@cotal-ai/auth 0.90.0 → 0.91.0

package/dist/service.js

@@ -62,7 +62,7 @@ import { resolve } from "node:path";
 import { connect, credsAuthenticator } from "@nats-io/transport-node";
 import { jetstream, jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { CotalEndpoint, deprovisionAgent, isConcreteChannel, provisionAgentDurables, contractDigest, contractRefToHex, contractStoreContext, endpointToken, fetchContractArtifact, verifyClusterManifest, verifyClusterRoot, admissionBucket, admissionMediatorGrants, assertDerivedOwnerToken, assertLifecycleToken, assertValidOwnerToken, authorizeTrustedServeSnapshot, commitSiblingIssuance, credsClaims, EpEnvelopeError, ensureAuthorityStores, epAuthBucket, isReachable, jwtFromCreds, managedRetirementOpId, mintCreds, mintPublicUserJwt, newIdentity, newTakeoverId, observeHostedRunAttempt, openRecordsBucket, parseEndpointGate, parseServiceSpec, parseServiceStatus, rawDigest, parseSecretStoreIdentity, readCheckpointStatus, readRunAdmission, readRunRevocation, readRunRecord, readSvcRecordLeader, reconcileEndpointGate, replayRunJournal, sameSecretStoreIdentity, recordSpecKey, recordStatusKey, RECORD_KINDS, recordsBucket, remoteManagerActors, retirementFrontierStreams, runDriverCaller, serveIssuanceGateKv, standaloneConnectOpts, STANDING_RENEWABLE_TTL_SEC, withIssuerSession, acceptedReadGrant, actorLedgerSource, connectionAcceptedToken, importNativeSubjectPermissions, mintGeneration, parseActorLedgerSource, writeAcceptedRow, invokeCommand, resolveService, contractArtifactCanonicalBytes, DEV_OWNER, endpointRegistrationBarrier, mintLifecycleUid, principalKey, provisionEndpointGateOpen, publishContractArtifact, registerServiceInstance, registerServingInstance, epgateKey, isCasLoss } from "@cotal-ai/core";
+import { CotalEndpoint, deprovisionAgent, dlvDurable, dlvStream, dmDurable, dmStream, isConcreteChannel, provisionAgentDurables, contractDigest, contractRefToHex, contractStoreContext, endpointToken, fetchContractArtifact, verifyClusterManifest, verifyClusterRoot, admissionBucket, admissionMediatorGrants, assertDerivedOwnerToken, assertLifecycleToken, assertValidOwnerToken, authorizeTrustedServeSnapshot, commitSiblingIssuance, credsClaims, EpEnvelopeError, ensureAuthorityStores, epAuthBucket, isReachable, jwtFromCreds, managedRetirementOpId, mintCreds, mintPublicUserJwt, newIdentity, newTakeoverId, observeHostedRunAttempt, openRecordsBucket, parseEndpointGate, parseServiceSpec, parseServiceStatus, rawDigest, parseSecretStoreIdentity, readCheckpointStatus, readRunAdmission, readRunRevocation, readRunRecord, readSvcRecordLeader, reconcileEndpointGate, replayRunJournal, sameSecretStoreIdentity, recordSpecKey, recordStatusKey, RECORD_KINDS, recordsBucket, remoteManagerActors, retirementFrontierStreams, runDriverCaller, serveIssuanceGateKv, standaloneConnectOpts, STANDING_RENEWABLE_TTL_SEC, withIssuerSession, acceptedReadGrant, actorLedgerSource, connectionAcceptedToken, importNativeSubjectPermissions, mintGeneration, parseActorLedgerSource, writeAcceptedRow, invokeCommand, resolveService, contractArtifactCanonicalBytes, DEV_OWNER, endpointRegistrationBarrier, mintLifecycleUid, principalKey, provisionEndpointGateOpen, publishContractArtifact, registerServiceInstance, registerServingInstance, epgateKey, isCasLoss, sameManagedGrantCustody } from "@cotal-ai/core";
 import { findCotalRoot, loadManagerInstanceIdentity, userAuthStateDir, workspaceSecretStore, createAuthInstanceIdentity, loadAuthInstanceIdentity } from "@cotal-ai/workspace";
 import { decodeJwt } from "jose";
 import { deriveOwnerForIdpSubject, platformControlOwner } from "./derive.js";
@@ -85,6 +85,7 @@ import { validateRetainedManagedAgent } from "./continuity.js";
 import { reconstructRemoteManagerServeGrant, remoteManagerServeGrantFromCluster, remoteManagerSurface } from "./manager-contract.js";
 import { authorityBarrierGrants, authorityWriterGrants, openAuthorityClient, openSupervisedConnectReader, platformReadinessGrants, remoteManagerIssuerGrants, remoteManagerRegistrationProof, registrationExecutorGrants, servedRunRequestSubjects } from "./authority-client.js";
 import { authorizeConnectCredential } from "./connect-reader.js";
+import { chatAwareAclResolver, openChatSessionAuthority } from "./chat-session-authority.js";
 import { makeNativeIssuanceRecorder, pruneNativeIssuance } from "./native-issuance.js";
 import { ensureRootCredential } from "./root-credential.js";
 import { activateLifecycleAtUid, observeGate, openLifecycleRegistry, readLifecycleHeadForOperation } from "./lifecycle-registry.js";
@@ -100,13 +101,16 @@ import { serializedFor } from "./serialized.js";
 import { joinOrStartRetirement, openAuthAdminListener } from "./auth-admin.js";
 import { AUTH_SERVICE_ENDPOINT, authClusterArtifacts, authContractArtifactValues } from "./auth-service-contract.js";
 import { drainTargetForEndpoint, openAdmissionMediator } from "./admission-mediator.js";
-import { AGENT_BEARER_TTL_SEC, assertWithinSpawnerGrant, findInteractiveActor, findManagedActor, findActorUnified, grantManagedActor, ledgerAclResolver, ledgerActorSourceIsLive, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, revokeManagedActorAt, } from "./ledger.js";
+import { AGENT_BEARER_TTL_SEC, assertWithinSpawnerGrant, findInteractiveActor, findManagedActor, findActorUnified, ledgerAclResolver, ledgerActorSourceIsLive, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, revokeManagedActorIf, withManagedGrantTransaction, } from "./ledger.js";
 import { AUTH_PROVIDER_NAME, claimAuthInstanceIdentity, clearAuthServiceInfo, dataAccountAuth, loadCalloutAuth, loadIssuer, loadOwnerSecret, loadPinnedIdp, loadServiceKeys, saveAuthServiceInfo, spaceIssuer, } from "./store.js";
 /** JWKS max-age seconds — the cache contract's knob. Exported so a rotation tool can compute the
  *  retire floor (max-age + max bearer TTL) from it. */
 export const JWKS_MAX_AGE_SEC = 300;
 /** Loopback-only operator route used by `cotal actor grant/revoke` before rotating or deleting an interactive lifecycle. */
 export const INTERACTIVE_RETIRE_PATH = "/interactive-lifecycle/retire";
+/** The user-mode chat-session routes, on the loopback face (capability-gated) and the public face.
+ *  Each takes a fresh IdP proof; `bearer` and `retire` also take the session's holder proof. */
+export const CHAT_SESSION_PATHS = Object.freeze({ open: "/chat-session/open", bearer: "/chat-session/bearer", retire: "/chat-session/retire" });
 /** Loopback-only host route that finishes a managed lifecycle's terminal retirement after the host
  *  revoked its grant, when the remote manager that should have requested it is gone (#2070). */
 export const MANAGED_RETIRE_PATH = "/managed-lifecycle/retire";
@@ -147,6 +151,11 @@ const MANAGER_PIN_REMEDY = {
     agent: "name one with --manager-instance <instanceId>",
     wire: "name one as managerInstanceId",
 };
+/** An unpinned manager-caller selection that found no single live manager. It is raised only after
+ *  the exchange's credential verified, and it describes the caller's own owner, so it is not probing:
+ *  the exchange arms neither count it against the refused-exchange budget nor hide it behind 429. */
+class ManagerSelectionRefusal extends Error {
+}
 /** Package-internal policy step for the hosted retirement requester. The HTTP production door calls
  * this after deriving the owner and manager actors; broker-free smokes exercise the same decision. */
 export function authorizeRemoteManagerRetirement(args) {
@@ -222,6 +231,14 @@ async function supervisorGeneration(session, space, owner, instanceId, lifecycle
         throw new EpEnvelopeError("permission-denied", "platform supervisor accepted row names another owner or lifecycle");
     return accepted.ref;
 }
+function runtimeSelection(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new Error("auth-service runtime options must be an object");
+    const selection = options.interactiveManagerSelection;
+    if (selection !== undefined && selection !== "local-primary")
+        throw new Error('interactiveManagerSelection must be "local-primary" when present');
+    return selection;
+}
 /**
  * Open the authority plane — the PRODUCTION connect/exchange composition (exported so the live
  * deny-new smoke exercises exactly what the daemon runs). Boot order is the readiness contract:
@@ -251,6 +268,7 @@ async function openAuthAuthorityPlaneWithCustody(opts, onConnection) {
 }
 /** The body of the plane opener, which owns the unwind of a failed construction. */
 async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
+    const interactiveManagerSelection = runtimeSelection(opts);
     const { server, space, dataAccount, log } = opts;
     const standingTtl = opts.standingRenewableTtlSeconds ?? STANDING_RENEWABLE_TTL_SEC;
     if (!Number.isSafeInteger(standingTtl) || standingTtl < 5 || standingTtl > STANDING_RENEWABLE_TTL_SEC) {
@@ -430,11 +448,20 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
     unwind.push(() => authAdmin.close());
     const recordToolResultConsent = makeToolResultConsentRecorder(registryStores(registry).authKv, () => refuseIfFenced(), space);
     const fileArm = ledgerAuthorizeConnect(opts.dir);
+    // A chat principal (its alias is in the chat row space) is checked by the chat arm: its active
+    // row, its parent pin and its holder index. Every other principal by the grant-file arm.
+    const connectArm = async (t) => {
+        if (chat.isChatPrincipal(t.owner, t.act.actor))
+            await chat.authorizeConnect(t);
+        else
+            fileArm(t);
+    };
     // The callout's issuance evidence: create-only natkey row, then the connect authority re-read
-    // in the same stream before the minted JWT may leave.
+    // in the same stream before the minted JWT may leave. For a chat session this re-read is the
+    // post-sign fence: its own head and root credential, its parent pin and its holder index.
     const recordIssuance = makeNativeIssuanceRecorder(registry, async (t) => {
         refuseIfFenced();
-        fileArm(t);
+        await connectArm(t);
         await authorizeConnectCredential(reader.current(), t, Date.now);
     });
     // Expired evidence goes at boot (a failure refuses the open) and then on the plane's own timer;
@@ -556,6 +583,24 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
                 throw new Error(`manager instance ${instanceId} is ${verdict}`);
             return instanceId;
         }
+        // A trusted host may choose the local Manager up front for human defaults. Explicit pins
+        // above and managed-agent calls keep their existing selection; no remote is a substitute.
+        if (caller === "human" && interactiveManagerSelection === "local-primary") {
+            let local;
+            try {
+                local = loadLocalManager();
+            }
+            catch {
+                throw new Error("interactive local-primary manager identity could not be read");
+            }
+            if (!local)
+                throw new Error("interactive local-primary manager identity is absent");
+            const instanceId = assertLifecycleToken(local.instanceId, "managerInstanceId");
+            const verdict = await managerGate(owner, instanceId);
+            if (verdict !== "candidate")
+                throw new Error(`interactive local-primary manager instance ${instanceId} is ${verdict}`);
+            return instanceId;
+        }
         const { instances } = await listManagerInstances(owner);
         const remoteInstances = instances.filter((i) => i.placement === "remote").map((i) => i.instanceId);
         const remoteLive = instances.filter((i) => i.placement === "remote" && i.state === "candidate").map((i) => i.instanceId);
@@ -564,12 +609,12 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
         if (remoteLive.length === 1)
             return remoteLive[0];
         if (remoteLive.length > 1)
-            throw new Error(`manager-caller selection found ${remoteLive.length} live remote manager candidates for owner ${owner} (${remoteLive.join(", ")}); exactly one is required, so ${MANAGER_PIN_REMEDY[caller ?? "wire"]}`);
+            throw new ManagerSelectionRefusal(`manager-caller selection found ${remoteLive.length} live remote manager candidates for owner ${owner} (${remoteLive.join(", ")}); exactly one is required, so ${MANAGER_PIN_REMEDY[caller ?? "wire"]}`);
         if (remoteInstances.length > 0)
-            throw new Error(`the remote manager for owner ${owner} is unavailable (${remoteInstances.length} gate${remoteInstances.length === 1 ? "" : "s"}, none live); start one with \`cotal supervise\` and retry, as this call is never routed to the local manager`);
+            throw new ManagerSelectionRefusal(`the remote manager for owner ${owner} is unavailable (${remoteInstances.length} gate${remoteInstances.length === 1 ? "" : "s"}, none live); start one with \`cotal supervise\` and retry, as this call is never routed to the local manager`);
         if (localCandidate !== undefined)
             return localCandidate;
-        throw new Error(`manager-caller selection found no manager candidate for owner ${owner}`);
+        throw new ManagerSelectionRefusal(`manager-caller selection found no manager candidate for owner ${owner}`);
     };
     // Every authority operation refuses once the plane is fenced: a half-dead plane keeps NO face up.
     // AUDIENCE SPLIT (ux): these refusals reach a CONNECTING AGENT during the brief fence→exit
@@ -621,12 +666,94 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
         const creds = await mintCreds(issuerAuth(), newIdentity(), "deprovisioner", { deprovisionTarget: { principal: targetId, lifecycleUid, memberChannels } });
         await deprovisionAgent({ servers: server, space, targetId, lifecycleUid, memberChannels, creds });
     };
