@cotal-ai/auth 0.65.0 → 0.67.0

package/dist/service.js

@@ -32,9 +32,9 @@
  * the public face is the credential itself: the human arm presents an EdDSA IdP JWT verified
  * against the pinned JWKS/issuer/audience; the agent arm presents an actorToken whose sha256 must
  * match a FRESH ledger row. Origin rejection, JSON-only bodies, the 64 KB bound, and no-CORS-ever
- * hold verbatim. Public views are channel-writer/channel-purger (admin-gated) and manager-caller
- * (instance-bound, with no added command scope). Other views stay loopback-only. The agent-secret
- * arm may request only manager-caller on either face;
+ * hold verbatim. Public views are channel-writer/channel-purger and the one-object transfer-writer
+ * (admin-gated) and manager-caller (instance-bound, with no added command scope). Other views stay
+ * loopback-only. The agent-secret arm may request only manager-caller on either face;
  * failures are bucketed per peer (`--exchange-trusted-proxy` opts into the last X-Forwarded-For
  * hop as the peer key; otherwise the socket remote address) in a bounded LRU, under a global
  * concurrent-admission cap and a hard request deadline — all of it pools SEPARATE from the
@@ -59,14 +59,14 @@ import { resolve } from "node:path";
 import { connect, credsAuthenticator } from "@nats-io/transport-node";
 import { jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { contractDigest, contractRefToHex, contractStoreContext, endpointToken, fetchContractArtifact, verifyClusterManifest, verifyClusterRoot, admissionBucket, admissionMediatorGrants, assertDerivedOwnerToken, assertLifecycleToken, assertValidOwnerToken, authorizeTrustedServeSnapshot, commitSiblingIssuance, credsClaims, EpEnvelopeError, ensureAuthorityStores, epAuthBucket, isReachable, jwtFromCreds, managedRetirementOpId, mintCreds, mintPublicUserJwt, newIdentity, observeHostedRunAttempt, openRecordsBucket, parseEndpointGate, parseServiceSpec, parseServiceStatus, rawDigest, parseSecretStoreIdentity, readCheckpointStatus, readRunAdmission, readRunRecord, readSvcRecordLeader, reconcileEndpointGate, sameSecretStoreIdentity, recordSpecKey, recordStatusKey, RECORD_KINDS, recordsBucket, remoteManagerActors, retirementFrontierStreams, runDriverCaller, serveIssuanceGateKv, standaloneConnectOpts, STANDING_RENEWABLE_TTL_SEC, withIssuerSession, acceptedReadGrant, actorLedgerSource, connectionAcceptedToken, importNativeSubjectPermissions, mintGeneration, parseActorLedgerSource, writeAcceptedRow, authorizeServeGrant, invokeCommand, resolveService, contractArtifactCanonicalBytes, DEV_OWNER, endpointRegistrationBarrier, mintLifecycleUid, principalKey, provisionEndpointGateOpen, publishContractArtifact, registerServiceInstance, SERVICE_READY, writeServiceStatus } from "@cotal-ai/core";
+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, observeHostedRunAttempt, openRecordsBucket, parseEndpointGate, parseServiceSpec, parseServiceStatus, rawDigest, parseSecretStoreIdentity, readCheckpointStatus, readRunAdmission, readRunRecord, readSvcRecordLeader, reconcileEndpointGate, 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 } 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";
 import { makePlatformControlAuthority, makePlatformControlReadiness, requireManagerAuthorityHolder } from "./platform-control.js";
 import { startAuthCallout } from "./callout.js";
 import { createIdpBridge, verifyIdpToken } from "./idp.js";
-import { PUBLIC_EXCHANGE_VIEWS } from "./token.js";
+import { PUBLIC_EXCHANGE_VIEWS, assertTransferWriterClaim } from "./token.js";
 import { grantCoordinates, verifySessionRedemption } from "./session-redemption.js";
 import { pinnedJwksResolver } from "./issuer.js";
 import { calloutPermissions } from "./permissions.js";
