@cotal-ai/manager 0.60.0 → 0.62.0

package/dist/manager.js

@@ -4,11 +4,11 @@ import { hostname } from "node:os";
 import { credsAuthenticator } from "@nats-io/transport-node";
 import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { isAbsolute, join, dirname, resolve } from "node:path";
-import { CotalEndpoint, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, } from "@cotal-ai/core";
+import { CotalEndpoint, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, modelPolicyRefusal, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, } from "@cotal-ai/core";
 import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, createManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, isCustodialRuntime, requireRuntimeAdopt, requireRuntimeReap, RuntimeReapUnproven, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
-import { makeManagerEndpointEvictionEvidence, makeManagerEndpointEvictor, makeManagerEndpointHolderEvictor } from "./endpoint-evict.js";
+import { DELIVERY_ADMIN_BOOT_WAIT_MS, isUnansweredDeliveryAdmin, makeManagerEndpointEvictionEvidence, makeManagerEndpointEvictor, makeManagerEndpointHolderEvictor, untilDeliveryAdminAnswers } from "./endpoint-evict.js";
 import { makeManagerHolderLivenessProbe } from "./holder-liveness.js";
 import { GateReconcileRefused, reconcileEndpointGate } from "./reconcile-gate.js";
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts, parseLaunchSpec, persistLaunchSpec, readContinuityAssignment, writeContinuityAssignment } from "./launch.js";
@@ -70,6 +70,9 @@ const DELIVERY_ADMIN_RELOAD_TIMEOUT_MS = 15_000;
 /** A hard preservation stop should settle quickly. The manager still waits and reports a partial
  * cut rather than pretending a child is gone. Held in ManagerOptions so fake runtimes can shorten it. */
 const PRESERVE_STOP_TIMEOUT_MS = 10_000;
+/** How long a resume waits for a reaped orphan's principal to leave presence. Presence rows age
+ * out after their 6s TTL, so three TTLs covers a killed seat that never published its leave. */
+const ORPHAN_PRESENCE_CLEAR_MS = 20_000;
 /** How much of an `input` text is written to a seat's pty at a time. Comfortably under the 4096-byte
  * kernel input buffer, so a slice is never re-split at a boundary the manager did not choose: the
  * tail of an oversized write stays queued and swallows the submit key that follows it (issue #1649).
@@ -122,6 +125,17 @@ function retireOpId(lifecycleUid) {
  *  dash) — what {@link Manager.psOwnerFilter} returns for an unparseable caller so a malformed
  *  principal fail-closes to an empty `ps` instead of an unbounded one. */
 const NO_OWNER_MATCHES = "-no-owner-";
+/** A caught value's text for a refusal. A host-supplied store or callback may reject with any value,
+ *  including one whose `message` is a Symbol or whose `message` getter or `toString` throws, and the
+ *  refusal must still be returned, so the coercion to text runs inside the guard. */
+function rejectionText(e) {
+    try {
+        return String(e?.message ?? e);
+    }
+    catch {
+        return "an unreadable rejection";
+    }
+}
 /** Run the agent's bearer argv once, pre-launch — the end-to-end auth preflight (state dir, daemon,
  *  ledger row, secret). Its stderr is the provider command's operator-exact sentence; surface it
  *  verbatim as the spawn refusal. */
@@ -237,6 +251,14 @@ function isAbsentDeliveryAdmin(msg) {
         return false;
     return /no responders|\b503\b/i.test(msg);
 }
+/** The store challenge went UNANSWERED while a delivery daemon exists: the rail timed out, or it had
+ *  no responder while the lease row names a holder. Both are what a daemon that is starting or
+ *  re-acquiring its lease looks like, so manager boot waits them out (#871); a renewal pass still
+ *  refuses on the first one. A reply that does not decode was answered and is never this. */
+class DeliveryAdminUnanswered extends Error {
+}
+/** How long one store challenge waits for the delivery daemon's answer. */
+const STORE_CHALLENGE_TIMEOUT_MS = 5_000;
 /**
  * The agent supervisor: a long-lived mesh node that owns agent process lifecycle.
  * It serves control requests on the "manager" service and spawns/kills agents
@@ -275,6 +297,11 @@ export class Manager {
      *  the launch settles, so no other spawn can take it, but the ceiling counts that seat through
      *  `agents` and, if it frees young, its cooling stamp, never through the reservation (#906). */
     reservedLive = new Set();
+    /** Every numbered name {@link uniqueName} has issued. A suffix carries nothing but arrival order,
+     *  so reissuing a freed one would give a later principal the name an earlier one posted under, and
+     *  a reader of that name could not tell the two apart (#382). Never pruned in-process: one string
+     *  per numbered spawn. */
+    issuedNumberedNames = new Set();
     /** Expiry stamps (`startedAt + MIN_LIFETIME`) for slots that freed while still young — a
      *  count-only, lazily-pruned recycle floor (P4c). Pruned + summed into the ceiling gate. */
     cooling = [];