+    // A chat session's footprint (admission a7): its own bind-only DM and DELIVER durables and the
+    // read-ACL row the delivery daemon authorizes its history and durable joins from, written by a
+    // short-lived provisioner and read back on that same connection (part of a8).
+    const provisionChatFootprint = async ({ owner, actor, lifecycleUid, read }) => {
+        const identity = newIdentity();
+        let conn;
+        const provisioner = new CotalEndpoint({
+            space,
+            servers: server,
+            onConnection: (nc) => { conn = nc; onConnection?.(nc, `cotal:chat-provisioner:${space}`); },
+            channels: [],
+            creds: await mintCreds(issuerAuth(), identity, "provisioner"),
+            card: { id: identity.id, name: "provisioner", role: "provisioner", kind: "endpoint" },
+            registerPresence: false,
+            watchPresence: false,
+            watchChannels: false,
+            consume: false,
+        });
+        await provisioner.start();
+        try {
+            await provisionAgentDurables(provisioner, { owner, actor, lifecycleUid }, { subscribe: [], allowSubscribe: read });
+            if (conn === undefined)
+                throw new EpEnvelopeError("unavailable", "the chat provisioner connection is unavailable for the read-back", undefined, "unknown");
+            const jsm = await jetstreamManager(conn);
+            await jsm.consumers.info(dmStream(space), dmDurable(owner, actor, lifecycleUid));
+            await jsm.consumers.info(dlvStream(space), dlvDurable(owner, actor, lifecycleUid));
+            const acl = await provisioner.aclForOwner(principalKey(owner, actor).key, lifecycleUid);
+            if (acl === undefined || JSON.stringify(acl) !== JSON.stringify(read))
+                throw new EpEnvelopeError("unavailable", `the chat session's read-ACL row did not read back for ${lifecycleUid}`, undefined, "unknown");
+        }
+        finally {
+            await provisioner.stop();
+        }
+    };
+    const chat = openChatSessionAuthority({
+        space,
+        dir: opts.dir,
+        registry,
+        managerInstance: `auth-service:${space}`,
+        retireLifecycle: async ({ owner, actor, lifecycleUid, opId }) => {
+            const flight = joinOrStartRetirement(retirementFlights, barrierReg, { owner, actor, lifecycleUid, opId, frontierStreams: retirementFrontierStreams(space) }, retirement);
+            if (flight === undefined)
+                throw new EpEnvelopeError("conflict", `chat retirement operation ${opId} is already in flight for different coordinates`);
+            await flight;
+        },
+        provisionFootprint: provisionChatFootprint,
+        deprovisionFootprint: ({ owner, actor, lifecycleUid, memberChannels }) => deprovisionManagedFootprint(owner, actor, lifecycleUid, memberChannels),
+        now: Date.now,
+        log,
+    });
+    // One bounded chat sweep pass per interval. A failed pass is logged and the next one retries; it
+    // never fences the plane, because every chat authority decision re-reads its own records.
+    const chatSweepMs = opts.chatSweepMs ?? 60_000;
+    if (!Number.isSafeInteger(chatSweepMs) || chatSweepMs < 100 || chatSweepMs > 3_600_000)
+        throw new Error(`chatSweepMs must be an integer between 100 and 3600000 (got ${chatSweepMs})`);
+    let chatSweepTimer;
+    let chatSweepFlight = Promise.resolve();
+    const scheduleChatSweep = () => {
+        if (closing || fatalReason !== undefined)
+            return;
+        chatSweepTimer = setTimeout(() => {
+            chatSweepFlight = chat.sweepPass().catch((e) => {
+                if (!closing)
+                    log(`auth-plane: chat sweep pass failed: ${e instanceof Error ? e.message : String(e)}`);
+            }).then(scheduleChatSweep);
+        }, chatSweepMs);
+    };
+    const stopChatSweep = async () => { clearTimeout(chatSweepTimer); await chatSweepFlight; };
+    unwind.push(async () => { closing = true; await stopChatSweep(); });
+    scheduleChatSweep();
     return {
         authorizeConnect: async (t) => {
             refuseIfFenced();
-            fileArm(t);
+            await connectArm(t);
             await authorizeConnectCredential(reader.current(), t, Date.now);
         },
+        openChatSession: async (args) => {
+            refuseIfFenced();
+            return chat.admit(args);
+        },
+        chatSessionBearer: async (args) => {
+            refuseIfFenced();
+            return chat.exchange(args);
+        },
+        retireChatSession: async (args) => {
+            refuseIfFenced();
+            return chat.retire(args);
+        },
         recordIssuance: (i) => {
             refuseIfFenced();
             return recordIssuance(i);
@@ -691,11 +818,18 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             }, principal, claim);
         },
         retireInteractiveLifecycle: async (args) => {
-            refuseIfFenced();
-            const owner = assertDerivedOwnerToken(args.owner);
-            const actor = assertValidOwnerToken(args.actor);
-            const lifecycleUid = assertLifecycleToken(args.lifecycleUid);
-            const head = await readLifecycleHeadForOperation(barrierReg, owner, actor);
+            // Everything before the barrier only reads, so a refusal there retired nothing.
+            let owner, actor, lifecycleUid;
+            try {
+                refuseIfFenced();
+                owner = assertDerivedOwnerToken(args.owner);
+                actor = assertValidOwnerToken(args.actor);
+                lifecycleUid = assertLifecycleToken(args.lifecycleUid);
+            }
+            catch (e) {
+                throw notExecuted(e, "bad-request");
+            }
+            const head = await readLifecycleHeadForOperation(barrierReg, owner, actor).catch((e) => { throw notExecuted(e, "unavailable"); });
             if (head === undefined)
                 return { retired: false, lifecycleUid, notStarted: true };
             if (head.mapping.lifecycleUid !== lifecycleUid) {
@@ -704,7 +838,7 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
                 // An active/retiring foreign uid is different: the ledger and authority disagree, so fail.
                 if (head.mapping.state === "retired")
                     return { retired: false, lifecycleUid, notStarted: true };
-                throw new EpEnvelopeError("conflict", `interactive lifecycle retirement for "${owner}/${actor}" names ${lifecycleUid}, but the authority head is ${head.mapping.state} at ${head.mapping.lifecycleUid}`);
+                throw new EpEnvelopeError("conflict", `interactive lifecycle retirement for "${owner}/${actor}" names ${lifecycleUid}, but the authority head is ${head.mapping.state} at ${head.mapping.lifecycleUid}`, undefined, "not-executed");
             }
             if (head.mapping.state === "retired")
                 return { retired: true, lifecycleUid, alreadyRetired: true };
@@ -1152,31 +1286,48 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             const t = r.target;
             const subscribe = t.subscribe ?? [];
             const { lifecycleUid, row } = await serializedForAlias(opts.dir, owner, t.actor, async () => {
-                // The token digest names one enrollment. A held row with this request's digest is that
-                // enrollment retried, so it answers the same uid; any other held row is a lifecycle that
-                // still runs, and taking its grant would strand it.
-                const held = findManagedActor(opts.dir, owner, t.actor);
-                if (held !== undefined && held.tokenHash !== t.tokenHash)
-                    throw new EpEnvelopeError("conflict", `managed agent "${t.actor}" is enrolled at lifecycle ${held.lifecycleUid}; prepare that lifecycle's retirement before enrolling a successor`);
-                // A fresh uid is never one a retirement tombstoned, and only the host can make that promise.
-                const lifecycleUid = held?.lifecycleUid ?? mintLifecycleUid();
-                // The grant first: its envelope walk against the supervising actor refuses an over-wide
-                // request before any durable exists. A retry walks the held grant again: its spawner chain
-                // may have narrowed since the first answer, and provisioning would restore what it took away.
-                if (held !== undefined)
-                    assertWithinSpawnerGrant(opts.dir, held, "spawn");
-                const row = held ?? grantManagedActor(opts.dir, {
-                    owner,
-                    actor: t.actor,
-                    scope: t.capabilities ?? [],
-                    allowSubscribe: t.allowSubscribe ?? [],
-                    allowPublish: t.allowPublish ?? [],
-                    ...(t.role !== undefined ? { role: t.role } : {}),
-                    ...(t.label !== undefined ? { label: t.label } : {}),
-                    parent: principalKey(owner, r.actor).key,
-                    lifecycleUid,
-                    tokenHash: t.tokenHash,
+                // The custody this enrollment attests: the instance the authorized request names, checked
+                // against its current registration above. Never a field of the participant's target.
+                const custody = { kind: "remote-manager", instanceId: r.instanceId };
+                // ONE synchronous transaction for the read, the decision and the write, so an
+                // enrollment in another process (or a provider grant) cannot land between them.
+                const decided = withManagedGrantTransaction(opts.dir, (tx) => {
+                    const current = tx.read(owner, t.actor);
+                    const held = current?.kind === "managed-agent" ? current : undefined;
+                    // The token digest names one enrollment. A held row with this request's digest is that
+                    // enrollment retried, so it answers the same uid; any other held row is a lifecycle that
+                    // still runs, and taking its grant would strand it.
+                    if (held !== undefined && held.tokenHash !== t.tokenHash)
+                        throw new EpEnvelopeError("conflict", `managed agent "${t.actor}" is enrolled at lifecycle ${held.lifecycleUid}; prepare that lifecycle's retirement before enrolling a successor`);
+                    // A retry is this enrollment only if the held row records this exact custody. A row with
+                    // none, or with another, is never upgraded or adopted here.
+                    if (held !== undefined && (held.custody === undefined || !sameManagedGrantCustody(held.custody, custody)))
+                        throw new EpEnvelopeError("conflict", `managed agent "${t.actor}" is held at lifecycle ${held.lifecycleUid} under another custody; it was not adopted by this enrollment`);
+                    // A retry walks the held grant again: its spawner chain may have narrowed since the
+                    // first answer, and provisioning would restore what it took away.
+                    if (held !== undefined) {
+                        assertWithinSpawnerGrant(opts.dir, held, "spawn");
+                        return { lifecycleUid: held.lifecycleUid, row: held, wrote: false };
+                    }
+                    // A fresh uid is never one a retirement tombstoned, and only the host can make that
+                    // promise. The grant's envelope walk refuses an over-wide request before any durable exists.
+                    const lifecycleUid = mintLifecycleUid();
+                    const row = tx.grantManaged({
+                        owner,
+                        actor: t.actor,
+                        scope: t.capabilities ?? [],
+                        allowSubscribe: t.allowSubscribe ?? [],
+                        allowPublish: t.allowPublish ?? [],
+                        ...(t.role !== undefined ? { role: t.role } : {}),
+                        ...(t.label !== undefined ? { label: t.label } : {}),
+                        parent: principalKey(owner, r.actor).key,
+                        lifecycleUid,
+                        tokenHash: t.tokenHash,
+                        custody,
+                    });
+                    return { lifecycleUid, row, wrote: true };
                 });
+                const { lifecycleUid, row } = decided;
                 try {
                     const identity = newIdentity();
                     const provisioner = new CotalEndpoint({
@@ -1202,9 +1353,10 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
                 catch (e) {
                     // A retried enrollment's first answer may already have reached the participant, so its
                     // grant stays. A grant this call wrote gave the participant no uid, so it can never be
-                    // retired: it and any durable it got must go now.
-                    if (held === undefined) {
-                        revokeManagedActorAt(opts.dir, owner, t.actor, lifecycleUid);
+                    // retired: it and any durable it got must go now. The revoke removes only the row this
+                    // call wrote: same uid AND same custody, read under the grant lock.
+                    if (decided.wrote) {
+                        revokeManagedActorIf(opts.dir, owner, t.actor, { lifecycleUid, custody });
                         await deprovisionManagedFootprint(owner, t.actor, lifecycleUid, []).catch((err) => opts.log(`auth-service: refused enrollment of ${owner}/${t.actor} left durables at ${lifecycleUid}: ${err instanceof Error ? err.message : String(err)}`));
                     }
                     throw e;
@@ -1244,8 +1396,17 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
                 const row = findManagedActor(opts.dir, owner, actor);
                 if (row?.lifecycleUid === lifecycleUid) {
                     // Footprint before grant: while the row stands, a retry still knows which channels to purge.
+                    // The footprint work is async, so it runs outside the grant lock.
                     await deprovisionManagedFootprint(owner, actor, lifecycleUid, row.allowSubscribe.filter(isConcreteChannel));
-                    revokeManagedActorAt(opts.dir, owner, actor, lifecycleUid);
+                    // The decision and the write are one transaction: the row removed is the one read above
+                    // only if it still names this uid and the custody it carried then. A row written before
+                    // custody existed is removed by uid alone, as before.
+                    withManagedGrantTransaction(opts.dir, (tx) => {
+                        if (row.custody !== undefined)
+                            tx.revokeManagedIf(owner, actor, { lifecycleUid, custody: row.custody });
+                        else
+                            tx.revokeManagedAt(owner, actor, lifecycleUid);
+                    });
                 }
             });
             return {
@@ -1504,6 +1665,7 @@ async function buildAuthAuthorityPlane(opts, unwind, onConnection) {
             // for a later close retry; successful scanner teardown is not run a second time.
             closing = true;
             await stopPrune();
+            await stopChatSweep();
             const scannerFlight = closeScanners ??= (async () => {
                 await authAdmin?.close();
                 const results = await Promise.allSettled([reader.close(), recordsScanner.close(), scanner.close()]);
@@ -1604,19 +1766,8 @@ async function resumeOpenOperations(reg, evictPrincipal, retirement, log) {
         }
     }
 }
-/** Run the auth service. Flags: `--space` (required), `--server` (broker URL, required), `--port`
- *  (loopback HTTP port; default ephemeral). All persisted material must already exist (the
- *  provider's `prepareServer` ran at `cotal up`) — a missing piece is a fail-loud config error
- *  naming the fix, never a silent partial service; this daemon LOADS the four secret kinds and
- *  never generates them.
- *
- *  `store` is the hosted composition's injection point for the space's SECRET material (callout
- *  account, issuer keys, owner secret, service key projection) — when given, it is those kinds'
- *  ONLY source (no flag or path can point this daemon at other secret material; an absent key is
- *  the hard error below). Absent, the daemon composes the local workspace store over `.cotal/`.
- *  NON-SEAM state (the actor ledger, the IdP pin, the discovery file) still lives in the local
- *  state dir either way — hosting those is a later, separate seam. */
-export async function runAuthService(args, store) {
+/** Pure native daemon input validation, shared with its explicit service launch plan. */
+export function authServiceConfiguration(args) {
     const v = args.values;
     const space = v.space;
     if (!space)
@@ -1647,9 +1798,27 @@ export async function runAuthService(args, store) {
     const badFace = publicFace && checkPublicFace(publicFace);
     if (badFace)
         throw new Error(badFace);
+    return { space, server, port, publicFace };
+}
+/** Run the auth service. Flags: `--space` (required), `--server` (broker URL, required), `--port`
+ *  (loopback HTTP port; default ephemeral). All persisted material must already exist (the
+ *  provider's `prepareServer` ran at `cotal up`) — a missing piece is a fail-loud config error
+ *  naming the fix, never a silent partial service; this daemon LOADS the four secret kinds and
+ *  never generates them.
+ *
+ *  `store` is the hosted composition's injection point for the space's SECRET material (callout
+ *  account, issuer keys, owner secret, service key projection) — when given, it is those kinds'
+ *  ONLY source (no flag or path can point this daemon at other secret material; an absent key is
+ *  the hard error below). Absent, the daemon composes the local workspace store over `.cotal/`.
+ *  NON-SEAM state (the actor ledger, the IdP pin, the discovery file) still lives in the local
+ *  state dir either way — hosting those is a later, separate seam. */
+export async function runAuthService(args, store, options = {}) {
+    const interactiveManagerSelection = runtimeSelection(options);
+    const lifecycle = "root" in options ? options : undefined;
+    const { space, server, port, publicFace } = authServiceConfiguration(args);
     // The provider's space-scoped state dir for NON-SEAM material (ledger, IdP pin, discovery). The
     // layout fact is workspace-owned (userAuthStateDir); this daemon never touches `.cotal/auth/auth.json`.
-    const root = findCotalRoot();
+    const root = lifecycle?.root ?? findCotalRoot();
     const dir = userAuthStateDir(root, space);
     const secrets = store ?? workspaceSecretStore(root);
     // Scrub any stale discovery file FIRST — a dead prior daemon's entry must never satisfy a
@@ -1681,25 +1850,43 @@ export async function runAuthService(args, store) {
         // The CLI composition's local manager is this workspace root's persisted instance, re-read per
         // selection exactly as before. A hosted context passes no local manager at all.
         localManager: () => loadManagerInstanceIdentity(root, space),
+        ...(interactiveManagerSelection !== undefined ? { interactiveManagerSelection } : {}),
     });
     // All planes bound — NOW write the discovery file (its existence is the readiness signal).
     const { url, publicUrl, cap } = started.handle;
     saveAuthServiceInfo(dir, { url, pid: process.pid, cap, ...(publicUrl !== undefined ? { publicUrl } : {}) });
-    console.log(`✓ auth service up (space ${space}) - callout on ${server}, exchange/JWKS at ${url}${publicUrl !== undefined ? `, public exchange at ${publicUrl}` : ""}`);
+    if (!lifecycle?.quiet)
+        console.log(`✓ auth service up (space ${space}) - callout on ${server}, exchange/JWKS at ${url}${publicUrl !== undefined ? `, public exchange at ${publicUrl}` : ""}`);
     // The CLI wrapper, not the context, owns process signals and exit codes.
-    const stop = async () => {
+    let stopping;
+    const stop = () => stopping ??= (async () => {
         clearAuthServiceInfo(dir); // a dead service must not satisfy the next start's readiness poll
         try {
             await started.handle.close();
+            await lifecycle?.onClosed();
         }
         catch (e) {
-            console.error(`✗ auth-service: ${e.message} - exiting`);
+            console.error(lifecycle ? "✗ native auth-service shutdown did not confirm completion; custody was retained" : `✗ auth-service: ${e.message} - exiting`);
             process.exit(1);
         }
         process.exit(0);
-    };
+    })();
     process.on("SIGINT", () => void stop());
     process.on("SIGTERM", () => void stop());
+    if (lifecycle) {
+        try {
+            await lifecycle.onReady();
+        }
+        catch {
+            clearAuthServiceInfo(dir);
+            try {
+                await started.handle.close();
+                await lifecycle.onClosed();
+            }
+            catch { /* Unknown close keeps custody. */ }
+            throw new Error("the native auth-service startup receipt was not published; no new launch was retried");
+        }
+    }
     // A dropped broker connection is fatal-loud, not a zombie: the supervising `up`/`down` lifecycle
     // owns restarts, and a callout that silently stopped answering would hang every user connect.
     // A FENCED plane is equally fatal (SPEC 13.13): its scanners are no longer whole, every authority
@@ -1708,13 +1895,14 @@ export async function runAuthService(args, store) {
     const ended = await started.ended;
     clearAuthServiceInfo(dir);
     if (ended.kind === "fenced") {
-        console.error(`✗ auth-service: ${ended.cause} - exiting`);
+        console.error(lifecycle ? "✗ native auth-service authority was fenced; custody was retained" : `✗ auth-service: ${ended.cause} - exiting`);
         process.exit(1);
     }
     if (ended.cause !== undefined) {
-        console.error(`✗ auth-service: broker connection closed (${ended.cause}) - exiting`);
+        console.error(lifecycle ? "✗ native auth-service broker connection closed; custody was retained" : `✗ auth-service: broker connection closed (${ended.cause}) - exiting`);
         process.exit(1);
     }
+    await lifecycle?.onClosed();
     process.exit(0);
 }
 /** Start one account-scoped auth-service context. Every input is explicit: the state dir, the
@@ -1806,6 +1994,7 @@ async function startAuthContext(o) {
         dataAccount: { pub: keys.dataAccount.pub, signingSeed: keys.dataAccount.signingSeed },
         log: (l) => console.error(l),
         localManager: o.localManager,
+        ...(o.interactiveManagerSelection !== undefined ? { interactiveManagerSelection: o.interactiveManagerSelection } : {}),
         ...(o.standingRenewableTtlSeconds !== undefined ? { standingRenewableTtlSeconds: o.standingRenewableTtlSeconds } : {}),
     }, onConnection);
     let nc;
@@ -1839,7 +2028,9 @@ async function startAuthContext(o) {
             token: { key: issuer.localKeySet(), issuer: issuer.issuer },
             authorizeActor: plane.authorizeConnect,
             recordIssuance: plane.recordIssuance,
-            permissionsFor: calloutPermissions(ledgerAclResolver(dir), plane.authorizeManagerCaller, plane.verifySession, plane.issueUserCaller),
+            // A chat principal resolves from its closed row (the agent leaf, no role); every other
+            // principal from the grant ledger.
+            permissionsFor: calloutPermissions(chatAwareAclResolver(dir, ledgerAclResolver(dir)), plane.authorizeManagerCaller, plane.verifySession, plane.issueUserCaller),
             log: (l) => console.error(l),
         });
         // The subscription must be ON the broker before readiness is signaled — an `up` that recorded a
@@ -1854,6 +2045,7 @@ async function startAuthContext(o) {
             issuer,
             authorizeActor: ledgerAuthorizeGrant(dir),
             mintConnectCredential: plane.mintConnectCredential,
+            ...(idp.dmReaderAudience !== undefined ? { dmReaderAudience: idp.dmReaderAudience } : {}),
         });
         const cap = randomBytes(32).toString("hex"); // per-start exchange capability (rotates with the daemon)
         // Set once the public face binds. An enrolled child's bearer exchanges there without the
@@ -1900,6 +2092,9 @@ async function startAuthContext(o) {
             selectManagerInstance: plane.selectManagerInstance,
             listManagerInstances: plane.listManagerInstances,
             verifySession: plane.verifySession,
+            openChatSession: plane.openChatSession,
+            chatSessionBearer: plane.chatSessionBearer,
+            retireChatSession: plane.retireChatSession,
         };
         const loopback = createServer((req, res) => void handle(req, res, ctx));
         http = loopback;
@@ -2278,6 +2473,13 @@ class RequestBodyError extends Error {
         this.status = status;
     }
 }
+/** `e`, raised before any write, as a refusal that states so (SPEC 13.3). An envelope error keeps
+ *  its code; any other error takes `code`. */
+function notExecuted(e, code) {
+    return e instanceof EpEnvelopeError
+        ? new EpEnvelopeError(e.code, e.message, e.details, "not-executed")
+        : new EpEnvelopeError(code, e instanceof Error ? e.message : String(e), undefined, "not-executed");
+}
 function sendRequestError(res, e) {
     if (e instanceof RequestBodyError)
         return send(res, e.status, { error: e.message });
@@ -2306,13 +2508,16 @@ const ROUTES = new Map([
     [VERIFY_ENROLLMENT_PATH, handleVerifyManagedAgentEnrollment],
     [TOOL_RESULT_HUMAN_PROOF_PATH, handleToolResultHumanProof],
     [TOOL_RESULT_CONSENT_PATH, handleToolResultConsent],
+    [CHAT_SESSION_PATHS.open, (req, res, ctx) => handleChatSession(req, res, ctx, LOOPBACK_POLICY, "open")],
+    [CHAT_SESSION_PATHS.bearer, (req, res, ctx) => handleChatSession(req, res, ctx, LOOPBACK_POLICY, "bearer")],
+    [CHAT_SESSION_PATHS.retire, (req, res, ctx) => handleChatSession(req, res, ctx, LOOPBACK_POLICY, "retire")],
 ]);
 /** Route one HTTP request against the loopback route table. Errors are JSON `{ error }`. */
 async function handle(req, res, ctx) {
     try {
         const route = ROUTES.get(req.url ?? "");
         if (!route)
-            return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /manager-service-authority/verify-enrollment, /interactive-lifecycle/retire, /managed-lifecycle/retire" });
+            return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /manager-service-authority/verify-enrollment, /interactive-lifecycle/retire, /managed-lifecycle/retire, /chat-session/open, /chat-session/bearer, /chat-session/retire" });
         await route(req, res, ctx);
     }
     catch (e) {
@@ -2320,34 +2525,50 @@ async function handle(req, res, ctx) {
     }
 }
 const INTERACTIVE_RETIRE_KEYS = new Set(["owner", "actor", "lifecycleUid"]);
+/** The interactive retirement door. Every refusal before the barrier starts retired nothing and
+ *  answers `outcome: "not-executed"` (SPEC 13.3), with the plane's native `code` when the plane
+ *  raised it. A failure inside the barrier answers 400 with no outcome, which reads as unknown. */
 async function handleInteractiveLifecycleRetirement(req, res, ctx) {
+    const before = { outcome: "not-executed" };
     if (req.method !== "POST")
-        return send(res, 405, { error: "POST only" });
+        return send(res, 405, { error: "POST only", ...before });
     if (req.headers.origin !== undefined)
-        return send(res, 403, { error: "browser-origin requests are not served here" });
+        return send(res, 403, { error: "browser-origin requests are not served here", ...before });
     if (!/^application\/json\b/.test(req.headers["content-type"] ?? ""))
-        return send(res, 415, { error: "content-type must be application/json" });
+        return send(res, 415, { error: "content-type must be application/json", ...before });
     if (req.headers.authorization !== `Bearer ${ctx.cap}`)
-        return send(res, 401, { error: "missing/invalid exchange capability - interactive lifecycle retirement is a loopback operator action" });
+        return send(res, 401, { error: "missing/invalid exchange capability - interactive lifecycle retirement is a loopback operator action", ...before });
     const body = await readJsonBody(req);
     if (body === null || typeof body !== "object" || Array.isArray(body))
-        return send(res, 400, { error: "interactive lifecycle retirement needs { owner, actor, lifecycleUid }" });
+        return send(res, 400, { error: "interactive lifecycle retirement needs { owner, actor, lifecycleUid }", ...before });
     for (const key of Object.keys(body))
         if (!INTERACTIVE_RETIRE_KEYS.has(key))
-            return send(res, 400, { error: `interactive lifecycle retirement carries the unknown field "${key}"` });
+            return send(res, 400, { error: `interactive lifecycle retirement carries the unknown field "${key}"`, ...before });
     const raw = body;
     if (typeof raw.owner !== "string" || typeof raw.actor !== "string" || typeof raw.lifecycleUid !== "string")
-        return send(res, 400, { error: "interactive lifecycle retirement needs string { owner, actor, lifecycleUid }" });
-    const owner = assertDerivedOwnerToken(raw.owner);
-    const actor = assertValidOwnerToken(raw.actor);
-    const lifecycleUid = assertLifecycleToken(raw.lifecycleUid);
+        return send(res, 400, { error: "interactive lifecycle retirement needs string { owner, actor, lifecycleUid }", ...before });
+    let owner, actor, lifecycleUid;
+    try {
+        owner = assertDerivedOwnerToken(raw.owner);
+        actor = assertValidOwnerToken(raw.actor);
+        lifecycleUid = assertLifecycleToken(raw.lifecycleUid);
+    }
+    catch (e) {
+        return send(res, 400, { error: e instanceof Error ? e.message : String(e), ...before });
+    }
     const row = findInteractiveActor(ctx.dir, owner, actor);
     if (!row)
-        return send(res, 404, { error: `interactive actor "${owner}/${actor}" is not granted` });
+        return send(res, 404, { error: `interactive actor "${owner}/${actor}" is not granted`, ...before });
     if (row.lifecycleUid !== lifecycleUid)
-        return send(res, 409, { error: `interactive actor "${owner}/${actor}" is current at lifecycle ${row.lifecycleUid ?? "<missing>"}, not ${lifecycleUid}` });
-    const result = await ctx.retireInteractiveLifecycle({ owner, actor, lifecycleUid });
-    return send(res, 200, result);
+        return send(res, 409, { error: `interactive actor "${owner}/${actor}" is current at lifecycle ${row.lifecycleUid ?? "<missing>"}, not ${lifecycleUid}`, ...before });
+    try {
+        return send(res, 200, await ctx.retireInteractiveLifecycle({ owner, actor, lifecycleUid }));
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError && e.outcome === "not-executed")
+            return send(res, REFUSAL_STATUS[e.code] ?? 500, { error: e.message, code: e.code, outcome: e.outcome });
+        throw e;
+    }
 }
 /** The host's terminal step for a managed lifecycle whose remote manager is gone: the same request
  *  guards as the interactive door, but it requires the managed grant to be REVOKED first (the
@@ -2482,15 +2703,15 @@ async function handleVerifyManagedAgentEnrollment(req, res, ctx) {
 }
 /** Refuse a missing/invalid loopback capability, audited and counted in its own window (see
  *  BAD_CAP_PER_MIN): 401 with `reason` until the window is full, then 429. */
-function refuseCapability(res, ctx, reason) {
+function refuseCapability(res, ctx, reason, extra = {}) {
     const now = Date.now();
     while (ctx.badCaps.length && now - ctx.badCaps[0] > 60_000)
         ctx.badCaps.shift();
     ctx.badCaps.push(now);
     console.error("auth-service: rejected an exchange with a missing/invalid capability");
     if (ctx.badCaps.length > BAD_CAP_PER_MIN)
-        return send(res, 429, { error: "too many invalid-capability attempts - wait a minute and retry" });
-    send(res, 401, { error: reason });
+        return send(res, 429, { error: "too many invalid-capability attempts - wait a minute and retry", ...extra });
+    send(res, 401, { error: reason, ...extra });
 }
 /** The exchange body, shared by every face; `policy` says how this face proves and attributes the
  *  caller. Behavior on the loopback face is unchanged from the pre-route-table handler. */
@@ -2594,9 +2815,11 @@ async function handleExchange(req, res, ctx, policy) {
             return send(res, 200, { token, owner, exp, ...(selectedManagerInstanceId ? { managerInstanceId: selectedManagerInstanceId } : {}) });
         }
         catch (e) {
-            policy.recordFailure(ctx, peer);
             const reason = e instanceof Error ? e.message : String(e);
             console.error(`auth-service: refused an agent exchange: ${reason}`);
+            if (e instanceof ManagerSelectionRefusal)
+                return send(res, 401, { error: reason });
+            policy.recordFailure(ctx, peer);
             if (peerThrottled)
                 return send(res, 429, { error: "too many refused exchanges - wait a minute and retry" });
             return send(res, 401, { error: reason });
@@ -2629,14 +2852,103 @@ async function handleExchange(req, res, ctx, policy) {
     catch (e) {
         // A refused exchange (bad IdP token, ungranted actor, expired proof) is an AUTHENTICATED
         // denial with the reason — the client shows it to the operator verbatim.
-        policy.recordFailure(ctx, peer);
         const reason = e instanceof Error ? e.message : String(e);
         console.error(`auth-service: refused an exchange: ${reason}`);
+        if (e instanceof ManagerSelectionRefusal)
+            return send(res, 401, { error: reason });
+        policy.recordFailure(ctx, peer);
         if (peerThrottled)
             return send(res, 429, { error: "too many refused exchanges - wait a minute and retry" });
         return send(res, 401, { error: reason });
     }
 }
+/** Each chat-session route's CLOSED body: an unknown or missing field refuses before any read. */
+const CHAT_SESSION_FIELDS = {
+    open: { required: ["idpToken", "holderHash", "read", "post", "ttlSec"], optional: ["label"] },
+    bearer: { required: ["idpToken", "actor", "holderProof"], optional: [] },
+    retire: { required: ["idpToken", "actor", "lifecycleUid", "holderProof"], optional: [] },
+};
+/** HTTP status for a door refusal's native code; the body carries the code itself. */
+const REFUSAL_STATUS = {
+    "bad-request": 400, unauthenticated: 401, "permission-denied": 403, "not-found": 404, conflict: 409,
+    "failed-precondition": 412, "resource-exhausted": 429, unimplemented: 501, unavailable: 503,
+};
+/**
+ * The chat-session routes, on both faces. The owner is derived from a fresh IdP proof exactly as
+ * `/exchange` derives it; the body never names one. `open` admits, `bearer` exchanges the holder
+ * proof for one short bearer, `retire` retires. Every refusal answers `{ error, code, outcome }`:
+ * `not-executed` when nothing was written, `executed` when this request wrote before refusing, and
+ * `unknown` when a write may have landed (a retry with the SAME holder resolves it). The holder proof
+ * and the bearer never reach a log line.
+ */
+async function handleChatSession(req, res, ctx, policy, op) {
+    // Every answer before the dispatch is refused with nothing read or written.
+    const before = { outcome: "not-executed" };
+    if (req.method !== "POST")
+        return send(res, 405, { error: "POST only", code: "bad-request", ...before });
+    if (req.headers.origin !== undefined)
+        return send(res, 403, { error: "browser-origin requests are not served here", code: "permission-denied", ...before });
+    if (!/^application\/json\b/.test(req.headers["content-type"] ?? ""))
+        return send(res, 415, { error: "content-type must be application/json", code: "bad-request", ...before });
+    if (policy.requireCapability && (req.headers.authorization ?? "") !== `Bearer ${ctx.cap}`)
+        return refuseCapability(res, ctx, "missing/invalid exchange capability - read it from the space's auth-service.json", { code: "unauthenticated", ...before });
+    const peer = policy.peerKey(req);
+    const peerThrottled = policy.throttled(ctx, peer);
+    const body = await readJsonBody(req);
+    const malformed = (why) => send(res, 400, { error: `chat-session ${op}: ${why}`, code: "bad-request", ...before });
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return malformed("the body must be a JSON object");
+    const b = body;
+    const fields = CHAT_SESSION_FIELDS[op];
+    const extra = Object.keys(b).find((k) => !fields.required.includes(k) && !fields.optional.includes(k));
+    if (extra !== undefined)
+        return malformed(`unknown field "${extra}"`);
+    const missing = fields.required.find((k) => !Object.hasOwn(b, k));
+    if (missing !== undefined)
+        return malformed(`missing field "${missing}"`);
+    if (typeof b.idpToken !== "string" || b.idpToken === "")
+        return malformed("idpToken must be a non-empty string");
+    if (op === "open" && (typeof b.holderHash !== "string" || !Array.isArray(b.read) || !Array.isArray(b.post) || typeof b.ttlSec !== "number" || (b.label !== undefined && typeof b.label !== "string")))
+        return malformed("open takes { idpToken, holderHash: string, read: string[], post: string[], ttlSec: number, label?: string }");
+    if (op !== "open" && (typeof b.actor !== "string" || typeof b.holderProof !== "string" || (op === "retire" && typeof b.lifecycleUid !== "string")))
+        return malformed(op === "bearer" ? "bearer takes { idpToken, actor: string, holderProof: string }" : "retire takes { idpToken, actor: string, lifecycleUid: string, holderProof: string }");
+    // A refusal keeps the effect outcome its source stated; one that states none is unknown.
+    const refuse = (status, message, code, outcome = "unknown") => {
+        policy.recordFailure(ctx, peer);
+        console.error(`auth-service: refused a chat-session ${op}: ${message}`);
+        if (peerThrottled)
+            return send(res, 429, { error: "too many refused exchanges - wait a minute and retry", code: "resource-exhausted", outcome });
+        return send(res, status, { error: message, code, outcome });
+    };
+    let owner;
+    let idpExp;
+    try {
+        const verified = await verifyIdpToken(b.idpToken, ctx.bridgeIdp);
+        owner = deriveOwnerForIdpSubject(ctx.ownerSecret, ctx.bridgeIdp.issuer, verified.sub);
+        idpExp = verified.exp;
+    }
+    catch (e) {
+        return refuse(401, e instanceof Error ? e.message : String(e), "unauthenticated", "not-executed");
+    }
+    try {
+        if (op === "open")
+            return send(res, 200, await ctx.openChatSession({
+                owner, holderHash: b.holderHash, read: b.read, post: b.post, ttlSec: b.ttlSec,
+                ...(typeof b.label === "string" ? { label: b.label } : {}),
+            }));
+        if (op === "bearer") {
+            const minted = await ctx.chatSessionBearer({ owner, actor: b.actor, holderProof: b.holderProof, idpExp, issuer: ctx.issuer });
+            return send(res, 200, { token: minted.token, owner, exp: minted.exp });
+        }
+        return send(res, 200, await ctx.retireChatSession({ owner, actor: b.actor, lifecycleUid: b.lifecycleUid, holderProof: b.holderProof }));
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError)
+            return refuse(REFUSAL_STATUS[e.code] ?? 500, e.message, e.code, e.outcome ?? "unknown");
+        // Anything else came from a store, broker or file read partway through: its effect is unknown.
+        return refuse(503, e instanceof Error ? e.message : String(e), "unavailable", "unknown");
+    }
+}
 /** The signed-in person's own Manager instances, read-only, on both faces. The proof is the IdP JWT
  *  the human exchange verifies, and the owner is derived from it the same way, so a caller lists only
  *  its own owner's gates. A browser-origin request is refused as on every exchange route; an
@@ -2882,6 +3194,9 @@ function makePublicHandler(ctx, policy, bundle) {
         ["/exchange", (req, res, c) => handleExchange(req, res, c, policy)],
         ["/manager-service-authority", (req, res, c) => handleManagerServiceAuthority(req, res, c, policy)],
         ["/manager-instances", (req, res, c) => handleManagerInstances(req, res, c, policy)],
+        [CHAT_SESSION_PATHS.open, (req, res, c) => handleChatSession(req, res, c, policy, "open")],
+        [CHAT_SESSION_PATHS.bearer, (req, res, c) => handleChatSession(req, res, c, policy, "bearer")],
+        [CHAT_SESSION_PATHS.retire, (req, res, c) => handleChatSession(req, res, c, policy, "retire")],
         [
             "/.well-known/cotal-mesh",
             (req, res) => {
@@ -2914,7 +3229,7 @@ function makePublicHandler(ctx, policy, bundle) {
             try {
                 const route = routes.get(req.url ?? "");
                 if (!route)
-                    return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /.well-known/cotal-mesh" });
+                    return send(res, 404, { error: "unknown path - /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /chat-session/open, /chat-session/bearer, /chat-session/retire, /.well-known/cotal-mesh" });
                 await route(req, res, ctx);
             }
             catch (e) {