@automatalabs/acp-agents 0.21.1 → 0.22.0

package/dist/errors-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors-map.d.ts","sourceRoot":"","sources":["../src/errors-map.ts"],"names":[],"mappings":"AAYA,OAAO,EAA0C,aAAa,EAAqB,MAAM,4BAA4B,CAAC;AACtH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,eAAO,MAAM,4BAA4B,SAAS,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAahD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,aAAa,CA4BvG"}
+{"version":3,"file":"errors-map.d.ts","sourceRoot":"","sources":["../src/errors-map.ts"],"names":[],"mappings":"AAYA,OAAO,EAA0C,aAAa,EAAqB,MAAM,4BAA4B,CAAC;AAEtH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,eAAO,MAAM,4BAA4B,SAAS,CAAC;AAQnD,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAahD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,aAAa,CAsCvG"}

package/dist/errors-map.js

@@ -12,6 +12,11 @@
 // AGENT_EMPTY_OUTPUT) pass through unchanged.
 import { classifyProviderLimit, isWorkflowError, WorkflowError, WorkflowErrorCode } from "@automatalabs/shared-types";
 export const ACP_AUTH_REQUIRED_ERROR_CODE = -32000;
+// JSON-RPC codes the SDK reserves for NON-auth failures (jsonrpc.js:764-829). A different reserved
+// code that merely mentions the auth phrase must NEVER mis-route to pause-for-auth. -32000 is
+// deliberately EXCLUDED — it is the primary auth code (reserved exclusively for authRequired,
+// jsonrpc.js:818-823) and is matched code-only above the fallback.
+const OTHER_RESERVED = new Set([-32700, -32600, -32601, -32602, -32603, -32800, -32002]);
 export function errorText(error) {
     if (error instanceof Error)
         return error.message;
@@ -38,9 +43,19 @@ export function mapThrownError(error, labelOrContext) {
     const context = typeof labelOrContext === "string" ? { label: labelOrContext } : (labelOrContext ?? {});
     const message = errorText(error);
     if (isAcpAuthRequired(error, message)) {
+        // authContext sources ONLY agent-advertised AuthMethod fields (ids/types/names) — never our
+        // sent _meta/env values (Principle 9). This is the machine-readable contract every downstream
+        // host reads; the enriched message is human-readable only.
+        const methods = (context.authMethods ?? []).map((m) => ({
+            id: m.id,
+            // AuthMethodAgent carries no `type` field (the SDK treats a missing discriminant as "agent").
+            type: ("type" in m ? m.type : undefined) ?? "agent",
+            name: m.name,
+        }));
         return new WorkflowError(authRequiredMessage(message, context), WorkflowErrorCode.AUTH_REQUIRED, {
             recoverable: false,
             agentLabel: context.label,
+            authContext: { backendId: context.backendId, methods },
             details: error,
         });
     }
@@ -55,8 +70,17 @@ export function mapThrownError(error, labelOrContext) {
     });
 }
 function isAcpAuthRequired(error, message) {
-    return (Boolean(error && typeof error === "object" && error.code === ACP_AUTH_REQUIRED_ERROR_CODE) &&
-        /^Authentication required\b/i.test(message));
+    const code = error?.code;
+    // PRIMARY (spec-faithful): -32000 is reserved EXCLUSIVELY for authRequired (jsonrpc.js:818-823;
+    // no other constructor in jsonrpc.js:764-829 emits it). Code alone, ANY message — this unblocks
+    // conformant agents that localize or rephrase the text.
+    if (code === ACP_AUTH_REQUIRED_ERROR_CODE)
+        return true;
+    // FALLBACK: a non-conformant agent that signals auth in prose without the reserved code. A
+    // DIFFERENT reserved code that merely mentions the phrase must NEVER mis-route to pause-for-auth.
+    return typeof code === "number"
+        ? !OTHER_RESERVED.has(code) && /\bauthentication required\b/i.test(message)
+        : /\bauthentication required\b/i.test(message);
 }
 function authRequiredMessage(message, context) {
     const backend = context.backendId ? ` (${context.backendId})` : "";

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
-export type { AcpRunnerOptions, AuthenticateOptions, AuthMethodsOptions, DisableProviderOptions, DeleteSessionOptions, ListProvidersOptions, ListSessionsOptions, LogoutOptions, ReattachSessionOptions, SetProviderOptions, } from "./runner.js";
+export type { AcpRunnerOptions, AuthenticateOptions, AuthMethodsOptions, AuthCapableRunner, AuthController, AuthOutcome, AuthStatusSnapshot, CompleteAuthOptions, DisableProviderOptions, DeleteSessionOptions, ListProvidersOptions, ListSessionsOptions, LogoutOptions, ReattachSessionOptions, SetProviderOptions, } from "./runner.js";
+export { buildAuthDescriptor, buildAuthDescriptors, isGatewayShapedMeta } from "./auth/auth-types.js";
+export type { AuthContext, AuthMethodDescriptor, AuthResolution, AuthResolver } from "./auth/auth-types.js";
+export { AuthStore, BackendAuthMachine, classifyCredential, redactSecrets, } from "./auth/auth-store.js";
+export type { AuthEvent, AuthIntent, AuthMethodType, BackendAuthState, ConnectionAuthStamp, CredentialClass, RedactedIntent, } from "./auth/auth-store.js";
+export { claudeAuthProfile, codexAuthProfile, opencodeAuthProfile } from "./auth/auth-profiles.js";
+export type { AuthProfile, TerminalLaunch } from "./auth/auth-profiles.js";
 export { InteractiveSession } from "./interactive.js";
 export type { InteractiveSessionOptions, InteractiveTurn } from "./interactive.js";
 export { AGENT_METHODS, CLIENT_METHODS } from "@agentclientprotocol/sdk";
@@ -8,8 +14,8 @@ export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from ".
 export type { BackendRegistry, CustomBackendConfig, RegisteredBackend } from "./registry.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
 export type { AcpSessionOptions, PooledConnectionDeps } from "./acp-client.js";
-export { AGENT_METHOD_COVERAGE, CLIENT_METHOD_COVERAGE } from "./protocol-coverage.js";
-export type { AgentMethodCoverage, ClientMethodCoverage } from "./protocol-coverage.js";
+export { AGENT_METHOD_COVERAGE, ACP_AUTH_REQUIRED_CODE_EXCLUSIVE, AUTH_CAPABILITY_KEYS, AUTH_META_CONVENTION_KEYS, AUTH_META_MATRIX, CLIENT_METHOD_COVERAGE, CODEX_SPAWN_AUTH_ENV, HANDLED_AUTH_METHOD_TYPES, assertAuthCapabilityShape, } from "./protocol-coverage.js";
+export type { AgentMethodCoverage, AuthMetaMatrixRow, ClientMethodCoverage } from "./protocol-coverage.js";
 export { GATED_CUSTOM_META_KEYS, adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 export type { NegotiatedCapabilities } from "./capabilities.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
@@ -23,8 +29,8 @@ export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";
 export { OpenCodeBackend } from "./backends/opencode.js";
 export { CustomAcpBackend } from "./backends/custom.js";
-export { decidePermission } from "./permissions.js";
-export type { ElicitationResolver, PermissionResolver, ToolPolicy } from "./permissions.js";
+export { decidePermission, resolvePermission, withPersist } from "./permissions.js";
+export type { ElicitationResolver, PermissionPersist, PermissionResolution, PermissionResolver, ToolPolicy, } from "./permissions.js";
 export { UsageAccumulator } from "./usage.js";
 export type { AgentSessionRef, McpAcpServerConfig, McpServerConfig } from "@automatalabs/shared-types";
 export { toAnthropicJsonSchema, toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,12 +5,18 @@
 // @automatalabs/workflow-engine; the two siblings meet ONLY at AgentRunner, injected by the
 // @automatalabs/workflows facade (which mcp-server builds on) via createAcpRunner().
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
+// Type-driven auth contracts (§1.3) and the AuthStore lifecycle spine (§2).
+export { buildAuthDescriptor, buildAuthDescriptors, isGatewayShapedMeta } from "./auth/auth-types.js";
+export { AuthStore, BackendAuthMachine, classifyCredential, redactSecrets, } from "./auth/auth-store.js";
+// Per-agent auth profiles (§3): the pure-data adapters wired onto the built-in backends. Custom
+// backends supply none (conformance-by-absence, §3.5).
+export { claudeAuthProfile, codexAuthProfile, opencodeAuthProfile } from "./auth/auth-profiles.js";
 export { InteractiveSession } from "./interactive.js";
 export { AGENT_METHODS, CLIENT_METHODS } from "@agentclientprotocol/sdk";
 // The custom-backend registry: run ANY ACP agent as an agent() target.
 export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from "./registry.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
-export { AGENT_METHOD_COVERAGE, CLIENT_METHOD_COVERAGE } from "./protocol-coverage.js";
+export { AGENT_METHOD_COVERAGE, ACP_AUTH_REQUIRED_CODE_EXCLUSIVE, AUTH_CAPABILITY_KEYS, AUTH_META_CONVENTION_KEYS, AUTH_META_MATRIX, CLIENT_METHOD_COVERAGE, CODEX_SPAWN_AUTH_ENV, HANDLED_AUTH_METHOD_TYPES, assertAuthCapabilityShape, } from "./protocol-coverage.js";
 // ACP capability negotiation: parse/validate the initialize response and gate what the client
 // sends (custom `_meta` keys, MCP transports) on what the connected agent advertised.
 export { GATED_CUSTOM_META_KEYS, adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
@@ -24,7 +30,7 @@ export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";
 export { OpenCodeBackend } from "./backends/opencode.js";
 export { CustomAcpBackend } from "./backends/custom.js";
-export { decidePermission } from "./permissions.js";
+export { decidePermission, resolvePermission, withPersist } from "./permissions.js";
 export { UsageAccumulator } from "./usage.js";
 export { toAnthropicJsonSchema, toJsonSchema, toStrictJsonSchema } from "./schema-strict.js";
 export { extractValidated, findJsonBlock, parseFinalJson, resolveStructuredOutput, validateValue, } from "./structured-output.js";

package/dist/permissions.d.ts

@@ -12,6 +12,20 @@ export type PermissionResolver = (params: RequestPermissionRequest, ctx: AcpEven
  *  UNSTABLE/@experimental; this library deliberately exposes the SDK request/response types
  *  directly so regular SDK bumps and wire tests catch drift instead of freezing a local copy. */
 export type ElicitationResolver = (request: CreateElicitationRequest, context: AcpEventContext) => Promise<CreateElicitationResponse> | CreateElicitationResponse;
+/** Codex tool-approval persistence directive (codex-acp `dist/index.js:23952-23975`, §3.6). A
+ *  permission decision may ask the agent to REMEMBER the approval for the rest of the session
+ *  ("session") or permanently ("always"). It is echoed as `_meta.persist` on the RequestPermission
+ *  response; an agent WITHOUT the capability ignores the extra `_meta` (Principle 3 — no silent
+ *  unsupported surface). */
+export type PermissionPersist = "session" | "always";
+/** High-level permission decision (§3.6). Mirrors the spec's `PermissionResolution`: a host says
+ *  allow/deny and, on allow, MAY request persistence. `resolvePermission` maps it onto a concrete ACP
+ *  `RequestPermissionResponse` (option selection + the `_meta.persist` echo), so a host can drive
+ *  `onPermissionRequest` at this altitude instead of hand-building the SDK response. */
+export interface PermissionResolution {
+    outcome: "allow" | "deny";
+    persist?: PermissionPersist;
+}
 export interface ToolPolicy {
     /** Allow-list (agentType `tools`). When non-empty, a tool that matches NOTHING is denied. */
     allow?: string[];
@@ -21,7 +35,20 @@ export interface ToolPolicy {
      *  behavior. Explicit ACP session modes set this to "deny" unless a permission resolver is
      *  present, otherwise read-only/plan confinement can be bypassed by auto-approved escalations. */
     defaultOutcome?: "allow" | "deny";
+    /** Codex tool-approval persistence (§3.6): when the auto-responder ALLOWS a tool, echo this as
+     *  `_meta.persist` on the response so a capable agent remembers the approval. Ignored on deny and by
+     *  agents without the capability. */
+    persist?: PermissionPersist;
 }
 /** Decide the auto-response for one permission request given the tool policy. */
 export declare function decidePermission(request: RequestPermissionRequest, policy: ToolPolicy): RequestPermissionResponse;
+/** Stamp a persistence directive onto a permission response's top-level `_meta.persist` (§3.6). A
+ *  cancelled response, or an absent directive, is returned unchanged. Never mutates the input; a
+ *  non-secret structural echo, so it is safe to emit in events. */
+export declare function withPersist(response: RequestPermissionResponse, persist: PermissionPersist | undefined): RequestPermissionResponse;
+/** Map a high-level `PermissionResolution` (§3.6) onto a concrete ACP `RequestPermissionResponse` for
+ *  `request`: pick an allow/reject option of the requested polarity and, on allow, echo `_meta.persist`.
+ *  Falls back to CANCELLING when the agent offers no option of the requested polarity (the only way to
+ *  refuse a tool with no reject option) — identical to the auto-responder's contract. */
+export declare function resolvePermission(request: RequestPermissionRequest, resolution: PermissionResolution): RequestPermissionResponse;
 //# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAGzB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;wDAMwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,wBAAwB,EAChC,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE;;iGAEiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;sGAEkG;IAClG,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAsC3B"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAGzB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;wDAMwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,wBAAwB,EAChC,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE;;iGAEiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE;;;;4BAI4B;AAC5B,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD;;;wFAGwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;sGAEkG;IAClG,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC;;yCAEqC;IACrC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAwC3B;AAED;;mEAEmE;AACnE,wBAAgB,WAAW,CACzB,QAAQ,EAAE,yBAAyB,EACnC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,yBAAyB,CAG3B;AAED;;;yFAGyF;AACzF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,EACjC,UAAU,EAAE,oBAAoB,GAC/B,yBAAyB,CAM3B"}

package/dist/permissions.js

@@ -35,7 +35,29 @@ export function decidePermission(request, policy) {
         // remaining way to refuse a tool the server offers no reject option for.
         return { outcome: { outcome: "cancelled" } };
     }
-    return { outcome: { outcome: "selected", optionId: option.optionId } };
+    const response = { outcome: { outcome: "selected", optionId: option.optionId } };
+    // Echo the persistence directive (§3.6) only when the auto-responder ALLOWS; a denial persists nothing.
+    return wantAllow ? withPersist(response, policy.persist) : response;
+}
+/** Stamp a persistence directive onto a permission response's top-level `_meta.persist` (§3.6). A
+ *  cancelled response, or an absent directive, is returned unchanged. Never mutates the input; a
+ *  non-secret structural echo, so it is safe to emit in events. */
+export function withPersist(response, persist) {
+    if (!persist || response.outcome.outcome !== "selected")
+        return response;
+    return { ...response, _meta: { ...(response._meta ?? {}), persist } };
+}
+/** Map a high-level `PermissionResolution` (§3.6) onto a concrete ACP `RequestPermissionResponse` for
+ *  `request`: pick an allow/reject option of the requested polarity and, on allow, echo `_meta.persist`.
+ *  Falls back to CANCELLING when the agent offers no option of the requested polarity (the only way to
+ *  refuse a tool with no reject option) — identical to the auto-responder's contract. */
+export function resolvePermission(request, resolution) {
+    const wantAllow = resolution.outcome === "allow";
+    const option = pickOption(request.options, wantAllow);
+    if (!option)
+        return { outcome: { outcome: "cancelled" } };
+    const response = { outcome: { outcome: "selected", optionId: option.optionId } };
+    return wantAllow ? withPersist(response, resolution.persist) : response;
 }
 function candidateNames(request) {
     const decoration = [];

package/dist/pool.d.ts

@@ -3,6 +3,7 @@ import { PooledConnection, SessionHandle, type AcpSessionOptions } from "./acp-c
 import { type ClientHandlers } from "./client-handlers.js";
 import type { AcpEventSink } from "./events.js";
 import type { ElicitationResolver, PermissionResolver } from "./permissions.js";
+import type { AuthStore } from "./auth/auth-store.js";
 export interface AcpPoolOptions {
     /** Long-lived processes to keep PER backend. Default 1; falls back to AGENTPRISM_ACP_POOL_SIZE. */
     size?: number;
@@ -16,6 +17,16 @@ export interface AcpPoolDeps {
     permissionResolver?: PermissionResolver;
     elicitationResolver?: ElicitationResolver;
     advertiseElicitation?: boolean;
+    /** Initialize-time client auth advertisement (§1.2), forwarded to every PooledConnection.
+     *  Undefined omits the `auth` capability — the default-OFF baseline. */
+    authCapabilities?: {
+        terminal?: boolean;
+        gateway?: boolean;
+    };
+    /** The runner's single auth store (§2). When present, connection selection is generation-gated:
+     *  no session is ever opened on a connection whose applied intent-generation is stale. Undefined
+     *  => no gating, byte-identical to the pre-auth baseline. */
+    authStore?: AuthStore;
 }
 /** Resolve the per-backend pool size: explicit option wins, else env, else 1. Clamped to >= 1. */
 export declare function resolvePoolSize(option?: number): number;
@@ -41,6 +52,15 @@ export declare class AcpAgentPool {
      * double-book a connection.
      */
     private selectConnection;
+    /** Reconcile every live connection for a key to the current generation (§2.6). Stale-but-busy
+     *  connections are DRAINED (recycled on release), not disposed synchronously, so in-flight prompts
+     *  finish under the auth they started with. Never blocks. */
+    private reconcileStale;
+    /** Public: reconcile every live connection for a backend to the current generation (§2.6). Called
+     *  by the runner immediately after a host-completed auth so a subsequent run() lands current. */
+    recycle(poolKey: string): void;
+    /** Spawn a fresh pooled connection (a fresh process primes the current intent at initialize). */
+    private spawn;
     private connectionsFor;
     /** Evict a dead connection so it is never handed out again. */
     private drop;

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAKhF,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;6FAC6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAOzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAehF,2FAA2F;IACrF,eAAe,CACnB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EACzF,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACrD,OAAO,CAAC,aAAa,CAAC;IAezB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA4BxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAsB,MAAM,sBAAsB,CAAC;AAK1E,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;6FAC6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;4EACwE;IACxE,gBAAgB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7D;;iEAE6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAOzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAehF,2FAA2F;IACrF,eAAe,CACnB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EACzF,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACrD,OAAO,CAAC,aAAa,CAAC;IAezB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;iEAE6D;IAC7D,OAAO,CAAC,cAAc;IActB;qGACiG;IACjG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM9B,iGAAiG;IACjG,OAAO,CAAC,KAAK;IAgBb,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}

package/dist/pool.js

@@ -75,26 +75,68 @@ export class AcpAgentPool {
         // Pool identity: poolKey (id + spawn-config hash for custom backends) over bare id, so two
         // runs declaring the same NAME with different COMMANDS never share a process.
         const key = backend.poolKey ?? backend.id;
+        // Generation-gated selection (§2.6): reuse any idle live connection that is NOT stale,
+        // reconciling stale ones first. This is the mechanical proof that no session is served under
+        // stale auth. `existing` (not `machineFor`) so the default-OFF path never lazily creates a
+        // machine — undefined machine ⇒ nothing is ever stale, byte-identical to the pre-auth baseline.
+        const machine = this.deps.authStore?.existing(key);
         const connections = this.connectionsFor(key);
-        const live = connections.filter((c) => c.alive);
-        const idle = live.find((c) => c.activeSessions === 0);
+        if (machine)
+            this.reconcileStale(key, machine);
+        const usable = connections.filter((c) => c.alive && !c.recyclePending && !machine?.isStale(c.authStamp));
+        const idle = usable.find((c) => c.activeSessions === 0);
         if (idle)
             return idle;
-        if (live.length < this.size) {
-            this.installExitHook();
-            const connection = PooledConnection.create(backend, {
-                onDead: (dead) => this.drop(key, dead),
-                onEvent: this.deps.onEvent,
-                permissionResolver: this.deps.permissionResolver,
-                elicitationResolver: this.deps.elicitationResolver,
-                advertiseElicitation: this.deps.advertiseElicitation,
-                clientHandlers: this.clientHandlers,
-            });
-            connections.push(connection);
-            return connection;
+        if (usable.length < this.size)
+            return this.spawn(key, backend);
+        // At capacity with every usable connection busy: multiplex onto the least-loaded one.
+        return usable.length > 0
+            ? usable.reduce((least, c) => (c.activeSessions < least.activeSessions ? c : least))
+            : this.spawn(key, backend);
+    }
+    /** Reconcile every live connection for a key to the current generation (§2.6). Stale-but-busy
+     *  connections are DRAINED (recycled on release), not disposed synchronously, so in-flight prompts
+     *  finish under the auth they started with. Never blocks. */
+    reconcileStale(key, machine) {
+        for (const c of this.connectionsFor(key).filter((c) => c.alive)) {
+            if (!machine.isStale(c.authStamp))
+                continue;
+            if (c.canLiveReapply(machine) && c.activeSessions === 0) {
+                c.scheduleReapply(machine); // in-process: re-auth the idle connection live
+            }
+            else if (c.activeSessions === 0) {
+                void c.dispose(); // disk/spawn-env: recycle the idle process now
+                this.drop(key, c);
+            }
+            else {
+                c.markForRecycleWhenIdle(machine); // BUSY: drain, then recycle on release
+            }
         }
-        // At capacity with every connection busy: multiplex onto the least-loaded one.
-        return live.reduce((least, c) => (c.activeSessions < least.activeSessions ? c : least));
+    }
+    /** Public: reconcile every live connection for a backend to the current generation (§2.6). Called
+     *  by the runner immediately after a host-completed auth so a subsequent run() lands current. */
+    recycle(poolKey) {
+        if (this.disposed)
+            return;
+        const machine = this.deps.authStore?.existing(poolKey);
+        if (machine)
+            this.reconcileStale(poolKey, machine);
+    }
+    /** Spawn a fresh pooled connection (a fresh process primes the current intent at initialize). */
+    spawn(key, backend) {
+        this.installExitHook();
+        const connection = PooledConnection.create(backend, {
+            onDead: (dead) => this.drop(key, dead),
+            onEvent: this.deps.onEvent,
+            permissionResolver: this.deps.permissionResolver,
+            elicitationResolver: this.deps.elicitationResolver,
+            advertiseElicitation: this.deps.advertiseElicitation,
+            authCapabilities: this.deps.authCapabilities,
+            authStore: this.deps.authStore,
+            clientHandlers: this.clientHandlers,
+        });
+        this.connectionsFor(key).push(connection);
+        return connection;
     }
     connectionsFor(key) {
         let arr = this.byBackend.get(key);

package/dist/protocol-coverage.d.ts

@@ -1,4 +1,5 @@
 import { AGENT_METHODS, CLIENT_METHODS } from "@agentclientprotocol/sdk";
+import type { AuthCapabilities, AuthMethod, AuthMethodAgent, AuthMethodEnvVar, AuthMethodTerminal, ClientCapabilities } from "@agentclientprotocol/sdk";
 type ValueOf<T> = T[keyof T];
 type ClientMethod = ValueOf<typeof CLIENT_METHODS>;
 type AgentMethod = ValueOf<typeof AGENT_METHODS>;
@@ -12,5 +13,79 @@ export type AgentMethodCoverage = "driven" | "passthrough" | "guarded";
  *  and the passthrough remainder is nes/*, document/*, and mcp/message. */
 export declare const CLIENT_METHOD_COVERAGE: Record<ClientMethod, ClientMethodCoverage>;
 export declare const AGENT_METHOD_COVERAGE: Record<AgentMethod, AgentMethodCoverage>;
+/** Compile-time assertion primitive: `Expect<T>` only accepts `true`, so a `false` (drifted) SDK
+ *  shape is a type error at build time. */
+type Expect<T extends true> = T;
+/** `ClientCapabilities.auth` still exists and is typed as `AuthCapabilities` (§1.2 UNSTABLE pin). */
+export type _AuthKeyExists = Expect<"auth" extends keyof ClientCapabilities ? true : false>;
+/** `AuthCapabilities.terminal` is still the typed boolean gate §1.2 assigns to (no `as` cast). */
+export type _AuthTerminalIsBoolean = Expect<AuthCapabilities["terminal"] extends boolean | undefined ? true : false>;
+/** The exact property set SDK 1.2.1 types on `AuthCapabilities` (§1.2). The runtime tripwire below
+ *  asserts `clientCapabilitiesFor({ auth })` emits ONLY these keys, so a bump that widens/renames
+ *  the shape trips the coverage suite. */
+export declare const AUTH_CAPABILITY_KEYS: readonly string[];
+/** Runtime drift assertion (§4.6.4 item 1): every key on the advertised `ClientCapabilities.auth`
+ *  block is a pinned SDK-1.2.1 `AuthCapabilities` key. Throws on drift, tripping the build. A
+ *  `null`/absent `auth` (the default-OFF baseline) is vacuously conformant. Reads only structural
+ *  keys — never any advertised value — so it is secret-free. */
+export declare function assertAuthCapabilityShape(auth: ClientCapabilities["auth"]): void;
+/** The three `AuthMethod` variants the base dispatcher handles (`agent`/`terminal`/`env_var`, §1.3).
+ *  `agent` is the default when `type` is absent (`AuthMethodAgent` carries no `type`). */
+export declare const HANDLED_AUTH_METHOD_TYPES: readonly ["agent", "terminal", "env_var"];
+/** §4.6.4 item 3 — the SDK `AuthMethod` union is EXACTLY the three variants the dispatcher handles;
+ *  a fourth variant (a widened union) makes this `false` and fails `tsc`. */
+export type _AuthMethodUnionPinned = Expect<[
+    AuthMethod
+] extends [AuthMethodAgent | AuthMethodTerminal | AuthMethodEnvVar] ? true : false>;
+/** The `terminal`/`env_var` discriminants are still the literals the dispatcher branches on: the SDK
+ *  intersects the bare method type with `{ type: "…" }` in the `AuthMethod` union, so a dropped
+ *  discriminant makes `Extract` collapse to `never` and fails `tsc`. */
+export type _AuthMethodTerminalDiscriminant = Expect<[
+    Extract<AuthMethod, {
+        type: "terminal";
+    }>
+] extends [never] ? false : true>;
+export type _AuthMethodEnvVarDiscriminant = Expect<[
+    Extract<AuthMethod, {
+        type: "env_var";
+    }>
+] extends [never] ? false : true>;
+/** The cross-agent `_meta` key conventions the base layer keys on (§1 intro; recognized by literal
+ *  name, NOT SDK schema fields). `gateway` ⇒ in-process classification; `terminal-auth` ⇒ terminal
+ *  launch hint; `api-key` ⇒ codex's disk api-key `_meta`. */
+export declare const AUTH_META_CONVENTION_KEYS: {
+    readonly gateway: "gateway";
+    readonly terminalAuth: "terminal-auth";
+    readonly apiKey: "api-key";
+};
+/** The codex startup pre-auth env channel delivered by `codexAuthProfile.spawnAuthEnv` (§2.8/§3.3). */
+export declare const CODEX_SPAWN_AUTH_ENV: "DEFAULT_AUTH_REQUEST";
+/** JSON-RPC `-32000` is reserved EXCLUSIVELY for `authRequired` (SDK `jsonrpc.js:818-823`) — the
+ *  guarantee the code-only §1.5 matcher relies on (§4.6.4 item 5). */
+export declare const ACP_AUTH_REQUIRED_CODE_EXCLUSIVE: -32000;
+/** One row of the §3.6 full `_meta` support matrix, landed as executable data (not prose) so an
+ *  SDK/agent bump that changes a `_meta` surface trips the drift suite (§4.6.4 item 4). */
+export interface AuthMetaMatrixRow {
+    readonly agent: "claude" | "codex" | "opencode" | "all";
+    /** A stable literal that MUST still be present in the cited artifact/spec — the drift anchor. */
+    readonly capability: string;
+    /** Wire direction: A→C agent→client, C→A client→agent, C↔A both, — none, agent-internal. */
+    readonly direction: "A→C" | "C→A" | "C↔A" | "—" | "agent-internal";
+    readonly status: "supported-today" | "work-item";
+    /** Owning §/PR for a work item; omitted for supported-today rows. */
+    readonly owner?: string;
+    /** When set, the literal is asserted present in this backend's INSTALLED dist (claude/codex only;
+     *  opencode ships a compiled binary with no consumable source — §3.4, grounded by live-e2e). */
+    readonly distProbe?: "claude" | "codex";
+}
+/** The §3.6 auth `_meta` matrix as executable rows — the exact surfaces §4.6.4 item 4 enumerates
+ *  (claude gateway/terminal-auth, codex api-key/gateway/DEFAULT_AUTH_REQUEST, opencode terminal-auth),
+ *  plus the codex tool-approval `persist` and the cross-agent provider-env passthrough. Each
+ *  `capability` is a literal that MUST appear in spec §3.6; `docs-drift.test.ts` asserts that lockstep,
+ *  and (where `distProbe` is set) `protocol-coverage.test.ts` asserts the literal is still present in
+ *  the installed agent dist — so neither the spec nor an agent bump can silently drift a `_meta`
+ *  surface. OpenCode ships a compiled binary with no consumable source (§3.4), so its row has no dist
+ *  probe (grounded instead by the §4.6.3 live-e2e). */
+export declare const AUTH_META_MATRIX: readonly AuthMetaMatrixRow[];
 export {};
 //# sourceMappingURL=protocol-coverage.d.ts.map

package/dist/protocol-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-coverage.d.ts","sourceRoot":"","sources":["../src/protocol-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEzE,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAC7B,KAAK,YAAY,GAAG,OAAO,CAAC,OAAO,cAAc,CAAC,CAAC;AACnD,KAAK,WAAW,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,SAAS,CAAC;AACxD;kGACkG;AAClG,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;AAEvE;;;2EAG2E;AAC3E,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAe7E,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,WAAW,EAAE,mBAAmB,CA6B1E,CAAC"}
+{"version":3,"file":"protocol-coverage.d.ts","sourceRoot":"","sources":["../src/protocol-coverage.ts"],"names":[],"mappings":"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"}

package/dist/protocol-coverage.js

@@ -49,3 +49,61 @@ export const AGENT_METHOD_COVERAGE = {
     [AGENT_METHODS.document_did_save]: "passthrough",
     [AGENT_METHODS.document_did_focus]: "passthrough",
 };
+/** The exact property set SDK 1.2.1 types on `AuthCapabilities` (§1.2). The runtime tripwire below
+ *  asserts `clientCapabilitiesFor({ auth })` emits ONLY these keys, so a bump that widens/renames
+ *  the shape trips the coverage suite. */
+export const AUTH_CAPABILITY_KEYS = ["terminal", "_meta"];
+/** Runtime drift assertion (§4.6.4 item 1): every key on the advertised `ClientCapabilities.auth`
+ *  block is a pinned SDK-1.2.1 `AuthCapabilities` key. Throws on drift, tripping the build. A
+ *  `null`/absent `auth` (the default-OFF baseline) is vacuously conformant. Reads only structural
+ *  keys — never any advertised value — so it is secret-free. */
+export function assertAuthCapabilityShape(auth) {
+    if (auth == null)
+        return;
+    for (const key of Object.keys(auth)) {
+        if (!AUTH_CAPABILITY_KEYS.includes(key)) {
+            throw new Error(`ClientCapabilities.auth carries unpinned key "${key}" — the SDK AuthCapabilities shape drifted (§1.2/§4.6.4).`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Auth `AuthMethod.type` discriminant + cross-agent `_meta` convention drift tripwires
+// (§3.6 / §4.6.4 items 3–5). The base auth flow (§1) dispatches on `AuthMethod.type` plus a small,
+// fixed set of literal cross-agent `_meta` key names — NOT SDK schema fields. Pin both so a
+// `@agentclientprotocol/sdk` bump that widens the method union, or an agent bump that moves a `_meta`
+// surface, fails the build BEFORE release (bump-ACP-deps-every-release), never silently.
+// ---------------------------------------------------------------------------------------------
+/** The three `AuthMethod` variants the base dispatcher handles (`agent`/`terminal`/`env_var`, §1.3).
+ *  `agent` is the default when `type` is absent (`AuthMethodAgent` carries no `type`). */
+export const HANDLED_AUTH_METHOD_TYPES = ["agent", "terminal", "env_var"];
+/** The cross-agent `_meta` key conventions the base layer keys on (§1 intro; recognized by literal
+ *  name, NOT SDK schema fields). `gateway` ⇒ in-process classification; `terminal-auth` ⇒ terminal
+ *  launch hint; `api-key` ⇒ codex's disk api-key `_meta`. */
+export const AUTH_META_CONVENTION_KEYS = {
+    gateway: "gateway",
+    terminalAuth: "terminal-auth",
+    apiKey: "api-key",
+};
+/** The codex startup pre-auth env channel delivered by `codexAuthProfile.spawnAuthEnv` (§2.8/§3.3). */
+export const CODEX_SPAWN_AUTH_ENV = "DEFAULT_AUTH_REQUEST";
+/** JSON-RPC `-32000` is reserved EXCLUSIVELY for `authRequired` (SDK `jsonrpc.js:818-823`) — the
+ *  guarantee the code-only §1.5 matcher relies on (§4.6.4 item 5). */
+export const ACP_AUTH_REQUIRED_CODE_EXCLUSIVE = -32000;
+/** The §3.6 auth `_meta` matrix as executable rows — the exact surfaces §4.6.4 item 4 enumerates
+ *  (claude gateway/terminal-auth, codex api-key/gateway/DEFAULT_AUTH_REQUEST, opencode terminal-auth),
+ *  plus the codex tool-approval `persist` and the cross-agent provider-env passthrough. Each
+ *  `capability` is a literal that MUST appear in spec §3.6; `docs-drift.test.ts` asserts that lockstep,
+ *  and (where `distProbe` is set) `protocol-coverage.test.ts` asserts the literal is still present in
+ *  the installed agent dist — so neither the spec nor an agent bump can silently drift a `_meta`
+ *  surface. OpenCode ships a compiled binary with no consumable source (§3.4), so its row has no dist
+ *  probe (grounded instead by the §4.6.3 live-e2e). */
+export const AUTH_META_MATRIX = [
+    { agent: "claude", capability: "gateway", direction: "C↔A", status: "work-item", owner: "§1.2-§1.3/PR2-PR3", distProbe: "claude" },
+    { agent: "claude", capability: "terminal-auth", direction: "C↔A", status: "work-item", owner: "§1.2-§1.3/PR2-PR3", distProbe: "claude" },
+    { agent: "codex", capability: "api-key", direction: "A→C", status: "work-item", owner: "§1.3/PR3", distProbe: "codex" },
+    { agent: "codex", capability: "gateway", direction: "C↔A", status: "work-item", owner: "§1.2-§1.3/PR2-PR3", distProbe: "codex" },
+    { agent: "codex", capability: "DEFAULT_AUTH_REQUEST", direction: "C→A", status: "work-item", owner: "§3.3/PR7", distProbe: "codex" },
+    { agent: "codex", capability: "persist", direction: "C→A", status: "work-item", owner: "§3.6/PR7", distProbe: "codex" },
+    { agent: "opencode", capability: "terminal-auth", direction: "C↔A", status: "work-item", owner: "§1.2-§1.3/PR2-PR3" },
+    { agent: "all", capability: "provider env keys", direction: "C→A", status: "work-item", owner: "§2.8/§3.4/PR3" },
+];