@cotal-ai/manager 0.24.0 → 0.26.0

package/dist/manager.js

@@ -1,9 +1,10 @@
 import { execFile } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
+import { hostname } from "node:os";
 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, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, deprovisionAgent, firstFreeName, idFromCreds, inspectCredHealth, loadAgentFile, loadCotalConfig, mintCreds, mintLifecycleUid, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, epRequestSubject, epCallerReplyFilter, parseEpSubject, controlServiceSubject, eventChannelPrincipal, } from "@cotal-ai/core";
+import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_TTL_MS, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, idFromCreds, inspectCredHealth, loadAgentFile, loadCotalConfig, mintCreds, mintLifecycleUid, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, epRequestSubject, epCallerReplyFilter, parseEpSubject, controlServiceSubject, eventChannelPrincipal, } from "@cotal-ai/core";
 import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KEY, findCotalRoot, getSpaceAuth, hasUserAuthState, loadManagerInstanceIdentity, loadMeshes, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KEY, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, saveManagerInstanceIdentity, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
@@ -11,6 +12,7 @@ import { makeManagerEndpointEvictor } from "./endpoint-evict.js";
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts, parseLaunchSpec, persistLaunchSpec } from "./launch.js";
 import { authorizeLaunch, authorizeNamedControl } from "./authorize.js";
 import { controlShutdown } from "./control-shutdown.js";
+import { controlSession } from "./control-session.js";
 import { parseResumeCommitArgs, parseResumeControlArgs, parseResumeFinalizeArgs } from "./resume.js";
 // Unit B (the static §13.1 lifecycle executor): the shared grammar/stores from core plus the
 // manager-side adapter (transport + slot orchestration + the F1 terminal) — see static-lifecycle.ts.
@@ -43,6 +45,10 @@ const MIN_LIFETIME = 10_000;
  *  launch-parity smoke can assert every launch client's request timeout OUTLIVES this window — the tier
  *  rule forbids the clients importing it directly. */
 export const READINESS_TIMEOUT_MS = 30_000;
