@cotal-ai/manager 0.11.6 → 0.13.0

package/dist/manager.js

@@ -1,13 +1,16 @@
 import { execFile } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
+import { createHash, randomUUID, randomBytes } from "node:crypto";
+import { connect, credsAuthenticator } from "@nats-io/transport-node";
+import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
-import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_TTL_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, deprovisionAgent, firstFreeName, loadAgentFile, loadCotalConfig, mintCreds, mkSecretDir, newIdentity, parsePrincipalKey, parseShareSelection, principalKey, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, writeSecretFile, subjectMatches, CONTROL_PRIVILEGED, CONTROL_SELF_SERVICE, CONTROL_ADMIN, } from "@cotal-ai/core";
-import { agentAuthState, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, findCotalRoot, loadMeshes, loadSpaceAuth, manifestExtensionNames, materializeFromManifest, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, userAuthStateDir, writeRenewalRecord } from "@cotal-ai/workspace";
+import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_TTL_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, deprovisionAgent, firstFreeName, idFromCreds, loadAgentFile, loadCotalConfig, mintCreds, mintLifecycleUid, mkSecretDir, newIdentity, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, CONTROL_PRIVILEGED, CONTROL_SELF_SERVICE, CONTROL_ADMIN, CONTROL_AUTH_ADMIN, controlServiceSubject, } from "@cotal-ai/core";
+import { agentActorTokenKey, agentAuthState, agentCredsDir, agentCredsKey, agentSecretFilePaths, agentSentinelCredsKey, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, findCotalRoot, loadMeshes, loadSpaceAuth, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts } from "./launch.js";
 import { authorizeLaunch, authorizeNamedControl } from "./authorize.js";
 import { controlShutdown } from "./control-shutdown.js";
+import { parseResumeCommitArgs, parseResumeControlArgs, parseResumeFinalizeArgs } from "./resume.js";
 /** Concurrency ceiling — the manager refuses to hold more than this many live + in-flight +
  *  cooling slots at once (P4a). Bounds a fork-bomb: spawn is a full agent process per call. */
 const MAX_AGENTS = 50;
@@ -29,6 +32,16 @@ export const READINESS_TIMEOUT_MS = 30_000;
  *  `.catch`. Generous over the helper's 5s connect timeout to allow the two consumer-deletes + ACL purge
  *  + drain on a healthy-but-slow broker. */
 const DEPROVISION_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;
+/** The STABLE retirement opId for one lifecycle (#29 piece 3): deterministic from the uid, so a
+ *  despawn retry, a same-name-spawn nudge, and the auth service's boot resume all drive the SAME
+ *  operation (the rail's idempotence table needs exactly one op per retiring incarnation). 26 hex
+ *  chars = in the lifecycle-token grammar `[a-z0-9]{26,32}`, collision-resistant. */
+function retireOpId(lifecycleUid) {
+    return createHash("sha256").update(`retire:${lifecycleUid}`).digest("hex").slice(0, 26);
+}
 /** Sentinel owner-filter value that matches NO agent's `userOwner` (owner tokens never contain a
  *  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. */
@@ -54,6 +67,9 @@ function withTimeout(p, ms, msg) {
     });
     return Promise.race([p.finally(() => clearTimeout(timer)), timeout]);
 }
+function sameStrings(a, b) {
+    return JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());
+}
 /**
  * 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
@@ -68,6 +84,7 @@ export class Manager {
     /** See {@link ManagerOptions.installedExtensions}. */
     installedExtensions;
     runtime;
+    preserveStopTimeoutMs;
     agents = new Map();
     /** Names whose spawn is in flight (reserved synchronously before the provision await) — counted
      *  toward the ceiling so two concurrent same-name spawns can't both pass the gate (P4a). */