@@ -437,6 +464,10 @@ export class Manager {
     /** The complete boot task. stop() joins it after fencing static reconciliation, so a registration
      * already past an earlier shutdown check cannot finish after stop() returns. */
     startTask;
+    /** The one stop this manager runs, with the agent policy it was asked for. A stop takes seats out
+     *  of `agents` before they have exited, so a second teardown would find none and report success
+     *  while the first still waits on a live seat. */
+    stopTask;
     /** Held as an instance field so broker-owning smokes can compress the schedule without changing
      *  production semantics. It is never a fence expiry: the durable non-retired row stays authoritative. */
     staticReconcileRetryDelaysMs = STATIC_RECONCILE_RETRY_DELAYS_MS;
@@ -474,7 +505,8 @@ export class Manager {
      *  for release would otherwise move the row out from under a same-cached-revision CAS delete. */
     leaseRenewTask;
     /** Set at the top of `stop()`. `renewLease` returns at once once this is set, and its `gone` arm
-     *  does not re-acquire: a manager that is stopping never puts its own key back. */
+     *  does not re-acquire: a manager that is stopping never puts its own key back. It also closes the
+     *  lifecycle fence ({@link beginLifecycle}), so no spawn can launch a seat the stop never sees. */
     leaseStopping = false;
     /** The class-2 renewal owner's half-TTL schedule (D5 slice 5); armed only on auth meshes. */
     credRenewTimer;
@@ -585,9 +617,12 @@ export class Manager {
     get runtimeKind() {
         return this.runtime.kind;
     }
-    /** Whether a default process stop can drop manager-local custody without taking agents with it. */
-    get canSpareAgents() {
-        return this.runtime.kind !== "pty" || this.runtime.supportsRelease === true;
+    /** What a default process stop does with this manager's seats. `release` drops manager-local
+     *  custody and leaves every seat running. `stop` means this runtime keeps its PTYs inside the
+     *  manager process, so those seats close with it: the stop stops and deprovisions them, and still
+     *  releases every seat that can outlive it. */
+    get spareSeats() {
+        return this.runtime.kind !== "pty" || this.runtime.supportsRelease === true ? "release" : "stop";
     }
     /** Reattach this manager's runtime to a durable handle. Refuses by name when adopt is absent. */
     adoptRuntimeHandle(reference) {
@@ -890,8 +925,10 @@ export class Manager {
         // `reloadCreds` adoption on the delivery-admin rail, and persist the audit record doctor renders.
         if (this.auth) {
             // #1634: a space may be served by several managers, so ownership of the daemon's credential
-            // renewal is decided here rather than by being the only manager able to start.
-            await this.claimDaemonRenewalOwnership();
+            // renewal is decided here rather than by being the only manager able to start. #871: a daemon
+            // that is still binding or re-acquiring its lease leaves this challenge unanswered for a few
+            // seconds, so boot waits that out instead of exiting over a daemon about to answer.
+            await this.claimDaemonRenewalOwnership(DELIVERY_ADMIN_BOOT_WAIT_MS);
             // ARMED BEFORE the first remint, not after. That first `renewDaemonCreds()` re-signs through
             // the SecretStore, and a slow or contended store makes the one pass outlast the lease's
             // MANAGER_LEASE_TTL_MS. Arming afterwards leaves the whole first remint unprotected: the lease
@@ -1025,16 +1062,17 @@ export class Manager {
      *  daemon"), and only a row that is absent or holderless settles "absent", the state start()
      *  treats as not-yet-bound. An unreadable row (a failed read, or a key that exists but does not
      *  parse) is a genuine unknown and refuses fail-closed, like a hung rail. */
-    async daemonStoreRelation() {
+    async daemonStoreRelation(timeoutMs) {
         let reply;
         try {
-            reply = await this.ep.requestDeliveryAdmin("reloadStoreIdentity", {}, 5_000);
+            reply = await this.ep.requestDeliveryAdmin("reloadStoreIdentity", {}, timeoutMs);
         }
         catch (e) {
             const msg = e.message;
             if (isAbsentDeliveryAdmin(msg))
-                return this.absentByLeaseRow();
-            throw new Error(`could not challenge the delivery daemon's SecretStore: ${msg}`);
+                return this.absentByLeaseRow(isUnansweredDeliveryAdmin(e));
+            const failure = `could not challenge the delivery daemon's SecretStore: ${msg}`;
+            throw isUnansweredDeliveryAdmin(e) ? new DeliveryAdminUnanswered(failure) : new Error(failure);
         }
         if (!reply.ok)
             throw new Error(reply.error ?? "delivery daemon refused to name the SecretStore it reloads from");
@@ -1089,7 +1127,7 @@ export class Manager {
      *
      *  `deliveryLeaseHolder` swallows its read failures into `undefined`, which would fold case 2
      *  into case 3 — so this reads the entry directly and lets the read's own failure refuse. */
-    async absentByLeaseRow() {
+    async absentByLeaseRow(unanswered) {
         let entry;
         try {
             entry = await this.ep.readDeliveryLeaseEntry(Manager.DELIVERY_SHARD);
@@ -1099,9 +1137,11 @@ export class Manager {
                 `(${e.message}) - absence is undetermined, nothing reminted`);
         }
         const holder = entry?.info.holder;
-        if (holder !== undefined && holder !== "")
-            throw new Error(`the delivery-admin rail reported no responder while the delivery lease names a holder ` +
-                `(${holder}) - absence cannot be read off the rail alone, and nothing reminted`);
+        if (holder !== undefined && holder !== "") {
+            const refusal = `the delivery-admin rail reported no responder while the delivery lease names a holder ` +
+                `(${holder}) - absence cannot be read off the rail alone, and nothing reminted`;
+            throw unanswered ? new DeliveryAdminUnanswered(refusal) : new Error(refusal);
+        }
         return "absent";
     }
     /** Keep this manager's renewal lease alive between credential passes (#1634). The manager bucket
@@ -1135,7 +1175,7 @@ export class Manager {
      *     request, which is the #773 refusal the challenge exists to prevent.
      *
      *  A manager failing either test serves the space normally and skips only the daemon remint. */
-    async claimDaemonRenewalOwnership() {
+    async claimDaemonRenewalOwnership(waitMs = 0) {
         // EVERY refusal outcome drops a held lease, not only "divergent". The refusal paths THROW
         // (#1694: a non-holder answer, an unbindable answerer, an unreadable or holder-naming row on a
         // no-responder rail), and a thrown refusal caught by renewDaemonCreds would otherwise leave a
@@ -1144,7 +1184,9 @@ export class Manager {
         // Deciding here, inside the claim, is what keeps the release on the refusal path itself.
         let relation;
         try {
-            relation = await this.daemonStoreRelation();
+            // Only the read-only challenge is retried, so a wait that ends mid-attempt abandons a read,
+            // never the lease work below.
+            relation = await untilDeliveryAdminAnswers(waitMs, (requestMs) => this.daemonStoreRelation(requestMs(STORE_CHALLENGE_TIMEOUT_MS)), (reason, delayMs) => console.error(`! delivery-admin rail did not answer the store challenge (${reason}); retrying in ${delayMs / 1000}s`), (e) => e instanceof DeliveryAdminUnanswered);
         }
         catch (e) {
             if (this.daemonRenewalOwner)
@@ -1522,9 +1564,9 @@ export class Manager {
         }
     }
     /** Admit one lifecycle/control operation while active. The synchronous increment is the fence:
-     * preserveState flips state before its first await, so work is either counted or rejected. */
+     * preserveState and stop close it before their first await, so work is either counted or rejected. */
     beginLifecycle(resumeOperation = false) {
-        if (this.maintenanceState !== "active" || (this.resumeRequired && !resumeOperation))
+        if (this.leaseStopping || this.maintenanceState !== "active" || (this.resumeRequired && !resumeOperation))
             return undefined;
         this.lifecycleInFlight++;
         let released = false;
@@ -1558,6 +1600,8 @@ export class Manager {
         await new Promise((resolve) => this.lifecycleDrainWaiters.push(resolve));
     }
     maintenanceError() {
+        if (this.leaseStopping)
+            return "manager is stopping; new lifecycle/control work is fenced";
         if (this.resumeRequired)
             return `manager is waiting for resume attempt ${this.resumeAttemptId}; ordinary lifecycle/control work is fenced`;
         return `manager is in ${this.maintenanceState} mode; new lifecycle/control work is fenced`;
@@ -1895,15 +1939,15 @@ export class Manager {
             ...(backfillFloor !== undefined ? { backfillFloor } : {}),
         };
     }
-    /** Tear down every managed agent's footprint on an explicit destructive {@link stop}. A manager exit is
+    /** Tear down every managed agent's footprint on an explicit destructive {@link stop}, or only the
+     *  in-process seats a default stop cannot detach. A manager exit is
      *  a mass agent-exit, and without this its agents' footprints (creds files + `dm_`/`dlv_` durables + ACL
      *  rows) would orphan exactly as the per-agent exit path prevents. Hard-stop each child (an exit has no
      *  time for the graceful grace window) and AWAIT its deprovision — bounded per agent (`withTimeout`) and
      *  best-effort (`allSettled` + a loud log), so one slow/failed teardown can neither hang nor abort exit.
      *  The creds file is dropped even if the broker teardown fails (see {@link deprovision}). Deliberately
      *  touches NEITHER the lease NOR the endpoints — the caller owns those. */
-    async teardownManagedAgents() {
-        const managed = [...this.agents.values()];
+    async teardownManagedAgents(managed = [...this.agents.values()]) {
         const failures = [];
         for (const a of managed) {
             // Free the slot + hard-stop each; `stopHandle` is best-effort (never throws — see it), so one bad
@@ -1934,16 +1978,11 @@ export class Manager {
         if (failures.length)
             throw new Error(`manager shutdown could not prove every seat exited: ${failures.join("; ")}`);
     }
-    /** Drop only this manager's local custody handles. Validate the complete snapshot before releasing
-     * any handle so a non-detachable runtime cannot leave a partially detached manager behind. */
+    /** Drop this manager's local custody of every seat that can outlive it. A pty seat whose handle
+     *  cannot be released lives in this process and closes with it, so it is left for {@link stop} to
+     *  stop instead. */
     releaseManagedAgents() {
-        const managed = [...this.agents.values()];
-        const blocked = managed.filter((a) => a.handle.kind === "pty" && typeof a.handle.release !== "function");
-        if (blocked.length) {
-            return [
-                `manager shutdown cannot detach ${blocked.map((a) => `${a.name} (${a.handle.kind})`).join(", ")}: runtime handle does not support release`,
-            ];
-        }
+        const managed = [...this.agents.values()].filter((a) => !(a.handle.kind === "pty" && typeof a.handle.release !== "function"));
         const failures = [];
         for (const a of managed) {
             try {
@@ -1981,7 +2020,16 @@ export class Manager {
         if (failures.length)
             throw new Error(`manager preservation shutdown incomplete: ${failures.join("; ")}`);
     }
-    async stop(options = {}) {
+    /** Every call joins the first stop and settles with it. A call that asks for a different
+     *  `withAgents` is refused, since the running stop has already applied its own policy. */
+    stop(options = {}) {
+        const withAgents = options.withAgents === true;
+        this.stopTask ??= { withAgents, done: this.stopOnce(withAgents) };
+        if (this.stopTask.withAgents === withAgents)
+            return this.stopTask.done;
+        return Promise.reject(new Error(`manager is already stopping ${this.stopTask.withAgents ? "with" : "without"} its agents`));
+    }
+    async stopOnce(withAgents) {
         this.leaseStopping = true;
         this.staticReconcileStopping = true;
         const starting = this.startTask;
@@ -2007,14 +2055,22 @@ export class Manager {
         // still move the key's revision after we clear the timer, and releasing against a cached
         // revision it has since moved is a CAS the broker correctly refuses, silently, forever.
         await this.leaseRenewTask?.catch(() => { });
+        // A spawn admitted before the fence closed may still be launching. Its seat must be in the
+        // snapshot below, or it would outlive a stop that reported success.
+        await this.awaitLifecycleDrain();
         let releaseFailures = [];
         let seatFailure;
         try {
             if (this.maintenanceState === "active" && !this.resumeRequired) {
-                if (options.withAgents)
+                if (withAgents)
                     await this.teardownManagedAgents();
-                else
+                else {
+                    // An in-process seat cannot be detached from the process that is exiting, so the default
+                    // stop stops and deprovisions it as `withAgents` does instead of orphaning its footprint.
+                    const inProcess = [...this.agents.values()].filter((a) => a.handle.kind === "pty" && typeof a.handle.release !== "function");
                     releaseFailures = this.releaseManagedAgents();
+                    await this.teardownManagedAgents(inProcess);
+                }
             }
             else {
                 // A signal after a partial preservation must never fall back into destructive teardown.
@@ -2654,6 +2710,13 @@ export class Manager {
                         // A retired row affirms that no agent exists now, so it keeps the old `not-found`
                         // result. The changed refusal is reserved for durable NONTERMINAL state that contradicts
                         // the live-map miss and needs operator attention.
+                        //
+                        // A sibling's nonterminal row is not a contradiction: the name belongs to another
+                        // manager instance in this space. In a multi-manager space the class queue hands this
+                        // read to either instance, so a plain `not-found` here read the same as a name that
+                        // exists nowhere and a caller had no way to tell the two apart (#443).
+                        if (observed?.ownerInstanceId !== undefined)
+                            throw new EpEnvelopeError("failed-precondition", `the durable slot for "${name}" belongs to manager instance ${observed.ownerInstanceId}, not ${this.managerInstanceId} which answered; only that instance can act on it ${renderStaticSlotObservation(observed)}`, [observed]);
                         if (observed !== undefined && observed.slotPhase !== "retired")
                             throw new EpEnvelopeError("failed-precondition", `no live agent "${name}"; durable state contradicts absence ${renderStaticSlotObservation(observed)}`, [observed]);
                     }
@@ -3018,6 +3081,19 @@ export class Manager {
      *  dead auth plane. Every failure is returned as the refusal sentence, with the grant + files
      *  rolled back. */
     async provisionUserAgent(name, opts) {
+        if (opts.delegatedIntent) {
+            // startAgentActive refused a delegated launch on a manager without this callback.
+            const execute = this.remoteAuthority.executeDelegatedUserIntent;
+            const { intentId, owner } = opts.delegatedIntent;
+            // The hosted arm with the intent's execution in place of the holder's own enrollment: the
+            // spawning owner is the intent's, so its existing owner check refuses any other.
+            return this.enrollUserAgent(name, { ...opts, specOwner: owner }, async ({ target }) => {
+                const result = await execute({ intentId, operation: "launch", target: { actor: target.actor, tokenHash: target.tokenHash } });
+                if (result.operation !== "launch" || result.intentId !== intentId)
+                    throw new Error(`the host answered delegated intent ${intentId} with another execution`);
+                return result.material;
+            });
+        }
         if (this.remoteAuthority?.enrollManagedAgent)
             return this.enrollUserAgent(name, opts, this.remoteAuthority.enrollManagedAgent);
         const spawnerPr = opts.spawner ? parsePrincipalKey(opts.spawner) : null;
@@ -3176,6 +3252,8 @@ export class Manager {
             // Re-key the family onto the HOST's uid (SPEC 13.1 name-disjointness on the FS): the child's
             // credential paths must embed the uid its broker footprint carries, never the provisional one.
             files = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, name, material.lifecycleUid);
+            // From here the host holds a grant at that uid.
+            opts.onEnrolled?.({ owner: material.owner, lifecycleUid: material.lifecycleUid, files });
             if (files.actorToken !== staged.actorToken) {
                 await secrets.put(agentSecretKeyForFile(files.actorToken, this.space), actorToken);
                 await materializeSecretToFile(secrets, agentSecretKeyForFile(files.actorToken, this.space), files.actorToken);
@@ -3210,14 +3288,25 @@ export class Manager {
             // Shred every local secret this attempt materialized. The HOST's rows are the host's to
             // reconcile: a participant holds no writer, so it must not pretend to roll back a grant or a
             // durable it never authored. A retry with the same requestId re-enters the same enrollment.
+            // A failed removal joins the refusal instead of throwing, so every removal is attempted and
+            // the refusal still reaches the caller.
+            const unshredded = [];
+            const shred = async (what, remove) => {
+                try {
+                    await remove();
+                }
+                catch (err) {
+                    unshredded.push(`${what}: ${rejectionText(err)}`);
+                }
+            };
             for (const family of files.actorToken === staged.actorToken ? [staged] : [staged, files]) {
-                await secrets.delete(agentSecretKeyForFile(family.actorToken, this.space)).catch(() => { });
-                await secrets.delete(agentSecretKeyForFile(family.sentinelCreds, this.space)).catch(() => { });
-                rmSync(family.actorToken, { force: true });
-                rmSync(family.sentinelCreds, { force: true });
-                rmSync(family.health, { force: true });
+                for (const path of [family.actorToken, family.sentinelCreds])
+                    await shred(`secret ${path}`, () => secrets.delete(agentSecretKeyForFile(path, this.space)));
+                for (const path of [family.actorToken, family.sentinelCreds, family.health])
+                    await shred(`file ${path}`, () => rmSync(path, { force: true }));
             }
-            return { error: `agent auth preflight failed for "${name}": ${e.message}` };
+            const leftover = unshredded.length ? `; cleanup failed: ${unshredded.join("; ")}` : "";
+            return { error: `agent auth preflight failed for "${name}": ${rejectionText(e)}${leftover}` };
         }
     }
     /**
@@ -3325,7 +3414,7 @@ export class Manager {
         if (this.userMode) {
             const p = parsePrincipalKey(a.id);
             if (p)
-                this.retiring.set(a.name, { opId: retireOpId(a.lifecycleUid), lifecycleUid: a.lifecycleUid, owner: p.owner, actor: p.actor, agentId: a.id, userOwner: a.userOwner, secretPaths: a.secretPaths, launch: { allowSubscribe: a.launch.allowSubscribe }, startedAt: Date.now() });
+                this.retiring.set(a.name, { opId: retireOpId(a.lifecycleUid), lifecycleUid: a.lifecycleUid, owner: p.owner, actor: p.actor, agentId: a.id, userOwner: a.userOwner, delegated: a.delegated, secretPaths: a.secretPaths, launch: { allowSubscribe: a.launch.allowSubscribe }, startedAt: Date.now() });
         }
         else if (this.auth) {
             // Unit B: a STATIC lifecycle now also holds its name pending its own terminal (the F1
@@ -3376,6 +3465,14 @@ export class Manager {
     /** The actual footprint teardown (wrapped by {@link deprovision}'s single-flight). */
     async driveDeprovision(a) {
         if (this.remoteAuthority) {
+            if (a.delegated) {
+                // The agent is its user's: only that user's retirement intent retires it, so the name stays
+                // held until retireDelegatedAgent confirms the host retired this UID.
+                const held = this.retiring.get(a.name);
+                if (held?.lifecycleUid === a.lifecycleUid)
+                    held.lastError = `"${a.name}" was launched under a delegated user intent and retires only through its user's retirement intent`;
+                return;
+            }
             // A hosted composition owns grant revocation and resumable footprint release. It calls this
             // prerequisite before the terminal rail. The callback must preserve this UID and its pending
             // state until the host decides terminal retirement, never map deprovisioning to suspension.
@@ -4031,10 +4128,16 @@ export class Manager {
      *  still refused downstream exactly as before. Offline rows do NOT occupy — a properly retired
      *  name stays reusable. A row this manager itself confirmed retired (its alias, principal, and
      *  lifecycleUid all matching a {@link confirmedRetiredPredecessors} entry) does not occupy
-     *  either, even while its advisory presence record ages out. */
+     *  either, even while its advisory presence record ages out. A numbered name is never reissued
+     *  ({@link issuedNumberedNames}), even after its holder retired. The requested base is exempt
+     *  from that history: it is the persona's own name, which stays reusable even when it once came
+     *  out of another persona's numbering. */
     uniqueName(base) {
         const live = this.liveRosterNames();
-        return firstFreeName(base, (n) => this.nameInUse(n, live));
+        const name = firstFreeName(base, (n) => this.nameInUse(n, live) || (n !== base && this.issuedNumberedNames.has(n)));
+        if (name !== base)
+            this.issuedNumberedNames.add(name);
+        return name;
     }
     /** Spawn a teammate by persona ref (`name` loads `.cotal/agents/<name>.md`; the peer presents
      *  under that file's own `name:`), as if a peer asked via the control plane. Used to pre-spawn the
@@ -4434,6 +4537,14 @@ export class Manager {
         }
     }
     async startAgentActive(opts, spawner, hooks) {
+        if (opts.delegatedIntent) {
+            if (!this.remoteAuthority?.executeDelegatedUserIntent)
+                return { ok: false, error: `"${opts.name}" names a delegated user intent, and this manager has no host execution for one` };
+            if (opts.supervise)
+                return { ok: false, error: `"${opts.name}" names a delegated user intent, and a delegated agent is never restarted (SPEC 13.16)` };
+            // A delegated launch's spawner is the user's principal, never the composition root's call.
+            spawner = opts.delegatedIntent.parent;
+        }
         // The spawn argument is a persona REF — a filename in `.cotal/agents` (the unique spawn KEY), or
         // a path via `--config`. It is NOT the mesh identity: the identity comes from inside the file
         // (`name:`), so a persona can be filed descriptively (review-critic.md) yet present under a
@@ -4642,6 +4753,27 @@ export class Manager {
                     `An operator adds \`capabilities: [spawn]\` to ${configPath}; a peer-defined persona ` +
                     `(cotal_persona) cannot declare capabilities by design — ask an operator to grant it.`,
             };
+        // #581: the operator's per-role model allowlist, judged on the EFFECTIVE role and model resolved
+        // above, before any reserve or mint. This is where the launch is performed, so no caller can
+        // skip it, and a definition pinned to a stale model (or to none) is refused here instead of
+        // serving on it. Read per spawn, so a policy edit reaches the next spawn without a restart.
+        let policyRefusal;
+        try {
+            policyRefusal = modelPolicyRefusal(loadCotalConfig(this.workspaceRoot), {
+                persona: opts.resolved ? `manifest agent "${ref}"` : `persona "${ref}" (${configPath})`,
+                role, model, variant,
+                // A manifest launch carries its own declared model/variant in these options
+                // (launchAgentToStartOpts), so there they are the definition's field, never a flag.
+                modelFlag: !opts.resolved && opts.model !== undefined,
+                variantFlag: !opts.resolved && opts.variant !== undefined,
+                launchOptions,
+            });
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        if (policyRefusal)
+            return { ok: false, error: policyRefusal };
         // The alias-reuse gate (#29 piece 3): a name whose previous agent is still retiring REFUSES
         // legibly (never a silent suffix), and the refusal re-drives the FULL durable teardown so
         // "retry the spawn" is also the nudge. It routes through `deprovision` (not `requestRetirement`
@@ -4652,7 +4784,7 @@ export class Manager {
             return { ok: false, error: `the name "${identityName}" is still reconciling at manager startup; its prior lifecycle terminal owns this alias until it completes. Retry shortly.` };
         const held = this.retiring.get(identityName);
         if (held !== undefined) {
-            void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, secretPaths: held.secretPaths, launch: held.launch }).catch(() => { });
+            void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, delegated: held.delegated, secretPaths: held.secretPaths, launch: held.launch }).catch(() => { });
             const err = lifecycleBlocked("failed-precondition", `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`, { blockedOp: "retirement", headState: "retiring", opId: held.opId, remedy: "retry" });
             return { ok: false, error: renderLifecycleBlocked(err.message, err), details: err.details };
         }
@@ -4844,6 +4976,15 @@ export class Manager {
                     capabilities,
                     label: ref,
                     lifecycleUid,
+                    delegatedIntent: opts.delegatedIntent,
+                    // Hold the name at the UID the host enrolled for the intent's user before any later local
+                    // step runs, so no later failure, its refusal included, releases a lifecycle that only that
+                    // user's retirement intent retires.
+                    onEnrolled: opts.delegatedIntent
+                        ? (enrolled) => {
+                            provisioned = { id: principalKey(enrolled.owner, name).key, name, lifecycleUid: enrolled.lifecycleUid, userOwner: enrolled.owner, delegated: true, secretPaths: enrolled.files };
+                        }
+                        : undefined,
                 });
                 if ("error" in prep) {
                     this.reserved.delete(name);
@@ -4857,7 +4998,7 @@ export class Manager {
                 lifecycleUid = prep.lifecycleUid;
                 userLaunch = prep.launch;
                 userOwner = prep.owner;
-                provisioned = { id: principalKey(prep.owner, name).key, name, lifecycleUid, userOwner: prep.owner, secretPaths: prep.files, ...(custody ? { runtime: custody } : {}) };
+                provisioned = { id: principalKey(prep.owner, name).key, name, lifecycleUid, userOwner: prep.owner, ...(opts.delegatedIntent ? { delegated: true } : {}), secretPaths: prep.files, ...(custody ? { runtime: custody } : {}) };
             }
             else if (this.auth) {
                 // Unit B (§13.1): reserve + activate this incarnation's DURABLE identity BEFORE any
@@ -4983,6 +5124,7 @@ export class Manager {
                 // recorded truth teardown/preservation/health consume, never re-derived by name.
                 secretPaths: provisioned?.secretPaths,
                 ...(userLaunch ? { userOwner } : { seed: identity.seed }),
+                ...(opts.delegatedIntent ? { delegated: true } : {}),
                 ...(issued ? { issued } : {}),
                 spawner: spawner ?? this.ep.ref().id,
                 authorityParent: userLaunch && spawner && parsePrincipalKey(spawner) ? spawner : undefined,
@@ -5021,7 +5163,8 @@ export class Manager {
                         ? Object.keys(opts.launchOptions).sort()
                         : undefined,
                 },
-                ...(connector.supportsSessionContinuation || opts.supervise !== undefined
+                // A delegated agent is never restarted (SPEC 13.16), so its slot arms no recovery.
+                ...((connector.supportsSessionContinuation || opts.supervise !== undefined) && !opts.delegatedIntent
                     ? {
                         restart: {
                             opts: launchOpts,
@@ -5139,6 +5282,11 @@ export class Manager {
             // orphan down (detached, fail-loud) so a failed spawn leaves no creds/durables behind (#159 B).
             if (provisioned) {
                 const orphan = provisioned;
+                // The host enrolled this UID for the intent's user, so only that user's retirement intent
+                // retires it, and its name stays held for retireDelegatedAgent.
+                const p = orphan.delegated ? parsePrincipalKey(orphan.id) : null;
+                if (p)
+                    this.retiring.set(orphan.name, { opId: retireOpId(orphan.lifecycleUid), lifecycleUid: orphan.lifecycleUid, owner: p.owner, actor: p.actor, agentId: orphan.id, userOwner: orphan.userOwner, delegated: true, secretPaths: orphan.secretPaths, startedAt: Date.now() });
                 this.trackDeprovision(orphan, "(orphaned spawn)");
             }
         }
@@ -5159,6 +5307,7 @@ export class Manager {
                 return { ok: false, agents: [], error: `resume inventory belongs to space "${inventory.space}", not "${this.space}"` };
             const seen = new Set();
             const principals = new Set();
+            const orphans = [];
             await this.ep.waitForPresenceSnapshot();
             const liveRoster = this.ep.getRoster().filter((presence) => presence.status !== "offline");
             const occupancy = this.occupancy();
@@ -5180,6 +5329,7 @@ export class Manager {
                         name: entry.name,
                         lifecycleUid: held.lifecycleUid,
                         userOwner: held.userOwner,
+                        delegated: held.delegated,
                         secretPaths: held.secretPaths,
                     }).catch(() => { });
                     return {
@@ -5210,8 +5360,12 @@ export class Manager {
                         presence.card.name !== entry.name ||
                         entry.identity.lifecycleUid === confirmedPredecessor.lifecycleUid;
                 });
-                if (principalIsLive)
-                    return { ok: false, agents: [], error: `retained principal "${principal}" is already live and this runtime cannot authoritatively adopt it` };
+                if (principalIsLive) {
+                    const orphan = await this.orphanedResumeSeat(entry, principal, liveRoster);
+                    if (!orphan)
+                        return { ok: false, agents: [], error: `retained principal "${principal}" is already live and this runtime cannot authoritatively adopt it` };
+                    orphans.push({ principal, reference: orphan });
+                }
                 if (this.agents.has(entry.name) || this.reserved.has(entry.name))
                     return { ok: false, agents: [], error: `retained agent "${entry.name}" is already managed or reserved` };
             }
@@ -5231,6 +5385,13 @@ export class Manager {
                     agents: preflight,
                     error: `${preflightFailures.length} retained agent${preflightFailures.length === 1 ? "" : "s"} failed preflight`,
                 };
+            // Only now, with the whole inventory through preflight, is an orphan reaped: a refused batch
+            // leaves every seat as it found it.
+            for (const { principal, reference } of orphans) {
+                const refusal = await this.reapOrphanedResumeSeat(principal, reference);
+                if (refusal)
+                    return { ok: false, agents: [], error: refusal };
+            }
             const agents = [];
             for (let i = 0; i < inventory.agents.length; i++) {
                 const entry = inventory.agents[i];
@@ -5430,6 +5591,46 @@ export class Manager {
             throw new Error(`retained user principal ${entry.identity.owner}.${entry.identity.actor} could not be reused: ${e.message}`);
         }
     }
+    /** The seat reference behind a live retained principal, when that seat is provably one a lost
+     *  manager of this logical instance launched for this exact incarnation. The resume binds the
+     *  launched handle's reference to the incarnation's active slot before it waits for readiness, and
+     *  the coordinator journals `resume-active` only after that wait, so a coordinator crash between the
+     *  two leaves `resume-intent` behind a live seat. Undefined for everything else, which stays refused:
+     *  another incarnation's presence, a slot another instance owns, a runtime that cannot reap the
+     *  reference, and user or open meshes, which keep no slot. */
+    async orphanedResumeSeat(entry, principal, liveRoster) {
+        if (!this.auth || this.userMode || entry.identity.mode !== "static")
+            return undefined;
+        if (typeof this.runtime.reap !== "function")
+            return undefined;
+        if (liveRoster.some((p) => p.card.id === principal && p.lifecycleUid !== entry.identity.lifecycleUid))
+            return undefined;
+        const slot = await this.readStaticReconcileSlot(entry.name);
+        if (slot?.phase !== "active" || slot.actor !== entry.identity.id || slot.lifecycleUid !== entry.identity.lifecycleUid)
+            return undefined;
+        if (slot.ownerInstanceId !== undefined && slot.ownerInstanceId !== this.managerInstanceId)
+            return undefined;
+        return slot.runtime?.kind === this.runtime.kind ? slot.runtime : undefined;
+    }
+    /** Reap a seat {@link orphanedResumeSeat} found, then wait for its principal to leave presence so
+     *  the relaunch's readiness cannot match the dead seat's row. Returns the refusal when the reap
+     *  proves nothing or the principal stays live, which means another process holds it. */
+    async reapOrphanedResumeSeat(principal, reference) {
+        try {
+            const evidence = await requireRuntimeReap(this.runtime, reference);
+            console.error(`resume: reaped orphaned seat ${reference.kind}:${reference.id} of retained principal "${principal}" (${evidence.detail})`);
+        }
+        catch (e) {
+            return `retained principal "${principal}" is already live and its recorded seat ${reference.kind}:${reference.id} could not be reaped: ${e.message}`;
+        }
+        const deadline = Date.now() + ORPHAN_PRESENCE_CLEAR_MS;
+        while (this.ep.getRoster().some((p) => p.card.id === principal && p.status !== "offline")) {
+            if (Date.now() >= deadline)
+                return `retained principal "${principal}" is still live after its recorded seat ${reference.kind}:${reference.id} was reaped, so another process holds it and this runtime cannot authoritatively adopt it`;
+            await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+        }
+        return undefined;
+    }
     /** Validate/relaunch one retained inventory entry. Called only through resumePreserved so all
      * records pass the same preflight before the first child is exposed. */
     async resumePreservedAgent(entry, preflightOnly = false, batchReserved = false, prepared) {
@@ -5986,6 +6187,53 @@ export class Manager {
         void this.cancelAgentGoal(a.name, graceful ? "graceful" : "terminate"); // M4: cancel a live spawn goal
         return { ok: true, data: { name: a.name, stopped: true, graceful } };
     }
+    /** Retire one agent this manager launched under a delegated user intent, through the host
+     *  (SPEC 13.16). It sends the user's retirement intent for the UID of the running slot or its
+     *  retirement hold, and only on `retired: true` for that exact target stops the slot and frees the
+     *  name; every other answer leaves the slot running or the name held. It never calls the holder's
+     *  own prepare or requester. */
+    async retireDelegatedAgent(name, intentId) {
+        const execute = this.remoteAuthority?.executeDelegatedUserIntent;
+        if (!execute)
+            return { ok: false, error: `this manager has no host execution for a delegated user intent; "${name}" was not retired` };
+        const release = this.beginLifecycle();
+        if (!release)
+            return { ok: false, error: this.maintenanceError() };
+        try {
+            const live = this.agents.get(name);
+            const held = live ? undefined : this.retiring.get(name);
+            const principal = live?.delegated ? parsePrincipalKey(live.id) : held?.delegated ? held : null;
+            const lifecycleUid = live?.lifecycleUid ?? held?.lifecycleUid;
+            if (!principal || !lifecycleUid)
+                return { ok: false, error: `no agent named "${name}" was launched on this manager under a delegated user intent` };
+            const target = { owner: principal.owner, actor: principal.actor, lifecycleUid };
+            try {
+                const result = await execute({ intentId, operation: "retire", target });
+                if (result.operation !== "retire" || result.intentId !== intentId || result.opId !== retireOpId(target.lifecycleUid) ||
+                    result.target.owner !== target.owner || result.target.actor !== target.actor || result.target.lifecycleUid !== target.lifecycleUid)
+                    throw new Error(`the host answered delegated intent ${intentId} with another execution`);
+                if (result.retired !== true)
+                    return { ok: false, error: `the host did not confirm the delegated retirement of "${name}" at ${target.lifecycleUid}; "${name}" is unchanged` };
+            }
+            catch (e) {
+                const error = `the delegated retirement under intent ${intentId} did not complete (${rejectionText(e)})`;
+                const hold = this.retiring.get(name);
+                if (hold?.lifecycleUid === target.lifecycleUid)
+                    hold.lastError = error;
+                return { ok: false, error: `${error}; "${name}" is unchanged` };
+            }
+            // The host's retirement closed this UID's provider handle before its barrier, so the stop only
+            // reaps the slot, and its hold clears with the confirmation.
+            const slot = this.agents.get(name);
+            if (slot?.lifecycleUid === target.lifecycleUid)
+                this.despawnAuthorized(slot, true, false, `delegated retirement ${intentId}`);
+            this.confirmRetirement({ id: principalKey(target.owner, target.actor).key, name, lifecycleUid: target.lifecycleUid });
+            return { ok: true, data: { name, lifecycleUid: target.lifecycleUid, retired: true } };
+        }
+        finally {
+            release();
+        }
+    }
     /** Resolve a v0.4 TARGET triple (owner, actor, lifecycleUid — broker-validated subject/body
      *  agreement, currency re-checked by the serve boundary's resolver) to the live managed agent it
      *  names. Static agents key `(DEV_OWNER, nkey)`; user-mode agents store the principal dot-form
@@ -6167,7 +6415,7 @@ export class Manager {
         try {
             report = await reconcileEndpointGate({
                 kv: authKv, space: this.space, endpoint: MANAGER_ENDPOINT, instanceId,
-                probeHolder: makeManagerHolderLivenessProbe({ space: this.space, servers, auth, log }),
+                probeHolder: makeManagerHolderLivenessProbe({ space: this.space, servers, auth, log, unreachableWaitMs: DELIVERY_ADMIN_BOOT_WAIT_MS }),
                 evictHolders: makeManagerEndpointHolderEvictor({ space: this.space, servers, auth, log }),
                 log,
                 recordsKv,
@@ -6442,7 +6690,7 @@ export class Manager {
             // error text — a crash-restart never silently skips eviction (no-fallbacks).
             const barrier = endpointRegistrationBarrier(authKv, this.space, {
                 endpoint: MANAGER_ENDPOINT, instanceId: iid, opId: registrationOpId,
-                ...(auth ? { evict: makeManagerEndpointEvictor({ space: this.space, servers: this.servers ?? DEFAULT_SERVER, auth, log: (line) => console.error(line) }) } : {}),
+                ...(auth ? { evict: makeManagerEndpointEvictor({ space: this.space, servers: this.servers ?? DEFAULT_SERVER, auth, log: (line) => console.error(line), unreachableWaitMs: DELIVERY_ADMIN_BOOT_WAIT_MS }) } : {}),
             });
             const spec = { endpoint: MANAGER_ENDPOINT, owner: DEV_OWNER, clusterDigests: [artifacts.closureDigest], protocol: { v: 1 } };
             const { registrationRevision } = await registerServiceInstance(recordsKv, {