+/** Managed same-session crash recovery follows the Codex host precedent: three restarts are allowed
+ * inside a rolling two-minute window; the fourth crash is a loop and retires the seat loud. */
+const SESSION_RESTART_LIMIT = 3;
+const SESSION_RESTART_WINDOW_MS = 120_000;
 /** Upper bound on a detached agent-exit deprovision (#159 B2). A wedged broker must not leave the
  *  fire-and-forget teardown pending forever with no log — past this it rejects into freeSlot's fail-loud
  *  `.catch`. Generous over the helper's 5s connect timeout to allow the two consumer-deletes + ACL purge
@@ -1118,6 +1124,7 @@ export class Manager {
                 events: a.launch.events,
                 shareTools: a.launch.shareTools,
                 forkSource: a.launch.forkSource,
+                sessionId: a.restart?.armed ? this.readManagedSession(a) : a.launch.sessionId,
                 unresolvedLaunchOptionKeys: a.launch.unresolvedLaunchOptionKeys,
             },
             dependencies,
@@ -2032,6 +2039,8 @@ export class Manager {
             return; // already freed (exit raced despawn, etc.)
         a.terminalizing = true; // F5 latch (Unit B): also covers exit/reap paths that never rode stopHandle
         this.agents.delete(a.name);
+        if (a.restart?.sessionStatePath)
+            rmSync(a.restart.sessionStatePath, { force: true });
         // P2 item 6 (pin 4): end any live §13.6 attach session bound to THIS incarnation with the honest
         // `target-despawn` reason. Fires once per agent on every free path (despawn / self-stop / reap /
         // exit) via the `agents` guard above; a no-op when no plane or no live session for the target.
@@ -2204,11 +2213,23 @@ export class Manager {
         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 (!target) {
             if (held)
-                held.lastError = "the manager or target principal could not be derived; the retirement was not requested";
+                held.lastError = "the target principal could not be derived; the retirement was not requested";
+            return;
+        }
+        // The SERVE identity, not the endpoint identity, is who this request speaks as (#549). The field
+        // is declared `!:`, which asserts to the type system what the ordering happens to provide, so it
+        // is read here as what it actually is. On today's ordering this guard cannot fire: `start()`
+        // assigns the identity before it connects anything, and a retirement needs an agent that only a
+        // started manager can hold. It is kept as a fail-closed assertion rather than a live face,
+        // because the alternative is carrying `undefined` into the caller triple and surfacing the
+        // result as "the rail could not be reached", which would name the wrong cause.
+        const serveIdentity = this.managerServeIdentity;
+        if (!serveIdentity?.id) {
+            if (held)
+                held.lastError = `the retirement was NOT requested: this manager has no serve identity yet, so it cannot speak as the registered serving instance. The despawn stopped "${a.name}" and the name stays held. NEXT: let the manager finish registering, then re-attempt the same-name spawn to re-drive the teardown.`;
             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.`;
@@ -2216,7 +2237,22 @@ export class Manager {
             // The caller triple and the TARGET are both grant-pinned now (#350): the `handle` target
             // rides the subject, so this ephemeral credential can ask to retire exactly this
             // incarnation and nothing else.
-            const caller = { owner: me.owner, actor: me.actor, uid: this.managerLifecycleUid };
+            //
+            // THE TRIPLE IS THE SERVE PRINCIPAL, and it has to be (#549). The auth rail authorizes this
+            // request by comparing the caller's `<owner>.<actor>` against the serve issuance gate's bound
+            // principal, and that gate is opened with `principalKey(DEV_OWNER, serveIdentity.id)` (see the
+            // registration block). Deriving the caller from `ep.ref().id` instead put the manager's
+            // ENDPOINT identity nkey on the wire, which is a different, equally real identity of the same
+            // manager, so the comparison was unsatisfiable and EVERY user-mesh retirement was refused as a
+            // full no-op. Measured before the fix: 8 refusals in one suite run across 5 agents, with the
+            // epoch and the instance id both matching and only the principal disagreeing.
+            //
+            // Both halves come from the gate's own sources rather than from `ep.ref()`: `DEV_OWNER` is
+            // hard-coded at the gate site, so taking the owner from `ep.ref().id` would re-open the same
+            // mismatch in the owner half the moment a manager ran under a user-shaped identity. This is
+            // also the more honest attribution: the authority being exercised is "I am the registered
+            // serving instance", which is exactly what the gate records.
+            const caller = { owner: DEV_OWNER, actor: serveIdentity.id, uid: this.managerLifecycleUid };
             const creds = await mintCreds(this.auth, newIdentity(), "retirement-requester", {
                 retirementRequester: { ...caller, target: { owner: target.owner, actor: target.actor, lifecycleUid: a.lifecycleUid } },
             });
@@ -2325,14 +2361,191 @@ export class Manager {
             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. */