@@ -75,6 +92,29 @@ export class Manager {
     /** 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 = [];
+    /** Names RESERVED PENDING RETIREMENT (#29 piece 3): a despawned agent's name stays held until
+     *  the auth plane confirms its lifecycle's retirement TERMINAL over the auth-admin rail — the
+     *  alias-reuse gate that closes the same-name despawn→respawn race at its root. An UNCERTAIN
+     *  outcome (rail down, timeout) keeps the hold with the last attempt's copy; a same-name spawn
+     *  refuses legibly AND re-fires the request. In-memory: across a manager restart the durable
+     *  truth is the auth-side lifecycle head itself (an unretired head refuses issuance — the
+     *  named residual this belt narrows, not replaces). */
+    retiring = new Map();
+    /** SINGLE-FLIGHT guard for {@link requestRetirement} (audit #1): one in-flight rail round-trip per
+     *  (name, lifecycleUid). The detached `deprovision` call and every same-name-spawn nudge for THAT
+     *  lifecycle JOIN the same promise instead of stacking independent requests that dual-enter the
+     *  barrier; a fresh trigger after it settles re-drives. Keyed by (name, uid) — NOT name alone — so a
+     *  same-name SUCCESSOR (which can spawn after the hold clears but before this flight's `nc.close`
+     *  yield settles) never joins the predecessor's rail request and skips its own retirement. */
+    retiringFlight = new Map();
+    /** SINGLE-FLIGHT guard for {@link deprovision} (INT-2/C): one in-flight teardown per
+     *  (name, lifecycleUid). The detached freeSlot teardown and every same-name-spawn nudge that
+     *  re-drives it JOIN one promise instead of launching a SECOND, concurrent teardown. Without it,
+     *  two teardowns race the NAME-KEYED ledger revoke: once the first frees the alias and a successor
+     *  mints its own row, the second's delayed revoke (which carries no lifecycle coordinate) would
+     *  delete the SUCCESSOR's standing authority. Keyed by (name, uid) so a later same-name lifecycle
+     *  gets its own flight; a fresh trigger after settle re-drives only if the hold still stands. */
+    deprovisioningFlight = new Map();
     attach;
     ep;
     /** Space trust material when the mesh runs in auth mode (`.cotal/auth` present);
@@ -92,6 +132,29 @@ export class Manager {
     leaseTimer;
     /** The class-2 renewal owner's half-TTL schedule (D5 slice 5); armed only on auth meshes. */
     credRenewTimer;
+    maintenanceState = "active";
+    lifecycleInFlight = 0;
+    lifecycleDrainWaiters = [];
+    preservationTask;
+    preparationTask;
+    preservationGeneration = 0;
+    preservationAttemptId;
+    preservationStarted = false;
+    preservationFailures = [];
+    unverifiedStops = [];
+    preservationInventory;
+    resumeAttemptId;
+    resumeInventoryDigest;
+    resumeInventory;
+    resumeTask;
+    resumeResult;
+    resumeRequired = false;
+    resumeAwaitingCommit = false;
+    resumeCommitted = false;
+    resumeCommitTask;
+    resumeFinalized = false;
+    resumeDurableCommitToken;
+    resumedAgentNames = new Set();
     constructor(opts) {
         this.space = opts.space;
         this.servers = opts.servers;
@@ -99,7 +162,17 @@ export class Manager {
         this.workspaceRoot = opts.workspaceRoot ?? findCotalRoot();
         this.installedExtensions = opts.installedExtensions ?? false;
         this.runtime = createRuntime(opts.runtime ?? "auto", `cotal-${this.space}`);
-        this.attach = new AttachEndpoint((name) => this.agents.get(name)?.handle, () => this.list(), 
+        this.preserveStopTimeoutMs = opts.preserveStopTimeoutMs ?? PRESERVE_STOP_TIMEOUT_MS;
+        if (opts.resumeAttemptId && !/^[A-Za-z0-9_-]{1,128}$/.test(opts.resumeAttemptId))
+            throw new Error("resumeAttemptId must be a safe token (letters, digits, _, -; max 128)");
+        if (opts.resumeDurableCommitToken && !/^[a-f0-9]{64}$/.test(opts.resumeDurableCommitToken))
+            throw new Error("resumeDurableCommitToken must be a lowercase 32-byte token");
+        if (opts.resumeDurableCommitToken && !opts.resumeAttemptId)
+            throw new Error("resumeDurableCommitToken requires resumeAttemptId");
+        this.resumeAttemptId = opts.resumeAttemptId;
+        this.resumeRequired = opts.resumeAttemptId !== undefined;
+        this.resumeDurableCommitToken = opts.resumeDurableCommitToken;
+        this.attach = new AttachEndpoint((name) => this.maintenanceState === "active" && !this.resumeRequired ? this.agents.get(name)?.handle : undefined, () => this.list(), 
         // Initial /feed replay for a connecting console: the current peer roster.
         () => [{ event: "roster", data: this.ep?.getRoster() ?? [] }], opts.consolePort ?? 0);
     }
@@ -149,6 +222,11 @@ export class Manager {
             servers: this.servers,
             channels: [],
             creds,
+            // The supervisor registers on the roster, and an authed presence-registering endpoint is
+            // lifecycle-keyed (SPEC 13.1, fail-before-presence). The manager process is the top of its
+            // own launch chain (the operator command IS its launcher), so it mints its incarnation's
+            // uid here - one per supervisor process, never reused across restarts.
+            lifecycleUid: mintLifecycleUid(),
             // The supervisor serves control + watches presence; it never consumes chat/dm/task
             // (no message handler). consume:false avoids binding consumers it doesn't use — and
             // under auth avoids trying to bind its own DM/task durables that nothing pre-created.
@@ -221,6 +299,9 @@ export class Manager {
      *  (no responder) is recorded honestly: the daemon's 75% source re-read remains the adoption backstop.
      *  Never throws — renewal failure must be LOUD (log + record), not fatal to the supervisor. */
     async renewDaemonCreds() {
+        const release = this.beginLifecycle();
+        if (!release)
+            return;
         try {
             const results = await remintDaemonCreds(this.workspaceRoot);
             const resigned = results.filter((r) => r.ok);
@@ -243,6 +324,360 @@ export class Manager {
         catch (e) {
             console.error(`! credential renewal pass failed: ${e.message}`);
         }
+        finally {
+            release();
+        }
+    }
+    /** 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. */
+    beginLifecycle(resumeOperation = false) {
+        if (this.maintenanceState !== "active" || (this.resumeRequired && !resumeOperation))
+            return undefined;
+        this.lifecycleInFlight++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.releaseLifecycle();
+        };
+    }
+    releaseLifecycle() {
+        this.lifecycleInFlight--;
+        if (this.lifecycleInFlight !== 0)
+            return;
+        const waiters = this.lifecycleDrainWaiters;
+        this.lifecycleDrainWaiters = [];
+        for (const wake of waiters)
+            wake();
+    }
+    /** A cleanup spawned by accepted active-mode work is part of that work for maintenance draining,
+     * even where the ordinary control reply remains fire-and-forget. */
+    trackDeprovision(a, context = "") {
+        this.lifecycleInFlight++;
+        void this.deprovision(a)
+            .catch((e) => console.error(`deprovision${context ? ` ${context}` : ""} ${a.name} (${a.id}): ${e.message}`))
+            .finally(() => this.releaseLifecycle());
+    }
+    async awaitLifecycleDrain() {
+        if (this.lifecycleInFlight === 0)
+            return;
+        await new Promise((resolve) => this.lifecycleDrainWaiters.push(resolve));
+    }
+    maintenanceError() {
+        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`;
+    }
+    /** Fence and build the inventory without stopping a child. The coordinator must durably persist
+     * this exact plan before calling commitPreservation with the same attempt id. */
+    preparePreservation(attemptId) {
+        if (!attemptId.trim())
+            return Promise.reject(new Error("preservation attemptId is required"));
+        if (this.preservationAttemptId && this.preservationAttemptId !== attemptId)
+            return Promise.reject(new Error(`manager is fenced for preservation attempt ${this.preservationAttemptId}; refusing different attempt ${attemptId}`));
+        if (this.maintenanceState === "preserved" && this.preservationInventory)
+            return Promise.resolve({ ok: true, attemptId, state: "preserved", inventory: this.preservationInventory, failures: [] });
+        if (this.preparationTask)
+            return this.preparationTask;
+        if (this.maintenanceState === "active") {
+            // The fence lands before any await. Accepted work has already incremented lifecycleInFlight.
+            this.maintenanceState = "preserving";
+            this.preservationAttemptId = attemptId;
+            this.preservationGeneration++;
+            if (this.credRenewTimer) {
+                clearInterval(this.credRenewTimer);
+                this.credRenewTimer = undefined;
+            }
+        }
+        const generation = this.preservationGeneration;
+        const task = this.runPreparation(attemptId, generation);
+        let wrapped;
+        wrapped = task.finally(() => {
+            if (this.preservationGeneration === generation && this.preparationTask === wrapped)
+                this.preparationTask = undefined;
+        });
+        this.preparationTask = wrapped;
+        return wrapped;
+    }
+    assertPreservationGeneration(attemptId, generation) {
+        if (this.preservationAttemptId !== attemptId || this.preservationGeneration !== generation)
+            throw new Error(`preservation attempt ${attemptId} was abandoned before preparation completed`);
+    }
+    async runPreparation(attemptId, generation) {
+        await this.awaitLifecycleDrain();
+        this.assertPreservationGeneration(attemptId, generation);
+        const inventory = this.preservationInventory ?? {
+            version: "cotal-manager-resume/v1",
+            space: this.space,
+            createdAt: new Date().toISOString(),
+            agents: [...this.agents.values()].map((a) => this.resumeEntry(a)),
+        };
+        const failures = [];
+        for (const entry of inventory.agents) {
+            const error = this.inventoryReferenceError(entry);
+            if (error)
+                failures.push({
+                    name: entry.name,
+                    id: entry.identity.mode === "user" ? principalKey(entry.identity.owner, entry.identity.actor).key : entry.identity.id,
+                    error,
+                });
+        }
+        const unverifiedStops = this.unverifiedStops.filter((stopped) => {
+            try {
+                if (!stopped.authoritative && stopped.handle.status() === "exited")
+                    return false;
+            }
+            catch { /* fail closed below */ }
+            failures.push({
+                name: stopped.name,
+                id: stopped.id,
+                error: stopped.error ?? `an earlier stop on runtime "${stopped.handle.kind}" cannot prove the child is gone`,
+            });
+            return true;
+        });
+        this.assertPreservationGeneration(attemptId, generation);
+        // The prepared inventory must round-trip through the EXACT resume control parser (schema and
+        // byte cap) NOW, before any child stops: a cut that cannot resume must fail at prepare time,
+        // never after listener exposure.
+        try {
+            parseResumeControlArgs({ attemptId, inventory });
+        }
+        catch (e) {
+            failures.push({ name: "<inventory>", id: attemptId, error: `prepared inventory would be rejected at resume: ${e.message}` });
+        }
+        this.preservationInventory = inventory;
+        this.preservationFailures = failures;
+        this.unverifiedStops = unverifiedStops;
+        return {
+            ok: failures.length === 0,
+            attemptId,
+            state: "prepared",
+            inventory,
+            failures: [...failures],
+        };
+    }
+    /** Stop children only after the coordinator has persisted the prepared inventory. Same-attempt
+     * retries are idempotent; a different attempt is refused. */
+    commitPreservation(attemptId) {
+        if (!this.preservationAttemptId || this.preservationAttemptId !== attemptId)
+            return Promise.reject(new Error(`preservation attempt ${attemptId} was not prepared by this manager`));
+        if (!this.preservationInventory)
+            return Promise.reject(new Error(`preservation attempt ${attemptId} has no prepared inventory`));
+        if (this.preservationFailures.length)
+            return Promise.resolve({
+                ok: false,
+                attemptId,
+                state: "preserving",
+                inventory: this.preservationInventory,
+                failures: [...this.preservationFailures],
+            });
+        if (this.maintenanceState === "preserved")
+            return Promise.resolve({ ok: true, attemptId, state: "preserved", inventory: this.preservationInventory, failures: [] });
+        if (this.preservationTask)
+            return this.preservationTask;
+        this.preservationStarted = true;
+        this.preservationTask = this.runPreservation(attemptId).finally(() => {
+            this.preservationTask = undefined;
+        });
+        return this.preservationTask;
+    }
+    /** Recover an abandoned prepare before any child stop. Once commit begins, preservation is
+     * irreversible and remains fenced until the coordinator records failure/recourse. */
+    abortPreservation(attemptId) {
+        if (this.preservationAttemptId !== attemptId)
+            throw new Error(`preservation attempt ${attemptId} is not the active manager attempt`);
+        if (this.preparationTask || this.lifecycleInFlight > 0)
+            throw new Error(`preservation attempt ${attemptId} is still preparing or draining accepted lifecycle work and cannot be aborted`);
+        if (this.preservationStarted || this.preservationTask || this.maintenanceState === "preserved")
+            throw new Error(`preservation attempt ${attemptId} has begun stopping children and cannot return to active mode`);
+        this.preservationGeneration++;
+        this.maintenanceState = "active";
+        this.preservationAttemptId = undefined;
+        this.preservationInventory = undefined;
+        this.preservationFailures = [];
+        if (this.auth && !this.credRenewTimer) {
+            this.credRenewTimer = setInterval(() => { void this.renewDaemonCreds(); }, (STANDING_RENEWABLE_TTL_SEC / 2) * 1000);
+            this.credRenewTimer.unref?.();
+        }
+        // Exit watchers were suppressed while the fence stood: reconcile every child that died during
+        // preparation now, or its slot/credential footprint would linger unreaped after the abort.
+        for (const agent of [...this.agents.values()]) {
+            try {
+                if (agent.handle.status() === "exited")
+                    this.onAgentExit(agent);
+            }
+            catch { /* status unavailable - the exit watcher fires again on real exit */ }
+        }
+    }
+    /** In-process convenience that preserves the crash barrier by awaiting durable persistence between
+     * prepare and commit. Wire callers use the explicit two-phase admin operations. */
+    async preserveState(opts) {
+        const plan = await this.preparePreservation(opts.attemptId);
+        if (!plan.ok)
+            return { ok: false, attemptId: opts.attemptId, state: "preserving", inventory: plan.inventory, failures: plan.failures };
+        await opts.persistInventory(plan.inventory);
+        return this.commitPreservation(opts.attemptId);
+    }
+    async runPreservation(attemptId) {
+        const failures = [];
+        for (const a of [...this.agents.values()])
+            a.suppressCleanup = true;
+        await Promise.all([...this.agents.values()].map(async (a) => {
+            try {
+                // A preservation cut must not run the connector's logical leave/cleanup hooks.
+                a.handle.stop({ graceful: false });
+            }
+            catch (e) {
+                failures.push({ name: a.name, id: a.id, error: `stop failed: ${e.message}` });
+                return;
+            }
+            try {
+                await this.awaitHandleExit(a.handle);
+                if (this.agents.get(a.name) === a)
+                    this.agents.delete(a.name);
+            }
+            catch (e) {
+                failures.push({ name: a.name, id: a.id, error: e.message });
+            }
+        }));
+        if (failures.length === 0)
+            this.maintenanceState = "preserved";
+        return {
+            ok: failures.length === 0,
+            attemptId,
+            state: this.maintenanceState === "preserved" ? "preserved" : "preserving",
+            inventory: this.preservationInventory,
+            failures,
+        };
+    }
+    async awaitHandleExit(handle) {
+        if (!handle.waitForExit)
+            throw new Error(`runtime "${handle.kind}" cannot prove child exit (AgentHandle.waitForExit is not implemented)`);
+        if (handle.status() === "exited")
+            return;
+        await withTimeout(handle.waitForExit(), this.preserveStopTimeoutMs, `child did not exit within ${this.preserveStopTimeoutMs}ms`);
+        if (handle.status() !== "exited")
+            throw new Error(`runtime "${handle.kind}" reported exit completion but status is still running`);
+    }
+    inventoryReferenceError(entry) {
+        if (entry.launch.source.kind === "manifest" && !entry.launch.source.runId)
+            return "resolved manifest launch has no retained runId";
+        if (entry.launch.unresolvedLaunchOptionKeys?.length)
+            return `imperative launch options have no non-secret durable source (${entry.launch.unresolvedLaunchOptionKeys.join(", ")})`;
+        if (!entry.dependencies.some((path) => resolve(path) === resolve(entry.launch.source.configPath)))
+            return `launch config is not declared as a retained dependency: ${entry.launch.source.configPath}`;
+        if (entry.launch.source.kind === "manifest" && entry.launch.source.runId) {
+            const specPath = join(this.workspaceRoot, ".cotal", "run", `${entry.launch.source.runId}.json`);
+            if (!entry.dependencies.some((path) => resolve(path) === resolve(specPath)))
+                return `manifest source is not declared as a retained dependency: ${specPath}`;
+        }
+        const required = [...entry.dependencies];
+        if (entry.identity.mode === "static")
+            required.push(entry.identity.credential.path);
+        if (entry.identity.mode === "user") {
+            required.push(entry.identity.actorToken.path, entry.identity.sentinelCredential.path);
+        }
+        for (const path of required) {
+            try {
+                const st = lstatSync(path);
+                if (!st.isFile() || st.isSymbolicLink())
+                    return `retained reference is not a regular non-symlink file: ${path}`;
+            }
+            catch (e) {
+                return `retained reference unavailable: ${path} (${e.message})`;
+            }
+        }
+        if (process.platform !== "win32") {
+            const secrets = entry.identity.mode === "static"
+                ? [entry.identity.credential.path]
+                : entry.identity.mode === "user"
+                    ? [entry.identity.actorToken.path, entry.identity.sentinelCredential.path]
+                    : [];
+            for (const path of secrets)
+                if ((lstatSync(path).mode & 0o077) !== 0)
+                    return `retained identity file is not private (expected 0600): ${path}`;
+        }
+        try {
+            if (this.fileDigest(entry.launch.source.configPath) !== entry.launch.source.configSha256)
+                return `launch config changed since it became effective: ${entry.launch.source.configPath}`;
+            if (entry.identity.mode === "static" && this.fileDigest(entry.identity.credential.path) !== entry.identity.credential.sha256)
+                return `retained credential changed after the cut: ${entry.identity.credential.path}`;
+            if (entry.identity.mode === "user" &&
+                (this.fileDigest(entry.identity.actorToken.path) !== entry.identity.actorToken.sha256 ||
+                    this.fileDigest(entry.identity.sentinelCredential.path) !== entry.identity.sentinelCredential.sha256))
+                return `retained user identity files changed after the cut for ${entry.name}`;
+            if (entry.launch.source.kind === "manifest" && entry.launch.source.runId) {
+                const specPath = join(this.workspaceRoot, ".cotal", "run", `${entry.launch.source.runId}.json`);
+                if (!entry.launch.source.manifestSha256 || this.fileDigest(specPath) !== entry.launch.source.manifestSha256)
+                    return `manifest source changed since it became effective: ${specPath}`;
+            }
+        }
+        catch (e) {
+            return `retained reference cannot be hashed: ${e.message}`;
+        }
+        return undefined;
+    }
+    fileDigest(path) {
+        return createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+    fileDigestOrEmpty(path) {
+        try {
+            return this.fileDigest(path);
+        }
+        catch {
+            return "";
+        }
+    }
+    resumeEntry(a) {
+        const principal = a.userOwner
+            ? parsePrincipalKey(a.id)
+            : { owner: DEV_OWNER, actor: a.id };
+        if (!principal)
+            throw new Error(`managed agent ${a.name} has an invalid principal ${a.id}`);
+        const files = agentSecretFilePaths(this.workspaceRoot, a.name);
+        const identity = a.userOwner
+            ? {
+                mode: "user",
+                owner: principal.owner,
+                actor: principal.actor,
+                lifecycleUid: a.lifecycleUid,
+                actorToken: { kind: "file", path: files.actorToken, sha256: this.fileDigestOrEmpty(files.actorToken) },
+                sentinelCredential: { kind: "file", path: files.sentinelCreds, sha256: this.fileDigestOrEmpty(files.sentinelCreds) },
+                health: { kind: "file", path: files.health },
+            }
+            : this.auth
+                ? { mode: "static", id: principal.actor, lifecycleUid: a.lifecycleUid, credential: { kind: "file", path: files.creds, sha256: this.fileDigestOrEmpty(files.creds) } }
+                : { mode: "open", id: principal.actor, lifecycleUid: a.lifecycleUid };
+        const dependencies = [a.launch.source.configPath];
+        if (a.launch.source.kind === "manifest" && a.launch.source.runId)
+            dependencies.unshift(join(this.workspaceRoot, ".cotal", "run", `${a.launch.source.runId}.json`));
+        return {
+            space: this.space,
+            name: a.name,
+            role: a.role,
+            identity,
+            launch: {
+                connector: a.agent,
+                runtime: a.handle.kind,
+                cwd: a.launch.cwd,
+                source: a.launch.source,
+                model: a.launch.model,
+                variant: a.launch.variant,
+                subscribe: a.launch.subscribe,
+                allowSubscribe: a.launch.allowSubscribe,
+                allowPublish: a.launch.allowPublish,
+                capabilities: a.launch.capabilities,
+                transcript: a.launch.transcript,
+                shareTools: a.launch.shareTools,
+                forkSource: a.launch.forkSource,
+                unresolvedLaunchOptionKeys: a.launch.unresolvedLaunchOptionKeys,
+            },
+            dependencies,
+            spawner: a.spawner,
+            authorityParent: a.authorityParent,
+            startedAt: new Date(a.startedAt).toISOString(),
+        };
     }
     /** Tear down every managed agent's footprint — the shared teardown for EVERY manager-exit path (#159
      *  B2): graceful {@link stop} AND the fail-closed lease-loss exit ({@link renewLease}). A manager exit is
@@ -262,14 +697,44 @@ export class Manager {
             this.stopHandle(a, false);
         }
         // Deprovision EVERY snapshot entry regardless of whether its stop failed (allSettled + a loud log).
-        await Promise.allSettled(managed.map((a) => this.deprovision(a).catch((e) => console.error(`deprovision ${a.name} (${a.id}) on shutdown: ${e.message}`))));
+        await Promise.allSettled(managed.filter((a) => !a.suppressCleanup).map((a) => this.deprovision(a).catch((e) => console.error(`deprovision ${a.name} (${a.id}) on shutdown: ${e.message}`))));
+    }
+    async stopRetainedAgentsOnExit() {
+        const managed = [...this.agents.values()];
+        for (const a of managed)
+            a.suppressCleanup = true;
+        const failures = [];
+        await Promise.all(managed.map(async (a) => {
+            try {
+                a.handle.stop({ graceful: false });
+            }
+            catch (e) {
+                failures.push(`${a.name}: stop failed: ${e.message}`);
+            }
+            try {
+                await this.awaitHandleExit(a.handle);
+                if (this.agents.get(a.name) === a)
+                    this.agents.delete(a.name);
+            }
+            catch (e) {
+                failures.push(`${a.name}: ${e.message}`);
+            }
+        }));
+        if (failures.length)
+            throw new Error(`manager preservation shutdown incomplete: ${failures.join("; ")}`);
     }
     async stop() {
         if (this.leaseTimer)
             clearInterval(this.leaseTimer);
         if (this.credRenewTimer)
             clearInterval(this.credRenewTimer);
-        await this.teardownManagedAgents(); // reap agents BEFORE releasing the lease/endpoints (#159 B2)
+        if (this.maintenanceState === "active" && !this.resumeRequired) {
+            await this.teardownManagedAgents(); // normal shutdown stays destructive (#159 B2)
+        }
+        else {
+            // A signal after a partial preservation must never fall back into destructive teardown.
+            await this.stopRetainedAgentsOnExit();
+        }
         await this.ep.releaseManagerLease(this.leaseRevision);
         await this.ep.stop();
         await this.attach.stop();
@@ -279,9 +744,9 @@ export class Manager {
      *  with the new holder, and exit. We deliberately do NOT re-acquire (a replacement may already be live
      *  while we'd still be serving) and do NOT release the key — it now belongs to that replacement. */
     async renewLease() {
-        if (!this.leaseInfo || this.leaseRevision === undefined)
-            return;
         try {
+            if (!this.leaseInfo || this.leaseRevision === undefined)
+                return;
             this.leaseRevision = await this.ep.renewManagerLease(this.leaseInfo, this.leaseRevision);
         }
         catch (e) {
@@ -291,7 +756,10 @@ export class Manager {
             // Tear down our managed agents' footprints too (#159 B2) — this exit path leaks them otherwise. Do
             // NOT release the lease key (it may belong to the replacement holder). Best-effort, like ep/attach.
             try {
-                await this.teardownManagedAgents();
+                if (this.maintenanceState === "active" && !this.resumeRequired)
+                    await this.teardownManagedAgents();
+                else
+                    await this.stopRetainedAgentsOnExit();
             }
             catch { /* best effort */ }
             try {
@@ -306,6 +774,187 @@ export class Manager {
         }
     }
     async handle(req, tier) {
+        if (req.op === "finalizeResume") {
+            if (tier !== CONTROL_ADMIN)
+                return { ok: false, error: "finalizeResume is admin-only; not allowed on this control subject" };
+            let args;
+            try {
+                args = parseResumeFinalizeArgs(req.args);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            if (!this.resumeAttemptId || this.resumeAttemptId !== args.attemptId)
+                return { ok: false, error: `manager expects resume attempt ${this.resumeAttemptId ?? "<none>"}, not ${args.attemptId}` };
+            if (!this.resumeCommitted || !this.resumeDurableCommitToken)
+                return { ok: false, error: `resume attempt ${args.attemptId} has no successful commit to finalize` };
+            if (this.resumeDurableCommitToken !== args.durableCommitToken)
+                return { ok: false, error: `resume attempt ${args.attemptId} durable commit token does not match` };
+            if (this.resumeFinalized)
+                return { ok: true, data: { attemptId: args.attemptId, state: "active" } };
+            const inventory = this.resumeInventory;
+            if (!inventory)
+                return { ok: false, error: `resume attempt ${args.attemptId} has no bound inventory` };
+            let inactive;
+            try {
+                inactive = this.resumeLivenessErrors(inventory, this.ep.getRoster());
+            }
+            catch (e) {
+                return { ok: false, error: `resume attempt ${args.attemptId} cannot verify live principals at finalize: ${e.message}` };
+            }
+            if (inactive.length)
+                return { ok: false, error: `resume attempt ${args.attemptId} is not live at finalize: ${inactive.join("; ")}` };
+            for (const entry of this.resumeInventory?.agents ?? []) {
+                const managed = this.agents.get(entry.name);
+                if (managed)
+                    managed.suppressCleanup = false;
+            }
+            this.resumeFinalized = true;
+            this.resumeRequired = false;
+            return { ok: true, data: { attemptId: args.attemptId, state: "active" } };
+        }
+        if (req.op === "commitResume") {
+            if (tier !== CONTROL_ADMIN)
+                return { ok: false, error: "commitResume is admin-only; not allowed on this control subject" };
+            let attemptId;
+            try {
+                attemptId = parseResumeCommitArgs(req.args).attemptId;
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            if (!this.resumeAttemptId || this.resumeAttemptId !== attemptId)
+                return { ok: false, error: `manager expects resume attempt ${this.resumeAttemptId ?? "<none>"}, not ${attemptId}` };
+            if (this.resumeCommitted)
+                return {
+                    ok: true,
+                    data: {
+                        attemptId,
+                        state: this.resumeFinalized ? "active" : "awaitingFinalize",
+                        durableCommitToken: this.resumeDurableCommitToken,
+                    },
+                };
+            if (this.resumeCommitTask)
+                return this.resumeCommitTask;
+            const task = this.commitResumeActivation(attemptId);
+            this.resumeCommitTask = task;
+            try {
+                return await task;
+            }
+            finally {
+                if (this.resumeCommitTask === task)
+                    this.resumeCommitTask = undefined;
+            }
+        }
+        if (req.op === "resumePreserved") {
+            if (tier !== CONTROL_ADMIN)
+                return { ok: false, error: "resumePreserved is admin-only; not allowed on this control subject" };
+            try {
+                const args = parseResumeControlArgs(req.args);
+                const inventoryDigest = createHash("sha256").update(JSON.stringify(args.inventory)).digest("hex");
+                if (!this.resumeAttemptId)
+                    return { ok: false, error: "resumePreserved requires a manager started with --resume-attempt" };
+                if (this.resumeAttemptId !== args.attemptId)
+                    return { ok: false, error: `manager expects resume attempt ${this.resumeAttemptId}, not ${args.attemptId}` };
+                if (this.resumeInventoryDigest && this.resumeInventoryDigest !== inventoryDigest)
+                    return { ok: false, error: `resume attempt ${args.attemptId} is already bound to a different inventory` };
+                if (!this.resumeInventoryDigest) {
+                    this.resumeInventoryDigest = inventoryDigest;
+                    this.resumeInventory = args.inventory;
+                }
+                if (!this.resumeTask && !this.resumeResult) {
+                    this.resumeTask = this.resumePreserved(args.inventory).then((result) => {
+                        if (result.ok || this.resumedAgentNames.size > 0)
+                            this.resumeResult = result;
+                        return result;
+                    }).finally(() => {
+                        this.resumeTask = undefined;
+                    });
+                }
+                const result = this.resumeResult ?? await this.resumeTask;
+                const data = { attemptId: args.attemptId, state: result.ok ? "awaitingCommit" : "degraded", ...result };
+                return result.ok
+                    ? { ok: true, data }
+                    : { ok: false, data, error: result.error ?? "retained-agent resume failed" };
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+        }
+        if (req.op === "preparePreservation" || req.op === "commitPreservation" || req.op === "abortPreservation") {
+            if (tier !== CONTROL_ADMIN)
+                return { ok: false, error: `${req.op} is admin-only; not allowed on this control subject` };
+            if (this.resumeRequired)
+                return { ok: false, error: this.maintenanceError() };
+            const attemptId = String(req.args?.attemptId ?? "").trim();
+            if (!attemptId)
+                return { ok: false, error: `${req.op} requires attemptId` };
+            try {
+                if (req.op === "abortPreservation") {
+                    this.abortPreservation(attemptId);
+                    return { ok: true, data: { attemptId, state: "active" } };
+                }
+                const result = req.op === "preparePreservation"
+                    ? await this.preparePreservation(attemptId)
+                    : await this.commitPreservation(attemptId);
+                return result.ok
+                    ? { ok: true, data: result }
+                    : {
+                        ok: false,
+                        data: result,
+                        error: `preservation incomplete: ${result.failures.map((f) => `${f.name}: ${f.error}`).join("; ")}`,
+                    };
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+        }
+        const release = this.beginLifecycle();
+        if (!release)
+            return { ok: false, error: this.maintenanceError() };
+        try {
+            return await this.handleActive(req, tier);
+        }
+        finally {
+            release();
+        }
+    }
+    async commitResumeActivation(attemptId) {
+        if (!this.resumeAwaitingCommit || !this.resumeResult?.ok)
+            return { ok: false, error: `resume attempt ${attemptId} has no successful activation to commit` };
+        const inventory = this.resumeInventory;
+        if (!inventory)
+            return { ok: false, error: `resume attempt ${attemptId} has no bound inventory` };
+        const authority = await Promise.all(inventory.agents.map(async (entry) => {
+            try {
+                await this.validateRetainedAuthority(entry);
+                return undefined;
+            }
+            catch (e) {
+                return `${entry.name}: ${e.message}`;
+            }
+        }));
+        const drift = authority.filter((error) => error !== undefined);
+        if (drift.length)
+            return { ok: false, error: `resume attempt ${attemptId} retained authority changed before commit: ${drift.join("; ")}` };
+        let inactive;
+        try {
+            inactive = this.resumeLivenessErrors(inventory, this.ep.getRoster());
+        }
+        catch (e) {
+            return { ok: false, error: `resume attempt ${attemptId} cannot verify live principals: ${e.message}` };
+        }
+        if (inactive.length)
+            return { ok: false, error: `resume attempt ${attemptId} is not live at commit: ${inactive.join("; ")}` };
+        this.resumeAwaitingCommit = false;
+        this.resumeCommitted = true;
+        this.resumeDurableCommitToken ??= randomBytes(32).toString("hex");
+        return {
+            ok: true,
+            data: { attemptId, state: "awaitingFinalize", durableCommitToken: this.resumeDurableCommitToken },
+        };
+    }
+    async handleActive(req, tier) {
         const args = req.args ?? {};
         // `req.from.id` is non-forgeable in auth mode: serveControl rejects any request whose payload
         // `from.id` doesn't match the subject sender (endpoint.ts). In open mode there are no creds, so
@@ -401,6 +1050,55 @@ export class Manager {
     managedPrincipal(a) {
         return a.userOwner ? a.id : principalKey(DEV_OWNER, a.id).key;
     }
+    resumeLivenessErrors(inventory, roster) {
+        const inactive = [];
+        const expectedNames = new Set(inventory.agents.map((entry) => entry.name));
+        for (const name of this.resumedAgentNames)
+            if (!expectedNames.has(name))
+                inactive.push(`${name} is not part of the bound inventory`);
+        for (const entry of inventory.agents) {
+            const managed = this.agents.get(entry.name);
+            if (!managed) {
+                inactive.push(`${entry.name} is no longer managed`);
+                continue;
+            }
+            const expectedId = entry.identity.mode === "user"
+                ? principalKey(entry.identity.owner, entry.identity.actor).key
+                : entry.identity.id;
+            const expectedPrincipal = entry.identity.mode === "user"
+                ? expectedId
+                : principalKey(DEV_OWNER, entry.identity.id).key;
+            if (managed.id !== expectedId || this.managedPrincipal(managed) !== expectedPrincipal) {
+                inactive.push(`${entry.name} no longer holds retained principal ${expectedPrincipal}`);
+                continue;
+            }
+            // The late paths (commit/finalize) must prove the SAME incarnation the incarnation-exact
+            // readiness fence proved (§13.1): a principal-only match lets a wrong/absent-uid presence under
+            // the reused alias satisfy commit/finalize after a readiness timeout, undoing the fence.
+            if (managed.lifecycleUid !== entry.identity.lifecycleUid) {
+                inactive.push(`${entry.name} manager metadata incarnation ${managed.lifecycleUid} drifted from the inventory's ${entry.identity.lifecycleUid}`);
+                continue;
+            }
+            if (managed.handle.name !== entry.name || managed.handle.kind !== entry.launch.runtime) {
+                inactive.push(`${entry.name} is not attached to its exact retained ${entry.launch.runtime} handle`);
+                continue;
+            }
+            try {
+                if (managed.handle.status() !== "running") {
+                    inactive.push(`${entry.name} runtime is not running`);
+                    continue;
+                }
+            }
+            catch (e) {
+                inactive.push(`${entry.name} runtime status failed: ${e.message}`);
+                continue;
+            }
+            if (!roster.some((presence) => presence.card.id === expectedPrincipal && presence.card.name === entry.name && presence.status !== "offline" &&
+                presence.lifecycleUid === entry.identity.lifecycleUid))
+                inactive.push(`${entry.name} incarnation ${entry.identity.lifecycleUid} (principal ${expectedPrincipal}) is not exactly present`);
+        }
+        return inactive;
+    }
     /** Self-despawn (P2b): stop the managed agent whose id == the authenticated caller. The
      *  no-name self-op can only ever resolve to the caller's OWN managed entry (ids are unique
      *  per spawn + non-forgeable in auth mode), never a peer — so it's structurally incapable of
@@ -412,7 +1110,7 @@ export class Manager {
             return { ok: false, error: `self-stop: caller ${callerId} is not a managed agent` };
         const graceful = args.graceful !== false;
         this.stopHandle(target, graceful);
-        this.freeSlot(target, true); // self-despawn is rate-floored (recycle churn)
+        this.trackStoppedHandle(target, true);
         return { ok: true, data: { name: target.name, stopped: true, graceful } };
     }
     // Plane-3 durable join/leave/list ops moved OFF the manager onto the server-side delivery daemon's
@@ -441,6 +1139,49 @@ export class Manager {
             console.error(`stop ${a.name} (${a.id}): ${e.message}`);
         }
     }
+    /** Keep an accepted stop inside the lifecycle drain until the runtime proves the child is gone,
+     * so a maintenance prepare can never fence ahead of a child that is still dying.
+     *
+     * An operator-accepted stop frees its slot at once: `stop` replying ✓ means `ps` no longer lists
+     * the agent. That cannot omit a still-live child from a cut, because runPreparation drains the
+     * lifecycle BEFORE it reads the roster — the exit proof below is what closes the race, not the
+     * slot lingering. A recursive reap (`requireAuthoritativeExit`) instead keeps the slot until the
+     * wait proves exit: nobody asked for those children to be gone, so they stay managed until the
+     * runtime says otherwise, and a runtime that cannot prove exit records an unverified stop. */
+    trackStoppedHandle(a, floor, requireAuthoritativeExit = false) {
+        if (!a.handle.waitForExit) {
+            // Preserve ordinary external-runtime stop behavior, but retain enough evidence for a later
+            // maintenance prepare to fail if that runtime still cannot prove the surface disappeared.
+            this.unverifiedStops.push({
+                name: a.name,
+                id: a.id,
+                handle: a.handle,
+                authoritative: requireAuthoritativeExit,
+                error: requireAuthoritativeExit
+                    ? `recursive reap cannot prove exit on runtime "${a.handle.kind}" (AgentHandle.waitForExit is not implemented)`
+                    : undefined,
+            });
+            if (requireAuthoritativeExit)
+                return;
+            this.freeSlot(a, floor, true);
+            return;
+        }
+        if (!requireAuthoritativeExit)
+            this.freeSlot(a, floor, true);
+        this.lifecycleInFlight++;
+        void this.awaitHandleExit(a.handle)
+            .then(() => this.freeSlot(a, floor, true)) // no-op once an accepted stop already freed it
+            .catch((e) => {
+            this.unverifiedStops.push({
+                name: a.name,
+                id: a.id,
+                handle: a.handle,
+                authoritative: true,
+                error: `accepted stop could not prove exit: ${e.message}`,
+            });
+        })
+            .finally(() => this.releaseLifecycle());
+    }
     /** USER-MODE spawn provisioning (the gate-1 counterpart to the static mint block): resolve the
      *  OWNER (ctl caller's principal, or the manifest's stamped owner — never a payload field),
      *  pre-create the principal-keyed durables + ACL row on the ephemeral provisioner, author the
@@ -469,15 +1210,19 @@ export class Manager {
         // pass through too (a persona may hold delegable roles) — the ledger's envelope walk still
         // attenuates every one of these against the spawner chain.
         const scope = (opts.capabilities ?? []).filter((c) => c === "spawn" || c === "admin" || /^role:[A-Za-z0-9_-]+$/.test(c));
-        const credsDir = join(authDir(this.workspaceRoot), "creds");
-        const tokenPath = join(credsDir, `${name}.actor-token`);
-        const sentinelPath = join(credsDir, `${name}.sentinel.creds`);
-        const healthPath = join(credsDir, `${name}.auth-health.json`);
+        // LOCAL composition, hardcoded: until the manager's entry is store-threaded (the same
+        // later slice as its renewal-owner store, with/after the membership-rw reader migration),
+        // a pure-KMS hosted manager CANNOT read the callout material this grant needs — hosted
+        // user-mode spawn via the manager is UNAVAILABLE, not silently degraded, until then.
+        const secrets = workspaceSecretStore(this.workspaceRoot);
+        const files = agentSecretFilePaths(this.workspaceRoot, name);
+        const { actorToken: tokenPath, sentinelCreds: sentinelPath, health: healthPath } = files;
         try {
             // The GRANT first — it is the envelope-rule enforcement point (a delegation must sit within
             // the spawner's own grant), so a refused delegation exits here having touched nothing beyond
             // the ledger: no durables, no broker footprint, nothing for a corrected respawn to race.
             const grant = await provider.grantAgent({
+                store: secrets,
                 dir,
                 space: this.space,
                 owner,
@@ -488,17 +1233,23 @@ export class Manager {
                 role: opts.role,
                 parent: spawnerPr ? opts.spawner : undefined,
                 label: opts.label,
+                lifecycleUid: opts.lifecycleUid,
             });
-            // Durables + ACL row, principal-keyed — the same onboarding as static agents minus the mint
-            // (a user agent's credential is its bearer, minted by the callout per connect).
-            await this.withProvisioner((prov) => provisionAgentDurables(prov, { owner, actor: name }, {
+            // Durables + ACL row, LIFECYCLE-keyed (SPEC 13.1) — the same onboarding as static agents minus
+            // the mint (a user agent's credential is its bearer, minted by the callout per connect from the
+            // ledger row's recorded lifecycleUid — the same value provisioned here).
+            await this.withProvisioner((prov) => provisionAgentDurables(prov, { owner, actor: name, lifecycleUid: opts.lifecycleUid }, {
                 subscribe: opts.subscribe,
                 allowSubscribe: opts.allowSubscribe,
                 role: opts.role,
             }));
-            mkSecretDir(credsDir);
-            writeSecretFile(tokenPath, grant.actorToken);
-            writeSecretFile(sentinelPath, grant.sentinelCreds);
+            // The store holds the source of truth; the bearer re-exec (`--token-file`) and the launch's
+            // sentinel handoff read FILES, so materialize both at the canonical paths (under the local
+            // FS composition, a byte-identical rewrite of the keys' own locations).
+            await secrets.put(agentActorTokenKey(name), grant.actorToken);
+            await secrets.put(agentSentinelCredsKey(name), grant.sentinelCreds);
+            await materializeSecretToFile(secrets, agentActorTokenKey(name), tokenPath);
+            await materializeSecretToFile(secrets, agentSentinelCredsKey(name), sentinelPath);
             rmSync(healthPath, { force: true }); // a fresh start opens a fresh health window
             const bearerCmd = [
                 // The manager's own invocation prefix (node + loader flags + the cotal entry) — the agent
@@ -525,10 +1276,12 @@ export class Manager {
             // may respawn the moment it reads the refusal, and a detached teardown would race (and
             // delete) that fresh spawn's just-provisioned durables.
             await provider.revokeAgent({ dir, owner, actor: name }).catch(() => { });
+            await secrets.delete(agentActorTokenKey(name)).catch(() => { });
+            await secrets.delete(agentSentinelCredsKey(name)).catch(() => { });
             rmSync(tokenPath, { force: true });
             rmSync(sentinelPath, { force: true });
             rmSync(healthPath, { force: true });
-            await this.deprovision({ id: principalKey(owner, name).key, name, userOwner: owner }).catch((err) => console.error(`rollback deprovision ${name}: ${err.message}`));
+            await this.deprovision({ id: principalKey(owner, name).key, name, lifecycleUid: opts.lifecycleUid, userOwner: owner }).catch((err) => console.error(`rollback deprovision ${name}: ${err.message}`));
             return { error: `agent auth preflight failed for "${name}": ${e.message}` };
         }
     }
@@ -537,17 +1290,31 @@ export class Manager {
      *  expires — flooring the RECYCLE, not the call, so both free paths (despawn + exit/reap) are
      *  covered (P4c). Floor self + own-child despawn and natural exit; NEVER admin despawn (operator
      *  emergency-kill stays unthrottled) and NEVER the reserved-rollback path (no cold-start paid). */
-    freeSlot(a, floor) {
+    freeSlot(a, floor, acceptedBeforeFence = false) {
         if (this.agents.get(a.name) !== a)
             return; // already freed (exit raced despawn, etc.)
         this.agents.delete(a.name);
         if (floor && Date.now() - a.startedAt < MIN_LIFETIME)
             this.cooling.push(a.startedAt + MIN_LIFETIME);
+        // #29 piece 3: on a USER mesh the name is RESERVED PENDING RETIREMENT — despawn started this
+        // lifecycle's FULL teardown (footprint + standing-authority revoke + the auth-side retirement),
+        // and the alias frees only when all of it completes (not the retirement alone). The detached
+        // deprovision below drives it; a failed revoke or an unreachable rail keeps the name held,
+        // re-driven by a retry. Gate on userMode BY
+        // CONSTRUCTION (NEW-1): a static-auth mint has no user-mode lifecycle head to retire, so the
+        // reservation + rail request simply don't apply there (the incidental nkey-parse used to mask
+        // this, but the intent is "user mode only", not "any principal-shaped id").
+        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, startedAt: Date.now() });
+        }
         // Auth mode: tear down the departed agent's minted broker footprint + creds file (#159 B2). The
         // process is already gone, so this must never block the slot free or throw into the caller — it runs
         // detached, and a failure is logged loudly (never swallowed), not retried. The `agents` guard above
         // makes this fire exactly once per agent across every free path (despawn / self-stop / reap / exit).
-        void this.deprovision(a).catch((e) => console.error(`deprovision ${a.name} (${a.id}): ${e.message}`));
+        if (!a.suppressCleanup && (this.maintenanceState === "active" || acceptedBeforeFence))
+            this.trackDeprovision(a);
     }
     /** Tear down a departed agent's minted footprint (#159 B2, auth mode): its local-principal durables
      *  (`dm_local-<id>`, `dlv_local-<id>`), its read-ACL row, and its creds file — everything the spawn's
@@ -564,53 +1331,208 @@ export class Manager {
     async deprovision(a) {
         if (!this.auth)
             return; // open mesh mints no creds/durables — nothing to tear down
+        // SINGLE-FLIGHT per (name, lifecycleUid) (INT-2/C): join an in-flight teardown for this exact
+        // lifecycle rather than launching a second concurrent one whose delayed name-keyed revoke could
+        // outlive the hold-clear and delete a successor's row. A fresh trigger after settle re-drives.
+        const key = JSON.stringify([a.name, a.lifecycleUid]); // ASCII-safe, delimiter-collision-free
+        const inflight = this.deprovisioningFlight.get(key);
+        if (inflight)
+            return inflight;
+        const flight = this.driveDeprovision(a).finally(() => {
+            if (this.deprovisioningFlight.get(key) === flight)
+                this.deprovisioningFlight.delete(key);
+        });
+        this.deprovisioningFlight.set(key, flight);
+        return flight;
+    }
+    /** The actual footprint teardown (wrapped by {@link deprovision}'s single-flight). */
+    async driveDeprovision(a) {
+        if (!this.auth)
+            return; // guaranteed by deprovision; re-checked for the deprovisionBroker narrowing
         // Drop the local creds file FIRST + unconditionally — it is a usable identity on disk, useless for a
         // departed agent, so it must not survive even if the broker teardown below fails or times out. The
         // teardown mints its OWN deprovisioner cred (not this file), so removing it early is independent.
-        rmSync(join(authDir(this.workspaceRoot), "creds", `${a.name}.creds`), { force: true });
+        // Migrated kinds: the store delete is the authoritative removal; the rmSync clears the FS
+        // materialization (a byte-identical no-op under the local composition, real once the manager
+        // is store-threaded onto a non-FS store).
+        const secrets = workspaceSecretStore(this.workspaceRoot);
+        const files = agentSecretFilePaths(this.workspaceRoot, a.name);
+        await secrets.delete(agentCredsKey(a.name));
+        rmSync(files.creds, { force: true });
         if (a.userOwner) {
             // USER MODE: this teardown IS revocation, not just footprint reduction — the ledger row is
             // the agent's standing mint authority, so delete it (next exchange refused, next connect
             // denied) and shred the secret/sentinel/health files. A copied actor token dies here; a
             // still-LIVE connection ends at its bearer-bound JWT expiry (≤ the agent TTL).
-            const credsDir = join(authDir(this.workspaceRoot), "creds");
-            for (const f of [`${a.name}.actor-token`, `${a.name}.sentinel.creds`, `${a.name}.auth-health.json`])
-                rmSync(join(credsDir, f), { force: true });
+            await secrets.delete(agentActorTokenKey(a.name));
+            await secrets.delete(agentSentinelCredsKey(a.name));
+            for (const f of [files.actorToken, files.sentinelCreds, files.health])
+                rmSync(f, { force: true });
+            // The ledger row IS the agent's STANDING mint authority (a different store from the auth-plane
+            // cred ledger the rail retirement covers): while it lives, a copied actor token can still mint a
+            // fresh connect credential. So a FAILED revoke must NOT be swallowed into a clean terminal (INT-2):
+            // mark the standing authority live on the hold so the retirement can never free the name (a freed
+            // name says "this lifecycle is fully gone" - false while the mint authority stands), and carry a
+            // legible operator copy. A retry re-drives this whole teardown (the same-name-spawn nudge routes
+            // through deprovision, not the rail alone), so the revoke is re-attempted, not stranded.
+            const holdRevoke = this.retiring.get(a.name);
+            if (holdRevoke && holdRevoke.lifecycleUid === a.lifecycleUid)
+                holdRevoke.standingAuthorityLive = true;
             try {
                 await resolveAuthProvider().revokeAgent({
                     dir: userAuthStateDir(this.workspaceRoot, this.space),
                     owner: a.userOwner,
                     actor: a.name,
                 });
+                const done = this.retiring.get(a.name);
+                if (done && done.lifecycleUid === a.lifecycleUid)
+                    done.standingAuthorityLive = false;
             }
             catch (e) {
+                const h = this.retiring.get(a.name);
+                if (h && h.lifecycleUid === a.lifecycleUid)
+                    h.lastError = `the agent's standing mint authority could not be revoked (${e.message}); the name stays held so a copied actor token cannot mint fresh credentials. NEXT: a same-name spawn re-drives the full teardown (including the revoke), or recover the auth state.`;
                 console.error(`revoke agent grant ${a.name}: ${e.message}`);
             }
         }
-        const creds = await mintCreds(this.auth, newIdentity(), "deprovisioner", { deprovisionTarget: a.id });
+        await this.deprovisionBroker(a);
+        // #29 piece 3: after the footprint teardown, ask the AUTH plane to RETIRE the lifecycle over
+        // the auth-admin rail. The rail re-checks the space-manager lease at serve time; the terminal
+        // (or an already-retired answer) clears the name reservation. Failures keep the hold with
+        // their operator copy — legible, retryable, never a silent half-state.
+        await this.requestRetirement(a);
+    }
+    /** Request the auth-side retirement of a departed agent's lifecycle (#29 piece 3): an ephemeral
+     *  `retirement-requester` credential (request + reply only), the generic `retireLifecycle` op,
+     *  a STABLE opId (derived from the lifecycleUid, so every retry re-drives the SAME operation),
+     *  and the four-outcome handling in operator vocabulary. */
+    async requestRetirement(a) {
+        if (!this.userMode)
+            return; // NEW-1: lifecycle retirement is a user-mesh concept; a static mint has no head to retire
+        // SINGLE-FLIGHT per (name, lifecycleUid) (audit #1): the detached deprovision call and every
+        // same-name-spawn nudge for THIS lifecycle share ONE in-flight retirement, so concurrent triggers
+        // never stack independent rail requests that dual-enter runAgentRetirementBarrier. Keyed by
+        // (name, uid), NOT name alone: driveRetirement clears the hold on rail ok but then yields at
+        // `nc.close()` with the flight still stored, so the alias can free and a SUCCESSOR (new uid) spawn.
+        // A name-only key would let that successor's own teardown JOIN the predecessor's still-pending
+        // flight and never send its OWN retirement — leaving the successor's lifecycle unretired. The uid in
+        // the key gives the successor a disjoint flight (mirrors {@link deprovisioningFlight}). A fresh
+        // trigger after settle re-drives (a still-present hold => retirement not yet confirmed).
+        const key = JSON.stringify([a.name, a.lifecycleUid]);
+        const inflight = this.retiringFlight.get(key);
+        if (inflight)
+            return inflight;
+        const flight = this.driveRetirement(a).finally(() => {
+            if (this.retiringFlight.get(key) === flight)
+                this.retiringFlight.delete(key);
+        });
+        this.retiringFlight.set(key, flight);
+        return flight;
+    }
+    /** The rail round-trip for one retirement (wrapped by {@link requestRetirement}'s single-flight). */
+    async driveRetirement(a) {
+        if (!this.auth)
+            return; // guaranteed by requestRetirement; re-checked for the type narrowing below
+        const held = this.retiring.get(a.name);
+        const me = parsePrincipalKey(this.ep.ref().id);
+        const target = parsePrincipalKey(a.id);
+        if (!me || !target) {
+            if (held)
+                held.lastError = "the manager or target principal could not be derived; the retirement was not requested";
+            return;
+        }
+        const uncertain = (why) => `the despawn stopped "${a.name}", but the retirement's completion could NOT be confirmed (${why}). The name stays held - not failed, not done - and a same-name spawn re-drives the same teardown; the auth service also finishes any started retirement on its next boot. NEXT: if the auth rail stays unreachable, recover the stack (\`cotal supervise\`), then re-attempt the same-name spawn.`;
+        try {
+            const creds = await mintCreds(this.auth, newIdentity(), "retirement-requester", { retirementRequester: { owner: me.owner, actor: me.actor } });
+            const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, authenticator: credsAuthenticator(new TextEncoder().encode(creds)), maxReconnectAttempts: 0 });
+            try {
+                const subject = controlServiceSubject(this.space, CONTROL_AUTH_ADMIN, me.owner, me.actor);
+                const m = await nc.request(subject, JSON.stringify({ op: "retireLifecycle", args: { owner: target.owner, actor: target.actor, lifecycleUid: a.lifecycleUid, opId: retireOpId(a.lifecycleUid) } }), { timeout: 20_000, noMux: true, reply: `${subject}.reply.${randomUUID()}` });
+                const r = m.json();
+                if (r.ok) {
+                    // CAS the hold clear (audit #1 ABA): free the alias ONLY if the current hold is still THIS
+                    // lifecycle's - a late reply for a retired predecessor must never clear a successor's newer hold.
+                    const cur = this.retiring.get(a.name);
+                    if (cur && cur.lifecycleUid === a.lifecycleUid) {
+                        if (cur.standingAuthorityLive) {
+                            // INT-2: the auth-plane lifecycle retired, but the manager-side STANDING mint authority is
+                            // not yet revoked (a failed revoke). Freeing the name here would be a false terminal (a
+                            // copied token could still mint), so keep the hold with its revoke-failure copy; a retry
+                            // re-drives the full teardown (revoke included).
+                            console.error(`despawn ${a.name}: the auth-plane lifecycle retired, but the standing mint authority is not yet revoked; the name stays held. ${cur.lastError ?? ""}`);
+                        }
+                        else {
+                            this.retiring.delete(a.name);
+                            console.error(`despawn ${a.name}: the agent's retirement completed; the name is free for reuse`);
+                        }
+                    }
+                    else {
+                        console.error(`despawn ${a.name}: retirement confirmed for a prior lifecycle of "${a.name}"; the current hold is left intact`);
+                    }
+                }
+                else {
+                    // The rail's refusal is already the operator copy (lease-loss/stale/foreign-op faces,
+                    // full-no-op statements included) - surface it INTACT, never flattened.
+                    if (held)
+                        held.lastError = r.error ?? "the auth service refused the retirement without a reason";
+                    console.error(`despawn ${a.name}: ${r.error ?? "the auth service refused the retirement without a reason"}`);
+                }
+            }
+            finally {
+                await nc.close().catch(() => { });
+            }
+        }
+        catch (e) {
+            const copy = uncertain(e.message);
+            if (held)
+                held.lastError = copy;
+            console.error(`despawn ${a.name}: ${copy}`);
+        }
+    }
+    /** The teardown's ASYNC BROKER PHASE: mint the ephemeral target-pinned deprovisioner cred and
+     *  delete the agent's broker footprint (dm_/dlv_ durables + read-ACL row). Split from
+     *  {@link deprovision} because it runs LAST in the ordered teardown chain — after the creds/secret
+     *  shred and the awaited ledger revoke, which precede it in that same single-flighted chain (the
+     *  revoke is awaited and can be deliberately slow, so it is not merely a synchronous prefix). The name
+     *  is NOT freed while any teardown phase is still in flight — the hold clears only after the
+     *  standing-authority revoke AND the lifecycle retirement both confirm (see {@link driveRetirement}) —
+     *  but the deletes here are still lifecycle-uid-pinned so even a replayed/stale teardown can never
+     *  reach a same-name successor's footprint (its names embed a different uid). */
+    async deprovisionBroker(a) {
+        // LIFECYCLE-PINNED (SPEC 13.1): both the credential's exact-name grants and the delete names
+        // carry a.lifecycleUid, so a stale/replayed teardown for this retired incarnation is broker-denied
+        // against a same-name successor's footprint (its names embed a different uid).
+        const creds = await mintCreds(this.auth, newIdentity(), "deprovisioner", {
+            deprovisionTarget: { principal: a.id, lifecycleUid: a.lifecycleUid },
+        });
         // Bound the detached broker teardown so a wedged broker can't leave the deprovision promise pending
         // forever with no log — the timeout rejects into freeSlot's fail-loud `.catch` (paired with the
         // helper's own fail-fast connect). The durables/ACL row still fall to space teardown as a backstop.
-        await withTimeout(deprovisionAgent({ servers: this.servers ?? DEFAULT_SERVER, space: this.space, targetId: a.id, creds }), DEPROVISION_TIMEOUT_MS, `deprovision ${a.name} (${a.id}): broker teardown timed out`);
+        await withTimeout(deprovisionAgent({ servers: this.servers ?? DEFAULT_SERVER, space: this.space, targetId: a.id, lifecycleUid: a.lifecycleUid, creds }), DEPROVISION_TIMEOUT_MS, `deprovision ${a.name} (${a.id}): broker teardown timed out`);
     }
