Report a seat whose bound credential the realm has refused

A seat whose bot key was invalidated kept answering bound from memory and
failed every write the same way for the life of the process. The adapter now
records the first 401 on any call made under the bound credential, the
events-queue poll included, and current_identity reports credential_rejected
without minting. A fresh bind clears it.

The seat does not re-acquire on its own: regenerating the key evicts any other
holder of the persona, so two colliding seats would rotate it against each
other until the persona is on attach mode.

Author: GraemeF

clients/claude-code/README.md

@@ -302,7 +302,7 @@ and history reads cover the browse case.
 | `get_channel_description` | Read a channel's standing description — the short statement of what it's for, which a project keeps as its charter. `{description}`, or `null` when nobody has set one. Channel-level state, so `read_channel` won't show it. |
 | `set_channel_description` | Set a channel's description, replacing whatever it says now; pass an empty string to clear it. Idempotent. What you write is read back verbatim — a description the substrate can't store as given (too long, or spanning multiple lines) is refused with an error saying which, never silently trimmed or reflowed. Fails with a clear error when the bound identity can't edit the channel. |
 | `presence` | Report presence (`online` / `idle` / `offline`) for a single identity. |
-| `current_identity` | Return `{state: 'bound', identity: {...}}` once acquire has resolved, or `{state: 'unbound', identity: null}` while a lazy ephemeral session is still lurking. Passive — never triggers acquire. |
+| `current_identity` | Return `{state: 'bound', identity: {...}}` once acquire has resolved, `{state: 'credential_rejected', identity: {...}, message}` once the realm has refused the bound key as invalid (writes fail and inbound events stop until the seat restarts), or `{state: 'unbound', identity: null}` while a lazy ephemeral session is still lurking. Passive — never triggers acquire. |
 | `resolve` | Look up an identity by name. |
 | `download_file` | Fetch a `/user_uploads/...` attachment to a temp file; returns `{file_path, content_type, size}`. Use the Read tool on the returned path to view images. |
 | `upload_file` | Upload a local file (absolute path) to the realm; returns `{reference, filename, size}`. The `reference` is a ready-to-embed string — drop it into a `post` body wherever you want the attachment to render, the same way you write `@**Name**` mention markup yourself. |

packages/core/ports.ts