+    readSessionStatePath(path) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`cannot read connector session state ${path}: ${error.message}`);
+        }
+        const state = parsed;
+        if (state.version !== 1 || typeof state.sessionId !== "string" || !state.sessionId.trim() || state.sessionId.length > 4096 ||
+            (state.status !== "running" && state.status !== "quit"))
+            throw new Error(`connector session state ${path} is malformed`);
+        return { sessionId: state.sessionId, status: state.status };
+    }
+    readManagedSessionState(a) {
+        const path = a.restart?.sessionStatePath;
+        if (!path)
+            throw new Error("connector supplied no session state path");
+        return this.readSessionStatePath(path);
+    }
+    /** Upgrade bridge: inventories written before sessionId existed can still resume exactly after
+     *  the old Pi seat has loaded the new extension once and written its lifecycle-keyed state file. */
+    retainedSessionId(entry, connector) {
+        if (entry.launch.sessionId)
+            return entry.launch.sessionId;
+        if (!connector.supportsSessionContinuation)
+            return undefined;
+        const path = join(this.workspaceRoot, ".cotal", "pi-sessions", `${entry.name}-${entry.identity.lifecycleUid}.json`);
+        try {
+            return this.readSessionStatePath(path).sessionId;
+        }
+        catch (error) {
+            throw new Error(`retained ${connector.name} agent ${entry.name} has no sessionId in its older inventory and no usable upgrade state at ${path} ` +
+                `(${error.message}). Reload the live Pi seat before the preservation cut; refusing to resume fresh and lose its context.`);
+        }
+    }
+    readManagedSession(a) {
+        return this.readManagedSessionState(a).sessionId;
+    }
+    async awaitManagedSessionState(a) {
+        const deadline = Date.now() + 15_000;
+        let last = "session state not written yet";
+        while (Date.now() < deadline) {
+            if (a.handle.status() === "exited")
+                throw new Error("process exited before writing session state");
+            try {
+                return this.readManagedSessionState(a);
+            }
+            catch (error) {
+                last = error.message;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error(`connector did not write session state (${last})`);
+    }
+    /** Bind a continuation-capable connector only after its process is ready. The file proves the
+     *  latest in-process session (including Pi /resume); the authenticated socket proves this process
+     *  owns that session now. Presence may lead session_start by milliseconds, so both proofs are
+     *  awaited within a bounded readiness window rather than read once. */
+    async armSessionRecovery(a) {
+        if (!a.restart || !a.control)
+            return;
+        const state = await this.awaitManagedSessionState(a);
+        if (state.status !== "running")
+            throw new Error("connector reported a deliberate quit before readiness completed");
+        await this.awaitRecoveredSession(a, state.sessionId);
+        a.restart.armed = true;
+    }
+    async awaitRecoveredSession(a, expected, handle = a.handle, control = a.control) {
+        const deadline = Date.now() + 15_000;
+        let last = "control endpoint not ready";
+        while (Date.now() < deadline) {
+            if (handle.status() === "exited")
+                throw new Error("replacement process exited before reporting its session");
+            if (control) {
+                try {
+                    const reported = await controlSession(control);
+                    if (reported !== expected)
+                        throw new Error(`replacement reported session ${reported}, expected ${expected}`);
+                    return;
+                }
+                catch (error) {
+                    last = error.message;
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error(`replacement did not prove session ${expected} (${last})`);
+    }
+    /** Restart one continuation-capable managed process in place. Identity, lifecycle, credentials,
+     *  durables, children, and the manager row remain owned; only the process handle/control endpoint
+     *  change. A fourth crash inside two minutes is a loop and falls through to normal retirement. */
+    recoverManagedSession(a) {
+        const restart = a.restart;
+        if (!restart || !restart.armed || restart.recovering || a.terminalizing)
+            return;
+        const release = this.beginLifecycle();
+        if (!release)
+            return; // preservation owns the cut once the lifecycle fence closes
+        const now = Date.now();
+        restart.crashes = restart.crashes.filter((at) => now - at < SESSION_RESTART_WINDOW_MS);
+        restart.crashes.push(now);
+        if (restart.crashes.length > SESSION_RESTART_LIMIT) {
+            console.error(`! ${a.name}: Pi crash loop (${restart.crashes.length} crashes in ${SESSION_RESTART_WINDOW_MS / 1000}s) - retiring the managed seat`);
+            restart.armed = false;
+            this.freeSlot(a, true);
+            this.reapChildrenOf(this.managedPrincipal(a));
+            release();
+            return;
+        }
+        restart.recovering = true;
+        void (async () => {
+            let replacement;
+            try {
+                const sessionId = this.readManagedSession(a);
+                const connector = await this.resolveConnector(a.agent);
+                if (!connector.supportsSessionContinuation)
+                    throw new Error(`connector ${connector.name} no longer declares same-session continuation`);
+                const opts = {
+                    ...restart.opts,
+                    resume: undefined,
+                    prompt: undefined,
+                    continueSession: sessionId,
+                };
+                const spec = connector.buildLaunch(opts);
+                const handle = this.runtime.spawn(a.name, spec, a.launch.cwd);
+                replacement = handle;
+                restart.sessionStatePath = spec.sessionStatePath ?? restart.sessionStatePath;
+                await this.awaitRecoveredSession(a, sessionId, handle, spec.control);
+                if (this.agents.get(a.name) !== a || a.terminalizing) {
+                    try {
+                        handle.stop({ graceful: false });
+                    }
+                    catch { /* terminal path owns cleanup */ }
+                    return;
+                }
+                a.handle = handle;
+                a.control = spec.control;
+                replacement = undefined;
+                restart.opts = opts;
+                restart.recovering = false;
+                console.error(`! ${a.name}: recovered Pi session ${sessionId} after crash (${restart.crashes.length}/${SESSION_RESTART_LIMIT})`);
+                this.watchExit(a);
+            }
+            catch (error) {
+                restart.recovering = false;
+                restart.armed = false;
+                let tail = "";
+                try {
+                    tail = this.tail(await (replacement ?? a.handle).attach().backlog());
+                }
+                catch { /* runtime has no readable tail */ }
+                console.error(`! ${a.name}: Pi session recovery failed: ${error.message}${tail ? ` - last output: ${tail}` : ""} - retiring the managed seat`);
+                // The replacement may be alive but unable to prove the expected session. Stop it BEFORE
+                // retiring credentials/durables; otherwise an untracked process survives under torn auth.
+                try {
+                    replacement?.stop({ graceful: false });
+                }
+                catch { /* terminal cleanup continues */ }
+                this.freeSlot(a, true);
+                this.reapChildrenOf(this.managedPrincipal(a));
+            }
+            finally {
+                release();
+            }
+        })();
+    }
+    /** A managed agent's process exited on its own (crash, /exit, finished). Continuation-capable Pi
+     *  seats restart in place after readiness; every other exit follows the existing terminal path. */
     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;
+        if (a.restart?.armed && !a.terminalizing) {
+            try {
+                if (this.readManagedSessionState(a).status === "running") {
+                    this.recoverManagedSession(a);
+                    return;
+                }
+            }
+            catch (error) {
+                console.error(`! ${a.name}: cannot classify Pi process exit for recovery: ${error.message} - retiring the seat`);
+            }
+        }
         this.freeSlot(a, true);
         this.reapChildrenOf(this.managedPrincipal(a));
     }
@@ -2745,9 +2958,20 @@ export class Manager {
             allowSubscribe = opts.allowSubscribe ?? def.allowSubscribe ?? subscribe ?? ["general"];
             allowPublish = opts.allowPublish ?? def.allowPublish;
             capabilities = def.capabilities;
+            // #651: fold the persona's model into the launch record, mirroring the variant line below
+            // and the manifest branch above. Without this, a persona-file model (the common pin source)
+            // never reaches `launch.model`, so the connector runs the seat on it while `ps --wide`/`--json`
+            // reports the model ABSENT - a false "no model pinned" for a seat that has one.
+            model = opts.model ?? def.model;
             variant = opts.variant ?? def.variant;
             launchOptions = mergeLaunchOptions(def.launchOptions, opts.launchOptions);
         }
+        // #651: an empty or whitespace-only model string is not a pin. Coerce it to undefined here, at
+        // the single point every path (persona, manifest, imperative) has resolved `model`, so it
+        // serializes ABSENT rather than present-but-empty (`"model": ""`), which a key-presence consumer
+        // would misread as "a pin was recorded".
+        if (model !== undefined && model.trim() === "")
+            model = undefined;
         const idErr = this.nameError(identityName);
         if (idErr)
             return { ok: false, error: opts.resolved ? `launch agent: ${idErr}` : `persona ${configPath}: ${idErr}` };
@@ -2970,7 +3194,11 @@ export class Manager {
             // 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
             // an optional --share-tools selection (absent → all declared, the pre-merge behavior).
-            const mcpServers = connectorServers(loadCotalConfig(this.workspaceRoot), agent, parseShareSelection(opts.shareTools));
+            const cotalConfig = loadCotalConfig(this.workspaceRoot);
+            const mcpServers = connectorServers(cotalConfig, agent, parseShareSelection(opts.shareTools));
+            // The operator's spawn-env policy travels the same route: absent means the child inherits
+            // their environment, present means containment. A connector never reads the config itself.
+            const envAllow = spawnEnvAllow(cotalConfig);
             // Per-agent cwd overrides the manager's shared workspace root, so agents can be rooted at
             // arbitrary folders/repos. A relative path resolves against the workspace root; omitted → the
             // agent shares the workspace root (the prior, unchanged behavior).
@@ -2980,7 +3208,7 @@ export class Manager {
                 ? join(this.workspaceRoot, ".cotal", "run", `${opts.launchRef.runId}.json`)
                 : undefined;
             const manifestSha256 = manifestPath ? this.fileDigest(manifestPath) : undefined;
-            const spec = connector.buildLaunch({
+            const launchOpts = {
                 space: this.space,
                 name,
                 role,
@@ -3014,10 +3242,12 @@ export class Manager {
                 capabilities,
                 events,
                 mcpServers,
+                envAllow,
                 // So a connector that keeps per-agent local state can root it at the workspace, not the
                 // (possibly per-agent) launch cwd below. The cwd itself rides runtime.spawn, not the launch.
                 workspaceRoot: this.workspaceRoot,
-            });
+            };
+            const spec = connector.buildLaunch(launchOpts);
             const handle = this.runtime.spawn(name, spec, cwd);
             hooks?.onLaunched?.(); // P2 item 2: the "launched" progress edge (process spawned, pre-presence)
             const managed = {
@@ -3063,6 +3293,9 @@ export class Manager {
                         ? Object.keys(opts.launchOptions).sort()
                         : undefined,
                 },
+                ...(connector.supportsSessionContinuation
+                    ? { restart: { opts: launchOpts, sessionStatePath: spec.sessionStatePath, crashes: [], recovering: false, armed: false } }
+                    : {}),
             };
             // Unit B: the DURABLE slot takes the `active` phase before the in-memory row takes the
             // name — a crash between the two leaves an active-but-unadopted slot the boot sweep
@@ -3098,11 +3331,25 @@ export class Manager {
             } // failed → already reaped
             // Started OR uncertain: the agent stays managed, so wire the ongoing exit reaper (it reaps a later
             // death — including one that follows an `uncertain` verdict, which deliberately does NOT deprovision).
-            this.watchExit(managed);
             if (!readiness.ok) {
-                await hooks?.onOutcome?.({ kind: "uncertain" });
+                this.watchExit(managed);
+                await hooks?.onOutcome?.({ kind: "uncertain", data: { reason: readiness.detail } });
                 return { ok: false, error: readiness.detail };
-            } // uncertain — non-success, but kept
+            }
+            if (managed.restart) {
+                try {
+                    await this.armSessionRecovery(managed);
+                    managed.launch.sessionId = this.readManagedSession(managed);
+                }
+                catch (error) {
+                    const detail = `${managed.name} joined, but its exact host session could not be bound for supervised recovery: ${error.message}`;
+                    this.stopHandle(managed, false);
+                    this.freeSlot(managed, true);
+                    await hooks?.onOutcome?.({ kind: "failed", data: { error: detail } });
+                    return { ok: false, error: detail };
+                }
+            }
+            this.watchExit(managed);
             // Reply with the id the slot actually carries (user-mode: the owner.actor principal —
             // presence, ps, and the manifest ownership ledger all key on it; the throwaway static nkey
             // would never match and down -f would treat the agent as foreign).
@@ -3418,6 +3665,17 @@ export class Manager {
                 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 retainedSession;
+            try {
+                retainedSession = this.retainedSessionId(entry, connector);
+            }
+            catch (error) {
+                return { ok: false, error: error.message };
+            }
+            if (entry.launch.forkSource && !retainedSession && !connector.supportsResume)
+                return { ok: false, error: `${connector.name} connector does not support session fork (resume)` };
+            if (retainedSession && !connector.supportsSessionContinuation)
+                return { ok: false, error: `${connector.name} connector does not support exact-session continuation` };
             let launchOptions;
             if (entry.launch.source.kind === "manifest") {
                 const launchSource = entry.launch.source;
@@ -3453,8 +3711,10 @@ export class Manager {
                 return { ok: false, error: e.message };
             }
             try {
-                const mcpServers = connectorServers(loadCotalConfig(this.workspaceRoot), entry.launch.connector, parseShareSelection(entry.launch.shareTools));
-                const spec = connector.buildLaunch({
+                const resumeConfig = loadCotalConfig(this.workspaceRoot);
+                const mcpServers = connectorServers(resumeConfig, entry.launch.connector, parseShareSelection(entry.launch.shareTools));
+                const envAllow = spawnEnvAllow(resumeConfig);
+                const launchOpts = {
                     space: this.space,
                     name: entry.name,
                     role: entry.role,
@@ -3472,16 +3732,19 @@ export class Manager {
                     model: entry.launch.model,
                     variant: entry.launch.variant,
                     launchOptions,
-                    resume: entry.launch.forkSource,
+                    resume: retainedSession ? undefined : entry.launch.forkSource,
+                    continueSession: retainedSession,
                     subscribe: entry.launch.subscribe,
                     allowSubscribe: entry.launch.allowSubscribe,
                     allowPublish: entry.launch.allowPublish,
                     capabilities: entry.launch.capabilities,
                     events: entry.launch.events,
                     mcpServers,
+                    envAllow,
                     workspaceRoot: this.workspaceRoot,
-                });
-                const value = { spec, ...authority };
+                };
+                const spec = connector.buildLaunch(launchOpts);
+                const value = { spec, launchOpts, ...authority };
                 prepared?.set(entry.name, value);
                 if (preflightOnly)
                     return { ok: true, data: { name: entry.name, preflight: true } };
@@ -3544,7 +3807,11 @@ export class Manager {
                     events: entry.launch.events,
                     shareTools: entry.launch.shareTools,
                     forkSource: entry.launch.forkSource,
+                    sessionId: entry.launch.sessionId,
                 },
+                ...(prepared.spec.sessionStatePath
+                    ? { restart: { opts: prepared.launchOpts, sessionStatePath: prepared.spec.sessionStatePath, crashes: [], recovering: false, armed: false } }
+                    : {}),
                 suppressCleanup: true,
             };
             this.agents.set(entry.name, managed);
@@ -3558,6 +3825,17 @@ export class Manager {
                 this.watchResumeAdoption(managed);
                 return { ok: false, error: readiness.detail };
             }
+            if (managed.restart) {
+                try {
+                    await this.armSessionRecovery(managed);
+                    managed.launch.sessionId = this.readManagedSession(managed);
+                }
+                catch (error) {
+                    this.stopHandle(managed, false);
+                    this.freeSlot(managed, true, true);
+                    return { ok: false, error: `${managed.name} resumed, but its exact host session could not be rebound: ${error.message}` };
+                }
+            }
             if (!this.resumeAttemptId)
                 managed.suppressCleanup = false;
             this.watchExit(managed);
@@ -4615,7 +4893,10 @@ export class Manager {
                     ({ fact } = await commitGoalResult(gw.ctx, { ref, now: Date.now(), cause: "complete", state: "failed", data: o.data, committer: { instanceId: this.managerInstanceId, epoch } }));
                 }
                 else {
-                    ({ fact } = await settleGoalUncertain(gw.ctx, { ref, now: Date.now(), committer: { instanceId: this.managerInstanceId, epoch } }));
+                    // Forward the readiness detail as the terminal's reason: this manager owns the deadline,
+                    // so it owns what elapsing it MEANS. Absent, core commits its own generic line (#605).
+                    const why = o.data?.reason;
+                    ({ fact } = await settleGoalUncertain(gw.ctx, { ref, now: Date.now(), committer: { instanceId: this.managerInstanceId, epoch }, ...(typeof why === "string" && why.length > 0 ? { reason: why } : {}) }));
                 }
                 this.emitGoalProgress(ref, epoch, { phase: "terminal", state: fact.state, ...(fact.data !== undefined ? { data: fact.data } : {}) });
                 await clearGoalIndex(gw.ctx, ref); // must-5 Q-B: terminal reached - the successor never reconciles it
@@ -5227,6 +5508,17 @@ export class Manager {
                 // The incarnation coordinate (SPEC 13.1) — with `id`, exactly what a v0.4 caller needs to
                 // build a targeted (`despawn`/`attach`) request against THIS incarnation.
                 lifecycleUid: a.lifecycleUid,
+                // #651 enrichment: per-seat facts the manager ALREADY holds, carried on the row so `ps
+                // --wide`/`--json` can surface them without a new collection path. All optional in the row
+                // schema: a fact this backend did not record serializes absent, never fabricated (the
+                // pid is absent on runtimes that do not own a real process; a launch may pin no model).
+                model: a.launch.model,
+                variant: a.launch.variant,
+                cwd: a.launch.cwd,
+                pid: a.handle.pid,
+                spawner: a.spawner,
+                instanceId: this.managerInstanceId,
+                host: hostname(),
                 ...(health && health.state !== "ok" ? { authHealth: health.state, authReason: health.reason } : {}),
             };
         });