-    /** Reap a parent's children on its exit (P4b): stop + free every agent whose `spawner` is the
-     *  exited agent's id, so orphans don't ratchet the ceiling shut. Recursive — a reaped child's
-     *  own children are reaped too. Exit-driven, so each freed slot is rate-floored like a despawn. */
+    /** Reap a parent's children on its exit (P4b). Every descendant remains managed until the runtime's
+     * authoritative wait proves exit; the wait participates in the lifecycle drain, so preservation can
+     * never omit a child that may still be alive. Recursive descendants are scheduled before their parent
+     * slot can disappear. */
     reapChildrenOf(parentId) {
         for (const child of [...this.agents.values()]) {
             if (child.spawner !== parentId)
                 continue;
+            this.reapChildrenOf(this.managedPrincipal(child));
             this.stopHandle(child, false);
-            this.freeSlot(child, true);
-            this.reapChildrenOf(child.id);
+            this.trackStoppedHandle(child, true, true);
         }
     }
     /** A managed agent's process exited on its own (crash, /exit, finished). Free its slot
      *  (rate-floored — exit-driven churn counts) and reap any children it spawned. Idempotent via
      *  freeSlot's identity guard, so a later graceful-stop SIGKILL firing exit again is a no-op. */
     onAgentExit(a) {
+        // Preservation owns the child-stop snapshot. Exit watchers must neither delete that snapshot nor
+        // trigger normal deprovision/reap while the cut is being formed.
+        if (this.maintenanceState !== "active")
+            return;
         this.freeSlot(a, true);
-        this.reapChildrenOf(a.id);
+        this.reapChildrenOf(this.managedPrincipal(a));
     }
     /** Agent names become `.cotal/agents/<name>.md` paths and mesh identities, so they must be bare
      *  tokens, never a path — blocks traversal / arbitrary writes from a model-supplied name. */