@@ -505,6 +505,15 @@ export interface IdentityPort {
    * a programmer error, not a typed failure.
    */
   currentIdentity(): Effect.Effect<Identity, never>
+  /**
+   * Whether the realm has refused the bound credential as invalid since this
+   * adapter bound it. Passive: reads what earlier calls already learned and
+   * never touches the realm or mints. A rejected credential stays rejected
+   * until `release()` and a fresh `acquire`, because nothing else replaces
+   * it. Always `false` on a substrate with no credentials to invalidate, and
+   * `false` before any bind.
+   */
+  credentialRejected(): Effect.Effect<boolean, never>
   /**
    * Bind the adapter to an identity with the given display name. Per
    * substrate:

packages/mcp/server.test.ts

@@ -209,6 +209,7 @@ const buildFakeAdapter = (
   }
   const identityPort: IdentityPort = {
     currentIdentity: () => Effect.succeed(identity),
+    credentialRejected: () => Effect.succeed(false),
     acquire: (name) =>
       Effect.suspend(() => {
         events.push(`acquire(${name})`)

packages/mcp/tools.test.ts

@@ -346,6 +346,30 @@ test('current_identity returns the bound identity after ensureBound resolves', (
     ),
   ))
 
+test('current_identity reports credential_rejected once the realm has refused the bound key', () =>
+  Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const base = yield* rigAdapter()
+        const adapter: MemoryAdapterRig = {
+          ...base,
+          identity: { ...base.identity, credentialRejected: () => Effect.succeed(true) },
+        }
+        const deps = yield* buildDeps(adapter)
+        yield* deps.ensureBound()
+        const rig = yield* mountAndConnect(adapter, deps)
+        const expected = yield* adapter.identity.currentIdentity()
+        const result = yield* Effect.promise(() =>
+          rig.client.callTool({ name: 'current_identity', arguments: {} }),
+        )
+        expect(result.structuredContent).toMatchObject({
+          state: 'credential_rejected',
+          identity: { id: expected.id, name: expected.name, kind: expected.kind },
+        })
+      }),
+    ),
+  ))
+
 test('current_identity before acquire returns the unbound sentinel (passive, never triggers acquire)', () =>
   Effect.runPromise(
     Effect.scoped(

packages/mcp/tools.ts

@@ -274,6 +274,11 @@ type CurrentIdentityResult =
         readonly last_post_body: string
       }>
     }
+  | {
+      readonly state: 'credential_rejected'
+      readonly identity: SerializedIdentity
+      readonly message: string
+    }
   | { readonly state: 'unbound'; readonly identity: null }
 
 interface InternalCache extends ToolsMemory {
@@ -623,7 +628,7 @@ const buildToolDefs = (deps: RegisterToolsDeps, cache: InternalCache): ReadonlyA
     {
       name: 'current_identity',
       description:
-        'Return the identity this session is bound to. Passive — never triggers acquire. Returns {state: "unbound", identity: null} for ephemeral sessions that have not yet performed an attribution-producing action; {state: "bound", identity: {id, name, kind}, recent_threads?} once acquire has resolved. recent_threads is a best-effort orientation list of {channel, thread, last_post_ts, last_post_body} for the threads this identity most recently posted in; it is omitted when the enrichment lookup fails — the binding self-check itself never fails on it.',
+        'Return the identity this session is bound to. Passive — never triggers acquire. Returns {state: "unbound", identity: null} for ephemeral sessions that have not yet performed an attribution-producing action; {state: "bound", identity: {id, name, kind}, recent_threads?} once acquire has resolved; {state: "credential_rejected", identity, message} when the realm has refused the bound credential as invalid, so writes fail and inbound events stop until the seat restarts. recent_threads is a best-effort orientation list of {channel, thread, last_post_ts, last_post_body} for the threads this identity most recently posted in; it is omitted when the enrichment lookup fails — the binding self-check itself never fails on it.',
       inputSchema: {
         type: 'object',
         properties: { cwd: cwdField },
@@ -645,6 +650,14 @@ const buildToolDefs = (deps: RegisterToolsDeps, cache: InternalCache): ReadonlyA
           return { state: 'unbound', identity: null }
         }
         cache.rememberIdentity(current.identity)
+        if (await run(adapter.identity.credentialRejected())) {
+          return {
+            state: 'credential_rejected',
+            identity: identityShape(current.identity),
+            message:
+              "The realm has refused this seat's credential as invalid. Writes will keep failing and inbound events are not being delivered. Restart the seat to bind a fresh credential.",
+          }
+        }
         const bound = { state: 'bound' as const, identity: identityShape(current.identity) }
         try {
           const threads = await run(adapter.history.recentThreads(current.identity.id))

packages/memory/adapter.ts

@@ -388,6 +388,7 @@ export const memoryAdapter = (config: MemoryAdapterConfig = {}): Effect.Effect<M
 
     const identity: IdentityPort = {
       currentIdentity: () => readBound(),
+      credentialRejected: () => Effect.succeed(false),
       acquire: (name) =>
         Ref.get(bound).pipe(
           Effect.flatMap(

packages/zulip/adapter.test.ts

@@ -888,6 +888,62 @@ effectTest('publisher.post returns a MessageRef built from the response id', ()
   }),
 )
 
+const seedRefusedSend = (stub: StubHttpClient, response: StubResponse): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    yield* seedSendMessage(stub, 1)
+    yield* stub.respond('POST', '/api/v1/messages', response)
+  })
+
+effectTest('identity.credentialRejected is false until the realm refuses the bound key', () =>
+  Effect.gen(function* () {
+    const stub = yield* makeStubHttpClient
+    yield* seedRefusedSend(stub, {
+      body: { result: 'error', msg: 'Invalid API key', code: 'UNAUTHORIZED' },
+      status: 401,
+    })
+    const adapter = yield* buildAdapter(stub)
+    expect(yield* adapter.identity.credentialRejected()).toBe(false)
+    yield* Effect.flip(
+      adapter.publisher.post(generalChannel.name, decodeMessageBodySync('hello world')),
+    )
+    expect(yield* adapter.identity.credentialRejected()).toBe(true)
+  }),
+)
+
+effectTest(
+  'identity.credentialRejected stays false when the realm refuses a write for another reason',
+  () =>
+    Effect.gen(function* () {
+      const stub = yield* makeStubHttpClient
+      yield* seedRefusedSend(stub, {
+        body: { result: 'error', msg: 'Message too long', code: 'BAD_REQUEST' },
+        status: 400,
+      })
+      const adapter = yield* buildAdapter(stub)
+      yield* Effect.flip(
+        adapter.publisher.post(generalChannel.name, decodeMessageBodySync('hello world')),
+      )
+      expect(yield* adapter.identity.credentialRejected()).toBe(false)
+    }),
+)
+
+effectTest('identity.credentialRejected clears when the seat releases and binds again', () =>
+  Effect.gen(function* () {
+    const stub = yield* makeStubHttpClient
+    yield* seedRefusedSend(stub, {
+      body: { result: 'error', msg: 'Invalid API key', code: 'UNAUTHORIZED' },
+      status: 401,
+    })
+    const adapter = yield* buildAdapter(stub)
+    yield* Effect.flip(
+      adapter.publisher.post(generalChannel.name, decodeMessageBodySync('hello world')),
+    )
+    yield* adapter.identity.release()
+    yield* adapter.identity.acquire(decodeBotNameSync('hermes-agent'))
+    expect(yield* adapter.identity.credentialRejected()).toBe(false)
+  }),
+)
+
 /**
  * A `bindOnDemand` that counts its invocations and binds through the very
  * adapter it is configured on. The adapter cannot be referenced inside its own

packages/zulip/adapter.ts

@@ -107,6 +107,7 @@ import {
   ApiKey,
   BotEmail,
   decodeUserUploadPath,
+  isCredentialRejected,
   isTransientZulipError,
   makeZulipHttp,
   ZulipApiError,
@@ -624,6 +625,26 @@ export const zulipAdapter = (
       ),
     )
     const boundRef = yield* SynchronizedRef.make<Option.Option<BoundState>>(Option.none())
+    const credentialRejectedRef = yield* Ref.make(false)
+
+    // Every call the bound credential makes, the events-queue poll included,
+    // goes out through this, so the first refusal of the key itself is
+    // recorded wherever it happens rather than only when a write loses.
+    const recordRejection = <A, E, R>(call: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+      call.pipe(
+        Effect.tapError((e) =>
+          e instanceof ZulipApiError && isCredentialRejected(e)
+            ? Ref.set(credentialRejectedRef, true)
+            : Effect.void,
+        ),
+      )
+    const watchBoundHttp = (inner: BotHttp): BotHttp => ({
+      get: (path, schema, params) => recordRejection(inner.get(path, schema, params)),
+      post: (path, schema, body) => recordRejection(inner.post(path, schema, body)),
+      patch: (path, schema, body) => recordRejection(inner.patch(path, schema, body)),
+      delete: (path, schema, body) => recordRejection(inner.delete(path, schema, body)),
+      uploadRaw: (filename, data) => recordRejection(inner.uploadRaw(filename, data)),
+    })
 
     const requireBound = (): Effect.Effect<BoundState> =>
       SynchronizedRef.get(boundRef).pipe(
@@ -1157,6 +1178,7 @@ export const zulipAdapter = (
       // need a coherent error — dying matches the port
       // contract of "throws when unbound".
       currentIdentity: () => requireBound().pipe(Effect.map((b) => b.identity)),
+      credentialRejected: () => Ref.get(credentialRejectedRef),
       // check-bound -> mint -> set is one atomic SynchronizedRef transition:
       // the effectful mint round-trip runs while the ref is locked, so two
       // concurrent acquires can never both observe `none` and double-mint.
@@ -1196,7 +1218,9 @@ export const zulipAdapter = (
                         config.hostHeader,
                       ),
                     ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient))
-                    const http = wrapBotHttp(innerHttp, recipientDirectory, minted.userId)
+                    const http = watchBoundHttp(
+                      wrapBotHttp(innerHttp, recipientDirectory, minted.userId),
+                    )
                     const ident: Identity = {
                       id: yield* decodeIdentityId(String(minted.userId)),
                       name: yield* decodeDisplayName(name),
@@ -1216,6 +1240,7 @@ export const zulipAdapter = (
                       http,
                       origin: minted.origin,
                     }
+                    yield* Ref.set(credentialRejectedRef, false)
                     return [
                       { identity: ident, credentials, origin: minted.origin },
                       Option.some(next),

packages/zulip/http.ts

@@ -268,6 +268,13 @@ const classifyEnvelope = (
   })
 }
 
+/**
+ * Whether the realm refused the request's credential itself, as opposed to
+ * refusing the request. Zulip answers an invalidated or deactivated bot key
+ * with 401 and no other request failure.
+ */
+export const isCredentialRejected = (err: ZulipApiError): boolean => err.status === 401
+
 const TRANSPORT_FAILURE_STATUS = 0
 
 /**