@cotal-ai/auth 0.64.0 → 0.66.1

package/dist/service.js

@@ -59,7 +59,7 @@ 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 { contractRefToHex, contractStoreContext, 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";
@@ -78,7 +78,7 @@ import { authorizeRemoteManagerAdmin } from "./manager-admin-authorization.js";
 import { authorizeRemoteManagerMaintenance, completeRemoteManagerMaintenance } from "./manager-maintenance.js";
 import { validateRetainedManagedAgent } from "./continuity.js";
 import { reconstructRemoteManagerServeGrant, remoteManagerServeGrantFromCluster, remoteManagerSurface } from "./manager-contract.js";
-import { authorityBarrierGrants, authorityWriterGrants, openAuthorityClient, openSupervisedConnectReader, platformReadinessGrants, remoteManagerIssuerGrants, remoteManagerRegistrationProof, authRegistrationExecutorGrants, servedRunRequestSubjects } from "./authority-client.js";
+import { authorityBarrierGrants, authorityWriterGrants, openAuthorityClient, openSupervisedConnectReader, platformReadinessGrants, remoteManagerIssuerGrants, remoteManagerRegistrationProof, registrationExecutorGrants, servedRunRequestSubjects } from "./authority-client.js";
 import { authorizeConnectCredential } from "./connect-reader.js";
 import { ensureRootCredential } from "./root-credential.js";
 import { activateLifecycleAtUid, observeGate, openLifecycleRegistry, readLifecycleHeadForOperation } from "./lifecycle-registry.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. */
@@ -121,7 +121,21 @@ const PUBLIC_FAILED_PER_MIN = 30; // per-PEER refused-exchange window (rolling m
 const PUBLIC_PEER_BUCKETS_MAX = 1024; // bounded LRU of per-peer failure buckets
 const PUBLIC_MAX_IN_FLIGHT = 64; // global concurrent-admission cap on the public listener
 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) {
@@ -135,6 +149,50 @@ export function authorizeRemoteManagerRetirement(args) {
     if (args.gate.processEpoch !== args.serveEpoch)
         throw new EpEnvelopeError("conflict", `manager-service retirement serve epoch ${args.serveEpoch} is stale; current is ${args.gate.processEpoch}`);
 }
+/** The §13.9 name authority in static mode: the plane holds the space signing seed, so it
+ *  self-authorizes exactly one endpoint name for exactly DEV_OWNER, as the manager does for
+ *  "manager". */
+function selfNameAuthority(endpoint) {
+    return { authorize: (name, owner) => ({ authorized: name === endpoint && owner === DEV_OWNER, revision: 0 }) };
+}
+/** Each contract artifact by its §13.7 content digest. */
+function contractArtifactReader(values) {
+    const store = new Map(values.map((v) => [contractDigest(v), v]));
+    return (digest) => store.get(digest);
+}
+/** The §13.7 registration ceremony for one instance of an endpoint this plane self-authorizes, on
+ *  a connection scoped to that instance. The contract artifacts are published before the
+ *  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. `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, register) {
+    const { space, endpoint, instanceId } = args;
+    const authKv = await new Kvm(nc).open(epAuthBucket(space));
+    const recordsKv = await new Kvm(nc).open(recordsBucket(space));
+    const storeCtx = await contractStoreContext(nc, space);
+    for (const value of args.artifacts)
+        await publishContractArtifact(storeCtx, contractArtifactCanonicalBytes(value));
+    if ((await serveIssuanceGateKv(authKv, space, { endpoint, instanceId }).observe()) === null)
+        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 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
+    // restart's predecessor; no read can close that window.
+    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 registered;
+}
 /**
  * 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:
@@ -179,60 +237,18 @@ export async function openAuthAuthorityPlane(opts) {
         });
         const iid = authIdentity.instanceId;
         const artifacts = authClusterArtifacts();
-        const store = new Map([
-            [artifacts.rootDigest, artifacts.document],
-            [artifacts.closureDigest, artifacts.manifest],
-        ]);
-        const readClusterArtifact = (digest) => store.get(digest);
-        // §13.9 name authority, static mode: the auth plane holds the space signing seed, so it
-        // self-authorizes exactly its own name ("auth") for exactly DEV_OWNER — mirrors the manager's
-        // own self-authorization for "manager".
-        const authority = {
-            authorize: (name, owner) => ({ authorized: name === AUTH_SERVICE_ENDPOINT && owner === DEV_OWNER, revision: 0 }),
-        };
-        const servePrincipal = principalKey(DEV_OWNER, authIdentity.serveIdentity.id).key;
-        const registrationOpId = mintLifecycleUid();
+        const values = [...authContractArtifactValues(), artifacts.document, artifacts.manifest];
         const regClient = await openAuthorityClient({
             server, space, dataAccount, label: `cotal:auth-registration:${space}`,
-            grants: (id) => authRegistrationExecutorGrants(space, id, iid),
+            grants: (id) => registrationExecutorGrants(space, id, AUTH_SERVICE_ENDPOINT, iid),
             log,
         });
         try {
-            const authKv = await new Kvm(regClient.nc).open(epAuthBucket(space));
-            const recordsKv = await new Kvm(regClient.nc).open(recordsBucket(space));
-            // §13.7 contract-artifact publication BEFORE the registration that advertises the digests.
-            const storeCtx = await contractStoreContext(regClient.nc, space);
-            for (const value of [...authContractArtifactValues(), artifacts.document, artifacts.manifest])
-                await publishContractArtifact(storeCtx, contractArtifactCanonicalBytes(value));
-            // §13.1 pre-registration: the issuance gate, born open@gen0, provisioned ONCE on the FIRST
-            // registration. On a restart the gate already exists; `registerServiceInstance` below
-            // freezes + re-registers it (advancing the epoch).
-            if ((await serveIssuanceGateKv(authKv, space, { endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid }).observe()) === null)
-                await provisionEndpointGateOpen(authKv, { endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid, principal: servePrincipal });
-            const barrier = endpointRegistrationBarrier(authKv, space, { endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid, opId: registrationOpId });
-            const spec = { endpoint: AUTH_SERVICE_ENDPOINT, owner: DEV_OWNER, clusterDigests: [artifacts.closureDigest], protocol: { v: 1 } };
-            const { registrationRevision } = await registerServiceInstance(recordsKv, {
-                space, spec, instanceId: iid, registrant: { owner: DEV_OWNER }, authority, barrier, readClusterArtifact,
-            });
-            const fence = serveIssuanceGateKv(authKv, space, { endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid });
-            const observed = await fence.observe();
-            if (observed === null)
-                throw new Error(`the issuance gate for ${AUTH_SERVICE_ENDPOINT}/${iid} vanished after registration`);
-            const readProcessEpoch = async () => {
-                const g = await fence.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: observed.processEpoch,
-                holder: { owner: DEV_OWNER }, authority, readClusterArtifact, readProcessEpoch,
-            });
-            await writeServiceStatus(recordsKv, {
-                endpoint: AUTH_SERVICE_ENDPOINT, instanceId: iid, epoch: observed.processEpoch,
-                status: { state: SERVICE_READY, epoch: observed.processEpoch, observedSpecRevision: registrationRevision },
-                readProcessEpoch,
-            });
+            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,
+            }, registerServingInstance);
             authServeInstanceId = iid;
             authServeGrant = grant;
         }
@@ -574,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();
@@ -1001,6 +1025,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 = {
@@ -1188,6 +1327,29 @@ export async function openAuthAuthorityPlane(opts) {
             const rec = await readSvcRecordLeader(recordsJsm, space, recordSpecKey(RECORD_KINDS.svc, ["manager", instanceId]));
             return { registered: rec !== undefined && !("deleted" in rec), gate: gate ?? null };
         },
+        registerHostInstance: async (host, instanceId) => {
+            refuseIfFenced();
+            const regClient = await openAuthorityClient({
+                server, space, dataAccount, label: `cotal:host-registration:${space}`,
+                grants: (id) => registrationExecutorGrants(space, id, host.endpoint, instanceId),
+                log,
+            });
+            try {
+                return (await registerSelfAuthorizedInstance(regClient.nc, {
+                    space, endpoint: host.endpoint, instanceId,
+                    // 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,
+                }, registerServiceInstance)).processEpoch;
+            }
+            finally {
+                await regClient.close();
+            }
+        },
+        observeEndpointGate: async (endpoint, instanceId) => {
+            refuseIfFenced();
+            return await serveIssuanceGateKv(await new Kvm(remoteIssuer.nc).open(epAuthBucket(space)), space, { endpoint, instanceId }).observe();
+        },
         fenced,
         close: async () => {
             // Clean-close order (SPEC 13.13): the rail stops answering first, then scan-capable
@@ -1393,6 +1555,12 @@ export async function startAuthService(inputs) {
         throw new Error(`auth-service: port must be a port number, got ${port}`);
     if (inputs.platformControl !== undefined && typeof inputs.platformControl?.observeAssignment !== "function")
         throw new Error("auth-service: platformControl requires an observeAssignment function");
+    const host = inputs.platformControl?.host;
+    if (host !== undefined) {
+        endpointToken(host.endpoint);
+        if (!host.endpoint.includes("."))
+            throw new Error(`auth-service: platformControl.host.endpoint "${host.endpoint}" must be a reverse-DNS name; single-label names are reserved (SPEC 13.2)`);
+    }
     const badFace = inputs.publicFace && checkPublicFace(inputs.publicFace);
     if (badFace)
         throw new Error(badFace);
@@ -1491,6 +1659,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 = {
@@ -1504,6 +1675,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,
@@ -1531,7 +1708,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,
@@ -1593,6 +1769,7 @@ async function startAuthContext(o) {
         });
         const context = o.context ?? { accountPublicKey: keys.dataAccount.pub, lifecycleUid: "" };
         const platformControl = o.platformControl;
+        const host = platformControl?.host;
         // The human route's retained-validation composition, for the platform holder.
         const validateRetainedForHolder = async (holder, request) => {
             const retained = await plane.validateRetainedAgent({ ...holder, request });
@@ -1670,6 +1847,29 @@ async function startAuthContext(o) {
                     await plane.activateManagedLifecycle(target);
                 },
             } : {}),
+            ...(host !== undefined ? {
+                registerHostIncarnation: async (instanceId) => {
+                    refuseUnlessReady();
+                    return { instanceId, processEpoch: await plane.registerHostInstance(host, instanceId) };
+                },
+                observeHostGate: async (instanceId) => {
+                    refuseUnlessReady();
+                    return await plane.observeEndpointGate(host.endpoint, instanceId);
+                },
+                awaitHostFence: async (instanceId, processEpoch) => {
+                    if (!Number.isSafeInteger(processEpoch) || processEpoch < 0)
+                        throw new EpEnvelopeError("bad-request", `processEpoch must be a non-negative integer, got ${String(processEpoch)}`);
+                    // No runtime credential may create a consumer on the auth bucket (SPEC 13.9), so the
+                    // gate cannot be watched; the hook polls its leader-served read.
+                    for (;;) {
+                        refuseUnlessReady();
+                        const gate = await plane.observeEndpointGate(host.endpoint, instanceId);
+                        if (gate?.state !== "open" || gate.processEpoch !== processEpoch)
+                            return gate;
+                        await new Promise((r) => setTimeout(r, HOST_FENCE_POLL_MS));
+                    }
+                },
+            } : {}),
             readiness() {
                 if (state === "unavailable")
                     return { state, context, cause: cause ?? "auth-service context is unavailable" };
@@ -1697,13 +1897,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");