@@ -623,7 +1545,7 @@ export class Manager {
      *  in-flight (reserved) slots. Lets a colliding spawn auto-number instead of being rejected, so
      *  callers never have to invent a unique name. */
     uniqueName(base) {
-        return firstFreeName(base, (n) => this.agents.has(n) || this.reserved.has(n));
+        return firstFreeName(base, (n) => this.agents.has(n) || this.reserved.has(n) || this.retiring.has(n));
     }
     /** 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
@@ -835,7 +1757,7 @@ export class Manager {
         catch (e) {
             return { ok: false, error: e.message };
         }
-        const reply = await this.startAgent(launchAgentToStartOpts(la, configPath, spec.owner), caller);
+        const reply = await this.startAgent(launchAgentToStartOpts(la, configPath, spec.owner, runId), caller);
         if (reply.ok)
             // `data.name` stays the spawned (numbered) identity — what creds are filed under and the ledger
             // keys on; `requested`/`runId`/`hash` give the CLI the manifest name + drift hash for the ledger.
@@ -849,6 +1771,17 @@ export class Manager {
      *  defaulting to the manager's own id for roster/pre-spawn — recorded for the spawner
      *  ledger (own-children despawn + reap-on-parent-exit). */
     async startAgent(opts, spawner) {
+        const release = this.beginLifecycle();
+        if (!release)
+            return { ok: false, error: this.maintenanceError() };
+        try {
+            return await this.startAgentActive(opts, spawner);
+        }
+        finally {
+            release();
+        }
+    }
+    async startAgentActive(opts, spawner) {
         // 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
@@ -968,6 +1901,20 @@ export class Manager {
         const idErr = this.nameError(identityName);
         if (idErr)
             return { ok: false, error: opts.resolved ? `launch agent: ${idErr}` : `persona ${configPath}: ${idErr}` };
+        // 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`
+        // alone) so a retry re-drives the standing-authority revoke (INT-2) AND the broker cleanup before
+        // any hold-clear (C): the alias must not free while the durable teardown or the revoke is still
+        // outstanding. All the teardown ops are idempotent, and the rail request is single-flighted.
+        const held = this.retiring.get(identityName);
+        if (held !== undefined) {
+            void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner }).catch(() => { });
+            return {
+                ok: false,
+                error: `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.`,
+            };
+        }
         if (variant && !connector.supportsModelVariant)
             return { ok: false, error: `${agent} connector does not support model variants (variant)` };
         const name = this.uniqueName(identityName);
@@ -1000,6 +1947,10 @@ export class Manager {
             // A stable nkey identity assigned at spawn: the public key is the agent's card.id (threaded via
             // COTAL_ID); the seed is retained to mint matching creds later.
             const identity = newIdentity();
+            // The incarnation's lifecycle UID (SPEC 13.1), minted ONCE per spawn: every lifecycle-keyed
+            // broker resource (dm_/dlv_/chathist_ durables, ACL row, memberships) and the teardown
+            // credential carry it, so a same-name successor's footprint is name-disjoint by construction.
+            const lifecycleUid = mintLifecycleUid();
             // In auth mode, mint the agent's creds from the space signing key and write them where the
             // spawned session reads them (COTAL_CREDS path). Open mesh → no creds. Scope = the resolved
             // subscribe/allowSubscribe (read) + allowPublish (post, default-deny).
@@ -1016,6 +1967,7 @@ export class Manager {
                     role,
                     capabilities,
                     label: ref,
+                    lifecycleUid,
                 });
                 if ("error" in prep) {
                     this.reserved.delete(name);
@@ -1023,7 +1975,7 @@ export class Manager {
                 }
                 userLaunch = prep.launch;
                 userOwner = prep.owner;
-                provisioned = { id: principalKey(prep.owner, name).key, name, userOwner: prep.owner };
+                provisioned = { id: principalKey(prep.owner, name).key, name, lifecycleUid, userOwner: prep.owner };
             }
             else if (this.auth) {
                 // Pre-create the agent's bind-only chat (+ DM + role TASK) durables and mint its scoped creds
@@ -1036,11 +1988,16 @@ export class Manager {
                     allowPublish,
                     role,
                     capabilities,
+                    lifecycleUid,
                 }));