@@ -93,7 +93,7 @@ import { makeDrainRepairers } from "./drain-repair.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, findInteractiveActor, findManagedActor, findActorUnified, ledgerAclResolver, ledgerActorSourceIsLive, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, } from "./ledger.js";
+import { AGENT_BEARER_TTL_SEC, assertWithinSpawnerGrant, findInteractiveActor, findManagedActor, findActorUnified, grantManagedActor, ledgerAclResolver, ledgerActorSourceIsLive, ledgerAuthorizeAgentExchange, ledgerAuthorizeConnect, ledgerAuthorizeGrant, revokeManagedActorAt, } from "./ledger.js";
 import { AUTH_PROVIDER_NAME, clearAuthServiceInfo, 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. */
@@ -123,6 +123,19 @@ const PUBLIC_MAX_IN_FLIGHT = 64; // global concurrent-admission cap on the publi
 const PUBLIC_DEADLINE_MS = 10_000; // hard wall-clock deadline per public request
 const HOST_FENCE_POLL_MS = 1_000; // how often awaitHostFence re-reads the host gate
 const OBSERVED_RUN_REQUEST_WINDOW_MS = 5 * 60_000; // how long an observed served resume or answer can still be forwarded
+/** Enrollment and retirement preparation of one managed agent run one at a time, so neither acts on
+ *  a grant the other is still writing or releasing. The chain lives at module level, keyed by the
+ *  ledger directory, so two plane instances over one ledger share it. */
+const MANAGED_ALIAS_CHAINS = new Map();
+const serializedForAlias = (dir, owner, actor, fn) => {
+    const key = `${resolve(dir)}:${principalKey(owner, actor).key}`;
+    const run = (MANAGED_ALIAS_CHAINS.get(key) ?? Promise.resolve()).then(fn, fn);
+    const tail = run.then(() => undefined, () => undefined);
+    MANAGED_ALIAS_CHAINS.set(key, tail);
+    void tail.then(() => { if (MANAGED_ALIAS_CHAINS.get(key) === tail)
+        MANAGED_ALIAS_CHAINS.delete(key); });
+    return run;
+};
 /** 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) {
@@ -152,9 +165,10 @@ function contractArtifactReader(values) {
  *  registration that advertises them. The issuance gate is provisioned open once, on first sight
  *  (§13.1); on a restart it already exists and `registerServiceInstance` freezes and re-registers
  *  it, which advances the process epoch and fences the predecessor. A first registration stays at
- *  epoch 0. It returns the epoch this registration committed, and refuses when its confirming read
+ *  epoch 0. `register` is {@link registerServiceInstance}, or {@link registerServingInstance} for an
+ *  instance that serves. It returns what `register` committed, and refuses when its confirming read
  *  finds that a later registration of the same instance superseded it. */
-async function registerSelfAuthorizedInstance(nc, args) {
+async function registerSelfAuthorizedInstance(nc, args, register) {
     const { space, endpoint, instanceId } = args;
     const authKv = await new Kvm(nc).open(epAuthBucket(space));
     const recordsKv = await new Kvm(nc).open(recordsBucket(space));
@@ -165,10 +179,11 @@ async function registerSelfAuthorizedInstance(nc, args) {
         await provisionEndpointGateOpen(authKv, { endpoint, instanceId, principal: args.principal });
     const barrier = endpointRegistrationBarrier(authKv, space, { endpoint, instanceId, opId: mintLifecycleUid() });
     const spec = { endpoint, owner: DEV_OWNER, clusterDigests: [args.clusterDigest], protocol: { v: 1 } };
-    const { registrationRevision, processEpoch } = await registerServiceInstance(recordsKv, {
+    const registered = await register(recordsKv, {
         space, spec, instanceId, registrant: { owner: DEV_OWNER }, authority: selfNameAuthority(endpoint), barrier,
         readClusterArtifact: contractArtifactReader(args.artifacts),
     });
+    const { registrationRevision, processEpoch } = registered;
     // A second start of the same instance can complete between this reopen and this read. Its epoch
     // is not this start's to claim, and this start's epoch is already fenced. One that completes after
     // the read leaves this start returning its own epoch, which the gate fences as it fences any
@@ -176,7 +191,7 @@ async function registerSelfAuthorizedInstance(nc, args) {
     const observed = await serveIssuanceGateKv(authKv, space, { endpoint, instanceId }).observe();
     if (observed?.state !== "open" || observed.processEpoch !== processEpoch || observed.registrationRevision !== registrationRevision)
         throw new EpEnvelopeError("conflict", `the issuance gate of ${endpoint}/${instanceId} is no longer open at this registration (process epoch ${processEpoch}, revision ${registrationRevision}); a later barrier fenced this start (SPEC 13.1)`);
-    return { authKv, recordsKv, registrationRevision, processEpoch };
+    return registered;
 }
 /**
  * Open the authority plane — the PRODUCTION connect/exchange composition (exported so the live
@@ -229,26 +244,11 @@ export async function openAuthAuthorityPlane(opts) {
             log,
         });
         try {
-            const { authKv, recordsKv, registrationRevision, processEpoch } = await registerSelfAuthorizedInstance(regClient.nc, {
+            const { grant } = await registerSelfAuthorizedInstance(regClient.nc, {
                 space, endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid,
                 principal: principalKey(DEV_OWNER, authIdentity.serveIdentity.id).key,
                 clusterDigest: artifacts.closureDigest, artifacts: values,
-            });
-            const readProcessEpoch = async () => {
-                const g = await serveIssuanceGateKv(authKv, space, { endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid }).observe();
-                if (g === null)
-                    throw new Error(`no issuance gate for ${AUTH_SERVICE_ENDPOINT}/${iid}`);
-                return g.processEpoch;
-            };
-            const grant = await authorizeServeGrant(recordsKv, {
-                space, endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid, epoch: processEpoch, holder: { owner: DEV_OWNER },
-                authority: selfNameAuthority(AUTH_SERVICE_ENDPOINT), readClusterArtifact: contractArtifactReader(values), readProcessEpoch,
-            });
-            await writeServiceStatus(recordsKv, {
-                endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid, epoch: processEpoch,
-                status: { state: SERVICE_READY, epoch: processEpoch, observedSpecRevision: registrationRevision },
-                readProcessEpoch,
-            });
+            }, registerServingInstance);
             authServeInstanceId = iid;
             authServeGrant = grant;
         }
@@ -590,6 +590,14 @@ export async function openAuthAuthorityPlane(opts) {
         observedRunRequests.delete(subject);
         return observed !== undefined && observed.expires > Date.now() ? observed.request : undefined;
     };
+    const observeManagerGate = async (instanceId) => serveIssuanceGateKv(await new Kvm(remoteIssuer.nc).open(epAuthBucket(space)), space, { endpoint: "manager", instanceId }).observe();
+    // A managed lifecycle's broker footprint, released under a deprovisioner pinned to that uid, so
+    // no call here can reach a same-name successor's durables.
+    const deprovisionManagedFootprint = async (owner, actor, lifecycleUid, memberChannels) => {
+        const targetId = principalKey(owner, actor).key;
+        const creds = await mintCreds(issuerAuth(), newIdentity(), "deprovisioner", { deprovisionTarget: { principal: targetId, lifecycleUid, memberChannels } });
+        await deprovisionAgent({ servers: server, space, targetId, lifecycleUid, memberChannels, creds });
+    };
     return {
         authorizeConnect: async (t) => {
             refuseIfFenced();
@@ -798,6 +806,13 @@ export async function openAuthAuthorityPlane(opts) {
                         });
                         return { credentials };
                     }
+                    if (r.operation === "transferReader") {
+                        const expectedProof = remoteManagerRegistrationProof(owner, r);
+                        if (r.registrationProof !== expectedProof)
+                            throw new EpEnvelopeError("permission-denied", "manager-service transfer reader proof does not match this owner/lifecycle");
+                        credentials.transferReader = await mintPublicUserJwt({ space, account: { pub: dataAccount.pub, signingSeed: dataAccount.signingSeed } }, r.transferReader.id, "transfer-reader", { principal: { owner, actor: actors.serve }, lifecycleUid: r.managerLifecycleUid, transferReader: { instanceId: r.instanceId } });
+                        return { credentials };
+                    }
                     if (r.operation === "retire") {
                         const expectedProof = remoteManagerRegistrationProof(owner, r);
                         if (r.registrationProof !== expectedProof)
@@ -881,7 +896,8 @@ export async function openAuthAuthorityPlane(opts) {
                         credentials.runMediator = await mintPublicUserJwt(auth, r.run.mediatorId, "run-mediator", {
                             principal: { owner, actor: caller.actor },
                             lifecycleUid: r.managerLifecycleUid,
-                            runMediator: binding,
+                            // Renewed with the placement the attempt was issued with (authorizeRemoteRunAttempt).
+                            runMediator: { ...binding, placement: { instanceId: r.instanceId } },
                             expiresInSeconds: standingTtl,
                         });
                         return { credentials };
@@ -1017,6 +1033,121 @@ export async function openAuthAuthorityPlane(opts) {
                 },
             });
         },
+        enrollManagedAgent: async ({ owner, scope, request, sentinelCreds, agentBearerExchangeUrl }) => {
+            refuseIfFenced();
+            const r = await authorizeRemoteManagedAgentEnrollment({ owner, scope, proofSecret: dataAccount.signingSeed, space, request, observeManagerGate });
+            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,
+                });
+                try {
+                    const identity = newIdentity();
+                    const provisioner = new CotalEndpoint({
+                        space,
+                        servers: server,
+                        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: t.actor, lifecycleUid }, { subscribe, allowSubscribe: row.allowSubscribe, role: row.role });
+                    }
+                    finally {
+                        await provisioner.stop();
+                    }
+                }
+                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);
+                        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;
+                }
+                return { lifecycleUid, row };
+            });
+            return {
+                v: 1,
+                kind: "manager-managed-agent-enrollment",
+                space,
+                owner,
+                actor: r.actor,
+                instanceId: r.instanceId,
+                managerLifecycleUid: r.managerLifecycleUid,
+                requestId: r.requestId,
+                registrationProof: r.registrationProof,
+                serveEpoch: r.serveEpoch,
+                material: {
+                    owner,
+                    actor: t.actor,
+                    lifecycleUid,
+                    sentinelCreds,
+                    subscribe,
+                    allowSubscribe: row.allowSubscribe,
+                    allowPublish: row.allowPublish,
+                    agentBearerExchangeUrl,
+                },
+            };
+        },
+        prepareManagedAgentRetirement: async ({ owner, scope, request }) => {
+            refuseIfFenced();
+            const r = await authorizeRemoteManagedAgentPrepareRetirement({ owner, scope, proofSecret: dataAccount.signingSeed, space, request, observeManagerGate });
+            const { actor, lifecycleUid } = r.target;
+            await serializedForAlias(opts.dir, owner, actor, async () => {
+                // Only a grant still at the target uid is this lifecycle's. A row at another uid belongs to a
+                // successor, and an absent row means an earlier attempt already released both halves.
+                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.
+                    await deprovisionManagedFootprint(owner, actor, lifecycleUid, row.allowSubscribe.filter(isConcreteChannel));
+                    revokeManagedActorAt(opts.dir, owner, actor, lifecycleUid);
+                }
+            });
+            return {
+                v: 1,
+                kind: "manager-managed-agent-prepare-retirement",
+                space,
+                owner,
+                actor: r.actor,
+                instanceId: r.instanceId,
+                managerLifecycleUid: r.managerLifecycleUid,
+                requestId: r.requestId,
+                target: r.target,
+                opId: r.opId,
+                prepared: true,
+            };
+        },
         verifyManagedAgentRuntime: async ({ owner, request }) => {
             refuseIfFenced();
             const args = {
@@ -1217,7 +1348,7 @@ export async function openAuthAuthorityPlane(opts) {
                     // The host is minted no serve credential, so the gate binds a principal nothing holds.
                     principal: principalKey(DEV_OWNER, `host_serve_${instanceId}`).key,
                     clusterDigest: host.clusterDigest, artifacts: host.artifacts,
-                })).processEpoch;
+                }, registerServiceInstance)).processEpoch;
             }
             finally {
                 await regClient.close();
@@ -1273,7 +1404,7 @@ async function resumeOpenOperations(reg, evictPrincipal, retirement, log) {
         // Owed by the gate: a freeze by THIS op is the barrier's live claim (the bar of every
         // barrier). A takeover completed under this predicate reopens the gate, so its completed
         // intent stays skipped exactly as before.
-        let owed = gate !== undefined && gate.row.state === "frozen" && gate.row.op?.opId === it.opId;
+        let owed = gate !== undefined && gate.row.state === "frozen" && gate.row.op.opId === it.opId;
         // #878: a retirement whose gate terminal landed by THIS op but whose head terminal did not.
         // The head decides the completed cell: `retired` at this uid means the barrier's last step ran
         // (skip), and a head at ANOTHER uid means a successor already replaced the retired predecessor
@@ -1281,7 +1412,7 @@ async function resumeOpenOperations(reg, evictPrincipal, retirement, log) {
         // the wedged crash window, and `active` at this uid is a backward head (impossible; a head
         // never un-retires) — both resume, so the barrier either finishes the tail or refuses loud; an
         // absent head is corruption the barrier refuses loud (a head is never deleted, SPEC 13.12).
-        if (!owed && it.kind === "retirement" && gate !== undefined && gate.row.state === "retired" && gate.row.op?.opId === it.opId) {
+        if (!owed && it.kind === "retirement" && gate !== undefined && gate.row.state === "retired" && gate.row.op.opId === it.opId) {
             const head = await readLifecycleHeadForOperation(reg, it.owner, it.actor);
             owed = head === undefined
                 || (head.mapping.lifecycleUid === it.lifecycleUid && head.mapping.state !== "retired");
@@ -1536,6 +1667,9 @@ async function startAuthContext(o) {
             mintConnectCredential: plane.mintConnectCredential,
         });
         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
+        // loopback capability, so enrollment needs that face.
+        let publicUrl;
         const failures = []; // rolling-window timestamps of REFUSED exchanges
         const badCaps = []; // rolling-window timestamps of invalid-capability attempts
         const ctx = {
@@ -1549,6 +1683,12 @@ async function startAuthContext(o) {
             verifyManagedAgentEnrollment: plane.verifyManagedAgentEnrollment,
             verifyManagedAgentPrepareRetirement: plane.verifyManagedAgentPrepareRetirement,
             verifyManagedAgentRuntime: plane.verifyManagedAgentRuntime,
+            enrollManagedAgent: (args) => {
+                if (publicUrl === undefined)
+                    throw new EpEnvelopeError("failed-precondition", "managed agent enrollment needs the public exchange face, where the enrolled agent's bearer exchanges - start the auth service with --exchange-public-port");
+                return plane.enrollManagedAgent({ ...args, sentinelCreds: callout.sentinelCreds, agentBearerExchangeUrl: publicUrl });
+            },
+            prepareManagedAgentRetirement: plane.prepareManagedAgentRetirement,
             scanManagerGoalIndex: plane.scanManagerGoalIndex,
             authorizeManagerAdmin: plane.authorizeManagerAdmin,
             admitManagerRun: plane.admitManagerRun,
@@ -1576,7 +1716,6 @@ async function startAuthContext(o) {
         const url = `http://127.0.0.1:${boundPort}`;
         // The optional PUBLIC face: its own server, its own closed route table, its own budgets — also
         // loopback-bound (the operator's reverse proxy terminates TLS and forwards here).
-        let publicUrl;
         if (o.publicFace !== undefined) {
             const face = o.publicFace;
             // The discovery bundle is GENERATED from the daemon's own recorded config — the pinned IdP,
@@ -1766,13 +1905,12 @@ export async function dispatchManagerAuthorityRequest(ctx, owner, body) {
     if (typeof request.actor !== "string")
         throw new Error("manager-service authority request requires an actor");
     const row = ledgerAuthorizeGrant(ctx.dir)(owner, request.actor);
-    // #1972: the managed-agent lifecycle operations mutate host storage (a database row, JetStream
-    // durables, a ledger grant), and stock holds none of that composition. A host platform intercepts
-    // these kinds on its own public route and calls the loopback verify-enrollment door for the
-    // decision. Refusing here keeps them from falling through to `managerServiceAuthority`, which
-    // would answer a manager-lifecycle phase for an agent-lifecycle request.
-    if (request.kind === "manager-managed-agent-enrollment" || request.kind === "manager-managed-agent-prepare-retirement")
-        throw new EpEnvelopeError("unimplemented", "managed agent enrollment and retirement preparation must be handled by host platform interception");
+    // #1972: this service owns the ledger and the space's provisioning authority, so it is the host
+    // that enrolls a remote manager's managed agent and prepares its terminal release.
+    if (request.kind === "manager-managed-agent-enrollment")
+        return ctx.enrollManagedAgent({ owner, scope: row.scope ?? [], request: body.request });
+    if (request.kind === "manager-managed-agent-prepare-retirement")
+        return ctx.prepareManagedAgentRetirement({ owner, scope: row.scope ?? [], request: body.request });
     // The hosted runtime kinds read and drive host-owned intent state that stock does not hold.
     if (request.kind === "manager-managed-agent-runtime-create" || request.kind === "manager-managed-agent-runtime-status")
         throw new EpEnvelopeError("unimplemented", "managed agent runtime create and status must be handled by host platform interception");
@@ -2125,9 +2263,11 @@ async function handleExchange(req, res, ctx, policy) {
     const peer = policy.peerKey(req);
     const peerThrottled = policy.throttled(ctx, peer);
     const body = await readJsonBody(req);
-    const { idpToken, actor, actorToken, owner, ttlSec, view, managerInstanceId, sessionGrant } = body;
+    const { idpToken, actor, actorToken, owner, ttlSec, view, managerInstanceId, sessionGrant, transferWriter } = body;
     if ((view === "session-caller") !== (sessionGrant !== undefined))
         return send(res, 400, { error: 'view "session-caller" and sessionGrant come together or not at all' });
+    if ((view === "transfer-writer") !== (transferWriter !== undefined))
+        return send(res, 400, { error: 'view "transfer-writer" and transferWriter come together or not at all' });
     if (ttlSec !== undefined && typeof ttlSec !== "number")
         return send(res, 400, { error: "ttlSec must be a number" });
     if (view !== undefined && typeof view !== "string")
@@ -2210,12 +2350,15 @@ async function handleExchange(req, res, ctx, policy) {
         // principal holds THAT redeemed session. The bridge's `verifySession` hook runs the decision on
         // the principal it derived, before signing; the callout re-runs it at the mint.
         const session = view === "session-caller" ? grantCoordinates(sessionGrant) : undefined;
+        if (transferWriter !== undefined)
+            assertTransferWriterClaim(transferWriter);
         const r = await ctx.bridge.exchange(idpToken, {
             actor,
             ttlSec,
             view: view,
             managerInstanceId: selectedManagerInstanceId,
             ...(session ? { verifySession: (p) => ctx.verifySession(p, session) } : {}),
+            ...(transferWriter !== undefined ? { transferWriter } : {}),
         });
         return send(res, 200, r);
     }