-                credsPath = join(authDir(this.workspaceRoot), "creds", `${name}.creds`);
-                mkSecretDir(dirname(credsPath)); // harden the creds dir before the cred lands
-                writeSecretFile(credsPath, creds);
-                provisioned = { id: identity.id, name }; // footprint now exists — the finally rolls it back if the spawn throws
+                // Store first (the source of truth), then materialize: `buildLaunch` hands the CHILD this
+                // file path, so the cred must exist as a file regardless of the store behind the seam.
+                // LOCAL composition, hardcoded, same posture as provisionUserAgent's grant store above.
+                const secrets = workspaceSecretStore(this.workspaceRoot);
+                credsPath = agentSecretFilePaths(this.workspaceRoot, name).creds;
+                await secrets.put(agentCredsKey(name), creds);
+                await materializeSecretToFile(secrets, agentCredsKey(name), credsPath);
+                provisioned = { id: identity.id, name, lifecycleUid }; // footprint now exists — the finally rolls it back if the spawn throws
             }
             // Personal MCP servers the operator opted to share with manager-spawned agents of this type
             // (cotal config; default none → isolated, the memory-safe default this guards), narrowed by
@@ -1050,6 +2007,11 @@ export class Manager {
             // arbitrary folders/repos. A relative path resolves against the workspace root; omitted → the
             // agent shares the workspace root (the prior, unchanged behavior).
             const cwd = opts.cwd ? resolve(this.workspaceRoot, opts.cwd) : this.workspaceRoot;
+            const configSha256 = this.fileDigest(configPath);
+            const manifestPath = opts.launchRef
+                ? join(this.workspaceRoot, ".cotal", "run", `${opts.launchRef.runId}.json`)
+                : undefined;
+            const manifestSha256 = manifestPath ? this.fileDigest(manifestPath) : undefined;
             const spec = connector.buildLaunch({
                 space: this.space,
                 name,
@@ -1059,6 +2021,10 @@ export class Manager {
                 id: userLaunch ? undefined : identity.id,
                 creds: credsPath,
                 userAuth: userLaunch,
+                // The incarnation's lifecycle UID: the agent endpoint binds its lifecycle-keyed dm/dlv/
+                // chathist durables by this exact value (its creds pin the same names, so a mismatch fails
+                // at the broker, never silently).
+                lifecycleUid,
                 servers: this.servers,
                 configPath,
                 model,
@@ -1090,11 +2056,41 @@ export class Manager {
                 role,
                 agent,
                 id: userLaunch ? principalKey(userLaunch.owner, name).key : identity.id,
+                lifecycleUid,
                 ...(userLaunch ? { userOwner } : { seed: identity.seed }),
                 spawner: spawner ?? this.ep.ref().id,
+                authorityParent: userLaunch && spawner && parsePrincipalKey(spawner) ? spawner : undefined,
                 startedAt: Date.now(),
                 handle,
                 control: spec.control,
+                launch: {
+                    source: opts.resolved
+                        ? {
+                            kind: "manifest",
+                            runId: opts.launchRef?.runId,
+                            requested: opts.launchRef?.requested ?? opts.resolved.name,
+                            hash: opts.launchRef?.hash ?? opts.resolved.hash,
+                            configPath,
+                            configSha256,
+                            manifestSha256,
+                        }
+                        : { kind: "persona", ref, configPath, configSha256 },
+                    cwd,
+                    model,
+                    variant,
+                    subscribe,
+                    allowSubscribe,
+                    allowPublish,
+                    capabilities,
+                    transcript,
+                    shareTools: opts.shareTools,
+                    forkSource: opts.resume,
+                    // Opaque values may contain secrets. Preserve only their keys and require the referenced
+                    // persona/manifest to resolve the values again; imperative overrides have no safe payload.
+                    unresolvedLaunchOptionKeys: opts.launchOptions && Object.keys(opts.launchOptions).length
+                        ? Object.keys(opts.launchOptions).sort()
+                        : undefined,
+                },
             };
             this.agents.set(name, managed);
             // The live slot now owns teardown — freeSlot deprovisions this identity on exit — so the
@@ -1128,10 +2124,402 @@ export class Manager {
             // orphan down (detached, fail-loud) so a failed spawn leaves no creds/durables behind (#159 B).
             if (provisioned) {
                 const orphan = provisioned;
-                void this.deprovision(orphan).catch((e) => console.error(`deprovision (orphaned spawn) ${orphan.name}: ${e.message}`));
+                this.trackDeprovision(orphan, "(orphaned spawn)");
+            }
+        }
+    }
+    /** Preflight the whole inventory before launching its first process, then adopt each exact retained
+     * principal without provisioning. A later runtime launch failure is reported per-agent, but malformed
+     * or missing inventory material can never produce a partially resumed set. */
+    async resumePreserved(inventory) {
+        const release = this.beginLifecycle(true);
+        if (!release)
+            return { ok: false, agents: [], error: this.maintenanceError() };
+        const batchReservations = [];
+        try {
+            if (inventory.version !== "cotal-manager-resume/v1")
+                return { ok: false, agents: [], error: `unsupported manager resume inventory version ${String(inventory.version)}` };
+            if (inventory.space !== this.space)
+                return { ok: false, agents: [], error: `resume inventory belongs to space "${inventory.space}", not "${this.space}"` };
+            const seen = new Set();
+            const principals = new Set();
+            await this.ep.waitForPresenceSnapshot();
+            const livePrincipals = new Set(this.ep.getRoster()
+                .filter((presence) => presence.status !== "offline")
+                .map((presence) => presence.card.id));
+            if (this.agents.size + this.reserved.size + this.coolingCount() + inventory.agents.length > MAX_AGENTS)
+                return { ok: false, agents: [], error: `resume inventory would exceed manager capacity (${MAX_AGENTS})` };
+            for (const entry of inventory.agents) {
+                if (seen.has(entry.name))
+                    return { ok: false, agents: [], error: `resume inventory contains duplicate agent name "${entry.name}"` };
+                seen.add(entry.name);
+                let principal;
+                try {
+                    principal = entry.identity.mode === "user"
+                        ? principalKey(entry.identity.owner, entry.identity.actor).key
+                        : principalKey(DEV_OWNER, entry.identity.id).key;
+                }
+                catch (e) {
+                    return { ok: false, agents: [], error: `invalid retained principal for ${entry.name}: ${e.message}` };
+                }
+                if (principals.has(principal))
+                    return { ok: false, agents: [], error: `resume inventory contains duplicate principal "${principal}"` };
+                principals.add(principal);
+                if (livePrincipals.has(principal))
+                    return { ok: false, agents: [], error: `retained principal "${principal}" is already live and this runtime cannot authoritatively adopt it` };
+                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` };
+            }
+            for (const entry of inventory.agents) {
+                this.reserved.add(entry.name);
+                batchReservations.push(entry.name);
+            }
+            const prepared = new Map();
+            const preflight = [];
+            for (const entry of inventory.agents) {
+                const reply = await this.resumePreservedAgent(entry, true, true, prepared);
+                preflight.push({ name: entry.name, reply });
+            }
+            const preflightFailures = preflight.filter(({ reply }) => !reply.ok);
+            if (preflightFailures.length)
+                return {
+                    ok: false,
+                    agents: preflight,
+                    error: `${preflightFailures.length} retained agent${preflightFailures.length === 1 ? "" : "s"} failed preflight`,
+                };
+            const agents = [];
+            for (let i = 0; i < inventory.agents.length; i++) {
+                const entry = inventory.agents[i];
+                const reply = await this.resumePreservedAgent(entry, false, true, prepared);
+                agents.push({ name: entry.name, reply });
+                if (!reply.ok) {
+                    for (const skipped of inventory.agents.slice(i + 1))
+                        agents.push({ name: skipped.name, reply: { ok: false, error: `not launched because ${entry.name} failed` } });
+                    return { ok: false, agents, error: reply.error };
+                }
+            }
+            if (this.resumeAttemptId)
+                this.resumeAwaitingCommit = true;
+            return { ok: true, agents };
+        }
+        finally {
+            for (const name of batchReservations)
+                this.reserved.delete(name);
+            release();
+        }
+    }
+    /** Re-read every retained identity input and its current authority without provisioning. This runs
+     * during whole-inventory preflight, immediately before each individual spawn, and at commit. */
+    async validateRetainedAuthority(entry) {
+        const referenceError = this.inventoryReferenceError(entry);
+        if (referenceError)
+            throw new Error(`retained agent ${entry.name}: ${referenceError}`);
+        if (entry.identity.mode === "open") {
+            if (this.auth || this.userMode)
+                throw new Error(`retained agent ${entry.name} is open-mode but the current manager is authenticated`);
+            return { id: entry.identity.id };
+        }
+        if (entry.identity.mode === "static") {
+            if (!this.auth || this.userMode)
+                throw new Error(`retained agent ${entry.name} is static-auth but the current manager is not`);
+            const expected = resolve(agentSecretFilePaths(this.workspaceRoot, entry.name).creds);
+            if (resolve(entry.identity.credential.path) !== expected)
+                throw new Error(`retained credential reference for ${entry.name} is not the manager-owned path ${expected}`);
+            let credentialText;
+            try {
+                // The lstat guards the FS MATERIALIZATION the child will read at launch; the identity check
+                // runs on the store's value — the source of truth (byte-identical here, the local FS
+                // composition resolves the key to this same path).
+                const st = lstatSync(expected);
+                if (!st.isFile() || st.isSymbolicLink())
+                    throw new Error("not a regular non-symlink file");
+                const stored = await workspaceSecretStore(this.workspaceRoot).get(agentCredsKey(entry.name));
+                if (stored === undefined)
+                    throw new Error("the credential is not in the secret store");
+                credentialText = stored;
+                const actual = idFromCreds(credentialText);
+                if (actual !== entry.identity.id)
+                    throw new Error(`retained credential identity ${actual} does not match inventory principal ${entry.identity.id}`);
             }
+            catch (e) {
+                throw new Error(`retained credential for ${entry.name} is unusable: ${e.message}`);
+            }
+            const accepted = await this.probeStaticCredential(credentialText);
+            if (!accepted.ok)
+                throw new Error(`retained credential for ${entry.name} is not accepted by the current broker (${accepted.reason})`);
+            return { id: entry.identity.id, creds: expected };
+        }
+        if (!this.userMode)
+            throw new Error(`retained agent ${entry.name} is user-auth but the current manager is not`);
+        try {
+            const provider = resolveAuthProvider();
+            // Mirror the static branch's expected-path equality: the store reads below are keyed by
+            // NAME, so a retained record aimed at a foreign path would otherwise pass its digest checks
+            // there while a different secret gets validated here. Canonical paths only.
+            const files = agentSecretFilePaths(this.workspaceRoot, entry.name);
+            if (resolve(entry.identity.actorToken.path) !== resolve(files.actorToken) ||
+                resolve(entry.identity.sentinelCredential.path) !== resolve(files.sentinelCreds))
+                throw new Error(`retained identity references are not the manager-owned paths under ${agentCredsDir(this.workspaceRoot)}`);
+            const secrets = workspaceSecretStore(this.workspaceRoot);
+            const actorToken = await secrets.get(agentActorTokenKey(entry.name));
+            const sentinelCreds = await secrets.get(agentSentinelCredsKey(entry.name));
+            if (actorToken === undefined || sentinelCreds === undefined)
+                throw new Error("the retained actor token / sentinel credential is not in the secret store");
+            const adopted = await provider.validateRetainedAgent({
+                store: secrets,
+                dir: userAuthStateDir(this.workspaceRoot, this.space),
+                space: this.space,
+                owner: entry.identity.owner,
+                actor: entry.identity.actor,
+                actorToken,
+                sentinelCreds,
+            });
+            if (adopted.owner !== entry.identity.owner || adopted.actor !== entry.identity.actor)
+                throw new Error(`auth provider returned a replacement principal; expected ${entry.identity.owner}.${entry.identity.actor}`);
+            // Bind the inventory's uid to the CURRENT authority row BEFORE any spawn: a corrupt or
+            // admin-supplied inventory naming a different incarnation is refused at pre-effect validation,
+            // never left to broker-fail after the child is already running (SPEC §13.1).
+            if (adopted.lifecycleUid !== entry.identity.lifecycleUid)
+                throw new Error(`retained user authority for ${entry.identity.owner}.${entry.identity.actor} is incarnation ${adopted.lifecycleUid}, not the inventory's ${entry.identity.lifecycleUid}; a resume binds the exact recovered uid before any spawn (SPEC 13.1)`);
+            if (!sameStrings(adopted.allowSubscribe, entry.launch.allowSubscribe) ||
+                !sameStrings(adopted.allowPublish, entry.launch.allowPublish) ||
+                !sameStrings(adopted.scope, entry.launch.capabilities) ||
+                adopted.role !== entry.role || adopted.parent !== entry.authorityParent)
+                throw new Error(`retained user authority for ${entry.identity.owner}.${entry.identity.actor} no longer matches the inventory`);
+            return {
+                userAuth: {
+                    owner: entry.identity.owner,
+                    actor: entry.identity.actor,
+                    sentinelCredsPath: entry.identity.sentinelCredential.path,
+                    bearerCmd: [
+                        process.execPath,
+                        ...process.execArgv,
+                        process.argv[1],
+                        provider.agentBearerCommand,
+                        "--dir", userAuthStateDir(this.workspaceRoot, this.space),
+                        "--space", this.space,
+                        "--owner", entry.identity.owner,
+                        "--actor", entry.identity.actor,
+                        "--token-file", entry.identity.actorToken.path,
+                        "--health-file", entry.identity.health.path,
+                    ],
+                },
+            };
+        }
+        catch (e) {
+            throw new Error(`retained user principal ${entry.identity.owner}.${entry.identity.actor} could not be reused: ${e.message}`);
+        }
+    }
+    /** 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) {
+        const release = this.beginLifecycle(batchReserved);
+        if (!release)
+            return { ok: false, error: this.maintenanceError() };
+        try {
+            if (entry.space !== this.space)
+                return { ok: false, error: `retained agent ${entry.name} belongs to space "${entry.space}", not "${this.space}"` };
+            if (entry.launch.runtime !== this.runtime.kind)
+                return { ok: false, error: `retained agent ${entry.name} requires runtime "${entry.launch.runtime}", current manager uses "${this.runtime.kind}"` };
+            const nameErr = this.nameError(entry.name);
+            if (nameErr)
+                return { ok: false, error: nameErr };
+            if (this.agents.has(entry.name) || (!batchReserved && this.reserved.has(entry.name)))
+                return { ok: false, error: `retained agent "${entry.name}" is already managed or reserved; same-principal resume never auto-numbers` };
+            if (!batchReserved && this.agents.size + this.reserved.size + this.coolingCount() >= MAX_AGENTS)
+                return { ok: false, error: `at capacity (${MAX_AGENTS} agents incl. in-flight + cooling); same-principal resume refused` };
+            const cached = prepared?.get(entry.name);
+            if (!preflightOnly && cached) {
+                try {
+                    // Do not trust the earlier batch preflight across another agent's sequential readiness wait.
+                    await this.validateRetainedAuthority(entry);
+                }
+                catch (e) {
+                    return { ok: false, error: e.message };
+                }
+                return this.launchPreparedResume(entry, cached, batchReserved);
+            }
+            try {
+                const cwd = lstatSync(entry.launch.cwd);
+                if (!cwd.isDirectory() || cwd.isSymbolicLink())
+                    return { ok: false, error: `retained cwd is not a real directory: ${entry.launch.cwd}` };
+            }
+            catch (e) {
+                return { ok: false, error: `retained cwd unavailable: ${entry.launch.cwd} (${e.message})` };
+            }
+            let connector;
+            try {
+                connector = registry.resolve("connector", entry.launch.connector);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            const missing = (connector.requires ?? []).filter((bin) => !resolveOnPath(bin));
+            if (missing.length)
+                return { ok: false, error: `${connector.name} harness needs ${missing.join(", ")} on PATH - not found` };
+            if (entry.launch.variant && !connector.supportsModelVariant)
+                return { ok: false, error: `${connector.name} connector does not support model variants (variant)` };
+            let launchOptions;
+            if (entry.launch.source.kind === "manifest") {
+                const launchSource = entry.launch.source;
+                if (!launchSource.runId)
+                    return { ok: false, error: `retained manifest launch for ${entry.name} has no runId; refusing to guess a .cotal/run source` };
+                let spec;
+                try {
+                    const source = launchSpecForRun(this.workspaceRoot, launchSource.runId);
+                    if (source.space !== this.space)
+                        return { ok: false, error: `retained launch spec space "${source.space}" does not match manager space "${this.space}"` };
+                    spec = source.agents.find((a) => a.name === launchSource.requested);
+                }
+                catch (e) {
+                    return { ok: false, error: e.message };
+                }
+                if (!spec || spec.hash !== launchSource.hash)
+                    return { ok: false, error: `retained manifest agent ${launchSource.requested} is missing or its hash changed; refusing same-principal resume` };
+                launchOptions = spec.launchOptions;
+            }
+            else {
+                try {
+                    launchOptions = loadAgentFile(entry.launch.source.configPath).launchOptions;
+                }
+                catch (e) {
+                    return { ok: false, error: e.message };
+                }
+            }
+            let authority;
+            try {
+                authority = await this.validateRetainedAuthority(entry);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            try {
+                const mcpServers = connectorServers(loadCotalConfig(this.workspaceRoot), entry.launch.connector, parseShareSelection(entry.launch.shareTools));
+                const spec = connector.buildLaunch({
+                    space: this.space,
+                    name: entry.name,
+                    role: entry.role,
+                    id: authority.id,
+                    creds: authority.creds,
+                    userAuth: authority.userAuth,
+                    // Recover the ORIGINAL incarnation uid (never a fresh mint on resume): the child endpoint
+                    // binds its lifecycle-keyed dm/dlv/chathist durables by this exact value, and its creds pin
+                    // the same names. Omitting it here (as the pre-fix resume path did) leaves the resumed child
+                    // with no COTAL_LIFECYCLE_UID: static/user fail the connector auth gate and open self-mints a
+                    // fresh uid that orphans the preserved durables and never matches the readiness fence.
+                    lifecycleUid: entry.identity.lifecycleUid,
+                    servers: this.servers,
+                    configPath: entry.launch.source.configPath,
+                    model: entry.launch.model,
+                    variant: entry.launch.variant,
+                    launchOptions,
+                    resume: entry.launch.forkSource,
+                    subscribe: entry.launch.subscribe,
+                    allowSubscribe: entry.launch.allowSubscribe,
+                    allowPublish: entry.launch.allowPublish,
+                    capabilities: entry.launch.capabilities,
+                    transcript: entry.launch.transcript,
+                    mcpServers,
+                    workspaceRoot: this.workspaceRoot,
+                });
+                const value = { spec, ...authority };
+                prepared?.set(entry.name, value);
+                if (preflightOnly)
+                    return { ok: true, data: { name: entry.name, preflight: true } };
+                return this.launchPreparedResume(entry, value, batchReserved);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+        }
+        finally {
+            release();
         }
     }
+    async launchPreparedResume(entry, prepared, batchReserved) {
+        if (!batchReserved)
+            this.reserved.add(entry.name);
+        try {
+            const handle = this.runtime.spawn(entry.name, prepared.spec, entry.launch.cwd);
+            const managed = {
+                name: entry.name,
+                role: entry.role,
+                agent: entry.launch.connector,
+                id: entry.identity.mode === "user" ? principalKey(entry.identity.owner, entry.identity.actor).key : entry.identity.id,
+                // Recover the ORIGINAL incarnation uid the durables are keyed by (never a fresh mint on resume).
+                lifecycleUid: entry.identity.lifecycleUid,
+                userOwner: entry.identity.mode === "user" ? entry.identity.owner : undefined,
+                spawner: entry.spawner,
+                authorityParent: entry.authorityParent,
+                startedAt: Date.now(),
+                handle,
+                control: prepared.spec.control,
+                launch: {
+                    source: entry.launch.source,
+                    cwd: entry.launch.cwd,
+                    model: entry.launch.model,
+                    variant: entry.launch.variant,
+                    subscribe: entry.launch.subscribe,
+                    allowSubscribe: entry.launch.allowSubscribe,
+                    allowPublish: entry.launch.allowPublish,
+                    capabilities: entry.launch.capabilities,
+                    transcript: entry.launch.transcript,
+                    shareTools: entry.launch.shareTools,
+                    forkSource: entry.launch.forkSource,
+                },
+                suppressCleanup: true,
+            };
+            this.agents.set(entry.name, managed);
+            if (this.resumeAttemptId)
+                this.resumedAgentNames.add(entry.name);
+            const readiness = await this.awaitReadiness(managed);
+            if (!readiness.ok && !readiness.uncertain)
+                return { ok: false, error: readiness.detail };
+            if (!readiness.ok) {
+                this.watchExit(managed);
+                this.watchResumeAdoption(managed);
+                return { ok: false, error: readiness.detail };
+            }
+            if (!this.resumeAttemptId)
+                managed.suppressCleanup = false;
+            this.watchExit(managed);
+            if (this.agents.get(managed.name) !== managed)
+                return { ok: false, error: `${managed.name} exited immediately after same-principal readiness` };
+            return {
+                ok: true,
+                data: { name: managed.name, role: managed.role, agent: managed.agent, id: managed.id, mode: handle.kind, resumed: true },
+            };
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        finally {
+            if (!batchReserved)
+                this.reserved.delete(entry.name);
+        }
+    }
+    probeStaticCredential(creds) {
+        return probeConnect(this.servers ?? DEFAULT_SERVER, { creds, timeoutMs: 5_000 });
+    }
+    /** An uncertain resume remains non-destructive until exact-principal AND exact-incarnation presence
+     *  arrives later. Same predicate as the readiness fence: a principal-only match would let a
+     *  wrong/absent-uid presence under the reused alias clear cleanup suppression on another incarnation. */
+    watchResumeAdoption(a) {
+        const wanted = this.managedPrincipal(a);
+        const onPresence = () => {
+            if (this.agents.get(a.name) !== a) {
+                this.ep.off("presence", onPresence);
+                return;
+            }
+            if (!this.ep.getRoster().some((p) => p.card.id === wanted && p.status !== "offline" && p.lifecycleUid === a.lifecycleUid))
+                return;
+            if (!this.resumeRequired)
+                a.suppressCleanup = false;
+            this.ep.off("presence", onPresence);
+        };
+        this.ep.on("presence", onPresence);
+        onPresence();
+    }
     /** #159 B1: wait for a detached launch to reach a REAL outcome before replying — never a liveness-
      *  inferring timer. Races three:
      *   • the assigned id joins presence (live) → **started** — the honest signal (the manager owns mesh
@@ -1158,7 +2546,16 @@ export class Manager {
         // through managedPrincipal or a static launch can never be seen joining (every static spawn would
         // resolve "uncertain"; caught by the lifecycle e2e).
         const wanted = this.managedPrincipal(a);
-        const joined = () => this.ep.getRoster().some((p) => p.card.id === wanted && p.status !== "offline");
+        // READINESS LIFECYCLE FENCE (SPEC 13.1): match the exact principal AND the exact lifecycle uid
+        // the manager minted for THIS spawn (presence carries it, §6/:315). The endpoint's own
+        // register-only broker proof is gated on the CLIENT-authored `card.kind`, which a managed child
+        // holding a valid agent credential could set to "endpoint" to skip - so it is defense-in-depth,
+        // NOT the authority boundary. This equality is: the manager (not the child) owns the expected
+        // uid, so a ghost that advertises a wrong/absent uid never reports STARTED, whatever kind it
+        // claims. The manager threads the uid into EVERY mode's launch (open included), so the child
+        // adopts it over a self-mint and publishes it in presence; the uid is absent only from a peer
+        // the manager never launched (a pure operator/daemon connection that never registers).
+        const joined = () => this.ep.getRoster().some((p) => p.card.id === wanted && p.status !== "offline" && p.lifecycleUid === a.lifecycleUid);
         return await new Promise((resolve) => {
             let done = false;
             let timer;
@@ -1255,7 +2652,7 @@ export class Manager {
             return { ok: false, error: denied };
         const graceful = args.graceful !== false;
         this.stopHandle(a, graceful);
-        this.freeSlot(a, !admin); // own-child despawn is rate-floored; admin emergency-kill is not
+        this.trackStoppedHandle(a, !admin);
         return { ok: true, data: { name, stopped: true, graceful } };
     }
     /** Open a short-lived PROVISIONER connection, run the onboarding ops on it, and drain it (closure (ii),
@@ -1392,7 +2789,7 @@ export class Manager {
             // FAIL-CLOSED: a failed record is the failure + repair sentence; a missing/malformed or
             // stale record on a live agent is auth-unknown/auth-stale, NEVER silently healthy.
             const health = a.userOwner
-                ? agentAuthState(join(authDir(this.workspaceRoot), "creds", `${a.name}.auth-health.json`))
+                ? agentAuthState(agentSecretFilePaths(this.workspaceRoot, a.name).health)
                 : undefined;
             return {
                 name: a.name,