@cotal-ai/manager 0.45.0 → 0.47.0

package/dist/manager.js

@@ -1,12 +1,12 @@
 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 { 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_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, 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_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, 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_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, saveManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
-import { createRuntime, } from "./runtime/index.js";
+import { createRuntime, requireRuntimeAdopt, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
 import { makeManagerEndpointEvictionEvidence, makeManagerEndpointEvictor } from "./endpoint-evict.js";
 import { makeManagerHolderLivenessProbe } from "./holder-liveness.js";
@@ -14,6 +14,7 @@ import { GateReconcileRefused, reconcileEndpointGate } from "./reconcile-gate.js
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts, parseLaunchSpec, persistLaunchSpec } from "./launch.js";
 import { authorizeLaunch, authorizeNamedControl } from "./authorize.js";
 import { controlShutdown } from "./control-shutdown.js";
+import { RunHosting } from "./run-hosting.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
@@ -30,7 +31,7 @@ import { ManagerSessionPlane, openSessionLedgerKv } from "./session/index.js";
 // the register/authorize/serve seams, all driven over a scoped one-shot executor connection.
 import { provisionEndpointGateOpen, endpointRegistrationBarrier, serveIssuanceGateKv, commitSiblingIssuance, markLedgerRowRevoked, epcredRowKey, epgateKey, parseEndpointGate, registerServiceInstance, deregisterServiceInstance, authorizeServeGrant, writeServiceStatus, SERVICE_READY, serveEndpoint, bindGoal, createGoal, transitionGoal, commitGoalResult, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, mintCheckpoint, resumeCheckpoint, readCheckpointSettle, readCheckpointSpec, expireCheckpoint, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, epeSubject, submissionFingerprint, EpEnvelopeError, lifecycleBlocked, renderLifecycleBlocked, } from "@cotal-ai/core";
 import { MANAGER_ENDPOINT, managerClusterArtifacts, managerCommandDefs, managerContractArtifactValues } from "./manager-service-contract.js";
-import { staticLifecycleTransport, activateStaticLifecycle, runStaticTerminal, readStaticSlot, casStaticSlot, recordSlotCredential, appendStaticCredentialRow, planStaticSlotResume, } from "./static-lifecycle.js";
+import { staticLifecycleTransport, activateStaticLifecycle, runStaticTerminal, readStaticSlot, casStaticSlot, recordSlotCredential, appendStaticCredentialRow, planStaticSlotResume, observeStaticSlot, renderStaticSlotObservation, StaticSlotReadError, STATIC_SLOT_READ_FAILED_DETAIL, } from "./static-lifecycle.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;
@@ -136,6 +137,8 @@ const FREE_SLOT_CAUSE_TEXT = {
     "process-exit": "its own process exited and this manager did not stop it",
     "pi-crash-loop": "this manager retired it after a Pi crash loop",
     "pi-recovery-failed": "this manager retired it after Pi session recovery failed",
+    "supervise-crash-loop": "this manager retired it after its supervise restart budget was spent",
+    "supervise-recovery-failed": "this manager retired it after a supervised restart failed",
     "session-bind-failed": "this manager stopped it: its host session could not be bound at launch",
     "resume-session-rebind-failed": "this manager stopped it: its host session could not be rebound on resume",
 };
@@ -319,6 +322,10 @@ export class Manager {
      *  manager reads its OWN `epgate.<e>.<iid>` epoch over this connection before a terminal commit
      *  and skips a superseded commit (the fast-fail belt paired with the (b) barrier-revoke fence). */
     goalWriter;
+    /** The workflow-run host (SPEC 14.3): the drives this incarnation holds, each on its own
+     *  per-run credential and connection. Absent under a remote authority, which mints no driver
+     *  credentials, so the `run-*` family refuses there rather than connecting on a weaker identity. */
+    runHosting;
     /** P2 item 2 must-5 (b): the STABLE goal-writer identity (auth mode) — minted once at
      *  registration alongside the serve identity; a renewal re-mints the SAME nkey with a fresh
      *  bounded exp and re-stages its distinct credId into the §13.1 revocation family. The current
@@ -455,6 +462,17 @@ export class Manager {
     resumeDurableCommitToken;
     resumedAgentNames = new Set();
     remoteAuthority;
+    /** Every broker dial this manager makes, through ONE transport decision.
+     *
+     *  `this.servers` is whatever the mesh record held (`cotal supervise` reads it from there), so it
+     *  can be a `ws://`/`wss://` broker published through an HTTPS edge. The raw node transport
+     *  refuses such a URL instead of dialing it, so the scheme picks the dialer here rather than at
+     *  thirteen call sites. `dialerFor` also owns the websocket transport's options, which is why
+     *  callers below still pass their own auth options unchanged. */
+    dial(opts) {
+        const servers = this.servers ?? DEFAULT_SERVER;
+        return dialerFor(servers)({ ...opts, servers });
+    }
     constructor(opts) {
         this.space = opts.space;
         this.servers = opts.servers;
@@ -495,6 +513,10 @@ export class Manager {
     get runtimeKind() {
         return this.runtime.kind;
     }
+    /** Reattach this manager's runtime to a durable handle. Refuses by name when adopt is absent. */
+    adoptRuntimeHandle(reference) {
+        return requireRuntimeAdopt(this.runtime, reference);
+    }
     /** The console page URL (manager-hosted, loopback). */
     get consoleUrl() {
         return this.attach.consoleUrl();
@@ -699,6 +721,25 @@ export class Manager {
         // BEFORE spawn-as-action begins accepting (the goalReconcileDone gate) — a fresh incarnation
         // never drops a goal a dead predecessor accepted. Never fatal; the gate opens either way.
         await this.reconcileGoalIndex();
+        // SPEC 14.3: the manager hosts workflow runs. Stood up AFTER registration (it names this
+        // instance's coordinates) and reconciled AFTER the goal index, for the same reason: a fresh
+        // incarnation takes back every run a dead predecessor was driving before it accepts new ones.
+        // The serve surface is already live by here, so the family itself holds the gate: `runHost()`
+        // refuses `run-start`/`run-resume` as `unavailable` until the host exists and `RunHosting`
+        // refuses them until its reconcile has returned. A user-auth mesh stands no host up at all
+        // (`runHost()` names why); a remote-authority manager holds no signer to mint with.
+        if (!this.remoteAuthority && !this.userMode) {
+            this.runHosting = new RunHosting({
+                space: this.space,
+                servers: this.servers,
+                endpoint: MANAGER_ENDPOINT,
+                instanceId: this.managerInstanceId,
+                holder: { id: this.ep.ref().id, lifecycleUid: this.managerLifecycleUid },
+                auth: this.auth,
+                log: (line) => console.error(line),
+            });
+            await this.runHosting.reconcile();
+        }
         // Plane-3 (durable backstop) is NOT the manager's job — the manager only manages agent lifecycle.
         // The server-side delivery daemon hosts the fan-out writer + trusted reader, owns the durable
         // membership registry, and serves the runtime durable join/leave/list ops (on `ctl.delivery`). The
@@ -835,6 +876,9 @@ export class Manager {
             // scoped executor. Without this the standing session-ledger connection dies at its TTL and
             // `attach` stops establishing sessions until a restart. The connection's authenticator presents
             // the refreshed credential on its next (re)connect.
+            // SPEC 14.6: every hosted drive's per-run `run-driver` credential is the manager's to renew
+            // for the same nkey; a run parked in a pause for days must not die at the credential's TTL.
+            await this.runHosting?.renew();
             if (this.sessionLedgerConn && this.sessionLedgerCreds && this.auth) {
                 const sw = this.sessionLedgerConn;
                 try {
@@ -1121,8 +1165,6 @@ export class Manager {
     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`);
@@ -1336,6 +1378,10 @@ export class Manager {
         // in-flight command can write a status back onto the record it just removed.
         const registered = this.serviceServe !== undefined;
         await this.stopServiceServe();
+        // The drives AFTER the serve loop (no new `run-start` can land) and BEFORE deregistration: a
+        // released run's status write is the last thing this incarnation says about it.
+        await this.runHosting?.stop();
+        this.runHosting = undefined;
         if (registered)
             await this.deregisterServiceOnStop();
         await this.stopGoalWriter();
@@ -1759,6 +1805,35 @@ export class Manager {
      *  cross-owner persona writes - an operator redefines via config, not the wire), where the ctl
      *  admin tier allowed operator cross-owner redefine; (2) launch is owner-equality-only, above.
      *  Both are least-privilege reductions, never widenings. */
+    /** The run host, or one of three refusals. A remote-authority manager holds no space signer, so
+     *  it cannot mint the per-run driver credential SPEC 14.6 requires, and hosting on any other
+     *  identity would be the fallback this tree does not take: `unimplemented`, for good. A
+     *  user-auth mesh is `unimplemented` too, for a different reason it names: a hosted run's seats
+     *  are spawned, turned and despawned by a caller derived from the run id under the static
+     *  owner, which the user-mode spawn door refuses (no `u_` owner), so a program would fail at
+     *  its first seat; no path to `--local` is offered there since a user bearer holds no run rows
+     *  either. An ordinary manager whose host is not standing yet is still booting (the serve
+     *  surface comes up before the host): `unavailable`, retry. The three are told apart, since
+     *  the first sentence steers a caller to `--local` and the others must not. */
+    runHost() {
+        if (this.runHosting)
+            return this.runHosting;
+        if (this.remoteAuthority)
+            throw new EpEnvelopeError("unimplemented", "this manager does not host workflow runs: a remote-authority manager mints no run-driver credentials (SPEC 14.6); drive the run from a terminal with `cotal run start --local --file <program>`");
+        if (this.userMode)
+            throw new EpEnvelopeError("unimplemented", `user-auth space "${this.space}" hosts no workflow runs yet: a hosted run's seats would be spawned under the static owner, which a user mesh refuses; run programs on a static-auth mesh`);
+        throw new EpEnvelopeError("unavailable", "the manager is still booting its workflow-run host; retry shortly (SPEC 14.3)");
+    }
+    /** The answerer a `run-answer` records (SPEC 14.5): the caller as this manager knows them. A
+     *  managed seat is named by its persona name; any other authenticated caller (an operator
+     *  instrument, a logged-in user) by its principal. Never the request body's word. */
+    runAnswerer(ctx) {
+        const caller = principalKey(ctx.subject.caller.owner, ctx.subject.caller.actor).key;
+        for (const a of this.agents.values())
+            if (this.managedPrincipal(a) === caller)
+                return a.name;
+        return caller;
+    }
     managerServiceDefs() {
         const args = (ctx) => (ctx.request.args ?? {});
         const callerOf = (ctx) => principalKey(ctx.subject.caller.owner, ctx.subject.caller.actor).key;
@@ -1794,8 +1869,34 @@ export class Manager {
             inspect: (ctx) => this.serveGated(ctx, async () => {
                 const name = String(args(ctx).name ?? "").trim();
                 const row = this.list(await this.psOwnerFilter(callerOf(ctx), false)).find((x) => x.name === name);
-                if (!row)
+                if (!row) {
+                    // The live hit above stays entirely local. Only a miss widens into durable static state,
+                    // where `not-found` is honest only after the slot read itself succeeds and returns absent.
+                    // User-mode lifecycles have no manager-local mgrslot row; their per-name projection remains
+                    // the live map until the auth service exposes an equivalent mediated reader.
+                    if (this.auth && !this.userMode) {
+                        const recordsKv = this.goalWriter?.ctx.kv;
+                        if (!recordsKv)
+                            throw new EpEnvelopeError("unavailable", `the durable static slot store is not ready while inspecting "${name}"`, [
+                                { kind: STATIC_SLOT_READ_FAILED_DETAIL, name, record: "slot", operation: "read" },
+                            ]);
+                        let observed;
+                        try {
+                            observed = await observeStaticSlot(recordsKv, DEV_OWNER, name, this.managerInstanceId);
+                        }
+                        catch (error) {
+                            throw new EpEnvelopeError("unavailable", `the durable static slot state for "${name}" could not be read: ${error.message}`, [
+                                { kind: STATIC_SLOT_READ_FAILED_DETAIL, name, record: error instanceof StaticSlotReadError ? error.record : "slot-or-head", operation: "read" },
+                            ]);
+                        }
+                        // A retired row affirms that no agent exists now, so it keeps the old `not-found`
+                        // result. The changed refusal is reserved for durable NONTERMINAL state that contradicts
+                        // the live-map miss and needs operator attention.
+                        if (observed !== undefined && observed.slotPhase !== "retired")
+                            throw new EpEnvelopeError("failed-precondition", `no live agent "${name}"; durable state contradicts absence ${renderStaticSlotObservation(observed)}`, [observed]);
+                    }
                     throw new EpEnvelopeError("not-found", `no agent "${name}"`);
+                }
                 return row;
             }),
             models: (ctx) => this.serveGated(ctx, async () => {
@@ -1873,6 +1974,13 @@ export class Manager {
             resumePreserved: (ctx) => adminGated(ctx, async () => unwrap(await this.opResumePreserved(args(ctx)))),
             commitResume: (ctx) => adminGated(ctx, async () => unwrap(await this.opCommitResume(args(ctx)))),
             finalizeResume: (ctx) => adminGated(ctx, async () => unwrap(await this.opFinalizeResume(args(ctx)))),
+            // The workflow-run family (SPEC 14.3): the manager hosts the driver. Reach is the broker's
+            // (`run` capability / privileged instrument rows); the serve gate is the maintenance fence.
+            runStart: (ctx) => this.serveGated(ctx, () => this.runHost().start(args(ctx))),
+            runResume: (ctx) => this.serveGated(ctx, () => this.runHost().resume(args(ctx))),
+            runAnswer: (ctx) => this.serveGated(ctx, () => this.runHost().answer(args(ctx), this.runAnswerer(ctx))),
+            runStatus: (ctx) => this.serveGated(ctx, () => this.runHost().status(args(ctx))),
+            runPs: (ctx) => this.serveGated(ctx, () => this.runHost().list(args(ctx))),
             preparePreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("preparePreservation", args(ctx)))),
             commitPreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("commitPreservation", args(ctx)))),
             abortPreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("abortPreservation", args(ctx)))),
@@ -2101,7 +2209,7 @@ export class Manager {
         // vocabulary as static capabilities; the broker maps them to the ctl tiers. `role:<r>` tokens
         // 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 scope = (opts.capabilities ?? []).filter((c) => c === "spawn" || c === "run" || c === "admin" || /^role:[A-Za-z0-9_-]+$/.test(c));
         // The manager's ONE store (injected for a hosted composition, workstation FS locally). A hosted
         // user-mode spawn reads the callout material from it — the same store the auth-store kinds
         // (callout/issuer/…) were migrated onto — so this is no longer a local-only path.
@@ -2441,7 +2549,7 @@ export class Manager {
             const creds = await mintCreds(this.auth, newIdentity(), "retirement-requester", {
                 retirementRequester: { ...caller, target: { owner: target.owner, actor: target.actor, lifecycleUid: a.lifecycleUid } },
             });
-            const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, authenticator: credsAuthenticator(new TextEncoder().encode(creds)), maxReconnectAttempts: 0 });
+            const nc = await this.dial({ authenticator: credsAuthenticator(new TextEncoder().encode(creds)), maxReconnectAttempts: 0 });
             try {
                 // §13.2 nonce: >=128 bits of CSPRNG entropy, base64url (the `endpoint-invoke` idiom).
                 const nonce = randomBytes(24).toString("base64url");
@@ -2635,9 +2743,10 @@ export class Manager {
         }
         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. */
+    /** Restart one managed process in place. Identity, lifecycle, credentials, durables, children,
+     *  and the manager row remain owned; only the process handle/control endpoint change. Budget
+     *  comes from `restart.policy` when spawn carried `supervise`; otherwise the Pi session-recovery
+     *  constants. Spending the budget falls through to normal retirement. */
     recoverManagedSession(a) {
         const restart = a.restart;
         if (!restart || !restart.armed || restart.recovering || a.terminalizing)
@@ -2646,12 +2755,15 @@ export class Manager {
         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);
+        const limit = restart.policy?.restarts ?? SESSION_RESTART_LIMIT;
+        const windowMs = restart.policy?.windowMs ?? SESSION_RESTART_WINDOW_MS;
+        const supervised = restart.policy !== undefined;
+        restart.crashes = restart.crashes.filter((at) => now - at < windowMs);
         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`);
+        if (restart.crashes.length > limit) {
+            console.error(`! ${a.name}: ${supervised ? "supervised" : "Pi"} crash loop (${restart.crashes.length} crashes in ${windowMs / 1000}s) - retiring the managed seat`);
             restart.armed = false;
-            this.freeSlot(a, true, "pi-crash-loop");
+            this.freeSlot(a, true, supervised ? "supervise-crash-loop" : "pi-crash-loop");
             this.reapChildrenOf(this.managedPrincipal(a));
             release();
             return;
@@ -2660,21 +2772,40 @@ export class Manager {
         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 continueSession = connector.supportsSessionContinuation ? this.readManagedSession(a) : undefined;
+                const opts = continueSession !== undefined
+                    ? { ...restart.opts, resume: undefined, prompt: undefined, continueSession }
+                    : { ...restart.opts, resume: undefined, prompt: undefined };
                 const spec = connector.buildLaunch(opts);
+                const wanted = this.managedPrincipal(a);
+                const joinedAfter = this.ep.getRoster()
+                    .filter((p) => p.card.id === wanted && p.lifecycleUid === a.lifecycleUid)
+                    .reduce((max, p) => Math.max(max, p.ts), 0) + 1;
                 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 (continueSession !== undefined)
+                    await this.awaitRecoveredSession(a, continueSession, handle, spec.control);
+                else {
+                    const previousHandle = a.handle;
+                    const previousControl = a.control;
+                    a.handle = handle;
+                    a.control = spec.control;
+                    try {
+                        const readiness = await this.awaitReadiness(a, connector.readinessTimeoutMs ?? this.readinessTimeoutMs, {
+                            reapOnExit: false,
+                            joinedAfter,
+                        });
+                        if (!readiness.ok)
+                            throw new Error(readiness.detail);
+                    }
+                    catch (error) {
+                        a.handle = previousHandle;
+                        a.control = previousControl;
+                        throw error;
+                    }
+                }
                 if (this.agents.get(a.name) !== a || a.terminalizing) {
                     try {
                         handle.stop({ graceful: false });
@@ -2687,7 +2818,10 @@ export class Manager {
                 replacement = undefined;
                 restart.opts = opts;
                 restart.recovering = false;
-                console.error(`! ${a.name}: recovered Pi session ${sessionId} after crash (${restart.crashes.length}/${SESSION_RESTART_LIMIT})`);
+                if (continueSession !== undefined)
+                    console.error(`! ${a.name}: recovered Pi session ${continueSession} after crash (${restart.crashes.length}/${limit})`);
+                else
+                    console.error(`! ${a.name}: restarted under the same lifecycle after crash (${restart.crashes.length}/${limit})`);
                 this.watchExit(a);
             }
             catch (error) {
@@ -2698,14 +2832,14 @@ export class Manager {
                     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
+                console.error(`! ${a.name}: ${supervised ? "supervised restart" : "Pi session recovery"} failed: ${error.message}${tail ? ` - last output: ${tail}` : ""} - retiring the managed seat`);
+                // The replacement may be alive but unable to prove readiness. 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, "pi-recovery-failed");
+                this.freeSlot(a, true, supervised ? "supervise-recovery-failed" : "pi-recovery-failed");
                 this.reapChildrenOf(this.managedPrincipal(a));
             }
             finally {
@@ -2714,13 +2848,23 @@ export class Manager {
         })();
     }
     /** 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. */
+     *  seats restart in place after readiness; a spawn carrying `supervise` restarts any connector
+     *  the same way, without classifying a session-state file. 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;
+        // A replacement is proving readiness under this row. Its own wait owns a failed
+        // relaunch; treating that exit as a seat death would free the slot mid-recovery.
+        if (a.restart?.recovering && !a.terminalizing)
+            return;
         if (a.restart?.armed && !a.terminalizing) {
+            if (a.restart.policy !== undefined) {
+                this.recoverManagedSession(a);
+                return;
+            }
             try {
                 if (this.readManagedSessionState(a).status === "running") {
                     this.recoverManagedSession(a);
@@ -2808,6 +2952,21 @@ export class Manager {
         // scalar/array (the CLI never does). Core doesn't interpret the keys; the connector validates them.
         if (args.launchOptions !== undefined && (typeof args.launchOptions !== "object" || args.launchOptions === null || Array.isArray(args.launchOptions)))
             return Promise.resolve({ ok: false, error: "launchOptions: expected a key:value mapping" });
+        let supervise;
+        if (args.supervise !== undefined) {
+            const raw = args.supervise;
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+                return Promise.resolve({ ok: false, error: "supervise: expected { restarts, windowMs }" });
+            const rec = raw;
+            const extra = Object.keys(rec).filter((k) => k !== "restarts" && k !== "windowMs");
+            if (extra.length > 0)
+                return Promise.resolve({ ok: false, error: `supervise: unknown key ${extra[0]}; it takes restarts and windowMs` });
+            if (typeof rec.restarts !== "number" || !Number.isInteger(rec.restarts) || rec.restarts < 1)
+                return Promise.resolve({ ok: false, error: "supervise.restarts: expected a positive integer" });
+            if (typeof rec.windowMs !== "number" || !Number.isInteger(rec.windowMs) || rec.windowMs < 1)
+                return Promise.resolve({ ok: false, error: "supervise.windowMs: expected a positive integer" });
+            supervise = { restarts: rec.restarts, windowMs: rec.windowMs };
+        }
         // ACL overrides arrive as string arrays or not at all — a malformed value is a bad request,
         // not something to coerce (no fallbacks).
         const strList = (v, flag) => {
@@ -2844,6 +3003,7 @@ export class Manager {
             allowSubscribe,
             allowPublish,
             shareTools: args.shareTools !== undefined ? String(args.shareTools) : undefined,
+            ...(supervise !== undefined ? { supervise } : {}),
         }, caller, hooks);
     }
     /** Resolve a connector by agent type. Library composition (installedExtensions off) → a registry
@@ -3165,6 +3325,16 @@ export class Manager {
         // reject-before-side-effects window as the harness preflight above; buildLaunch stays the backstop.
         if (opts.resume && !connector.supportsResume)
             return { ok: false, error: `${agent} connector does not support resuming an existing session (resume)` };
+        // A restart policy this host cannot honour is refused at accept, never accepted and ignored.
+        // External runtimes (tmux/cmux/orca/herdr) attach to a process they do not own and stream no
+        // exit, so a name cannot be respawned in place. User-mode seats have no static slot that
+        // keeps the incarnation owned across a process death, so the same refusal applies there.
+        if (opts.supervise !== undefined) {
+            if (this.runtime.kind !== "pty")
+                return { ok: false, error: `supervise is a restart policy this host cannot enforce: runtime "${this.runtime.kind}" cannot respawn a name in place` };
+            if (this.userMode)
+                return { ok: false, error: "supervise is a restart policy this host cannot enforce: a user-mode seat has no static slot to keep the incarnation owned across a process death" };
+        }
         // Resolve the launch profile: IDENTITY (free-form `name:`) + role + read/post ACL + capabilities
         // + model/variant. Either from a fully-resolved manifest launch object (`opts.resolved`, whose `config`
         // is a materialized transient persona — the file is NOT the access authority), or from the
@@ -3577,8 +3747,17 @@ export class Manager {
                         ? Object.keys(opts.launchOptions).sort()
                         : undefined,
                 },
-                ...(connector.supportsSessionContinuation
-                    ? { restart: { opts: launchOpts, sessionStatePath: spec.sessionStatePath, crashes: [], recovering: false, armed: false } }
+                ...(connector.supportsSessionContinuation || opts.supervise !== undefined
+                    ? {
+                        restart: {
+                            opts: launchOpts,
+                            sessionStatePath: spec.sessionStatePath,
+                            crashes: [],
+                            recovering: false,
+                            armed: false,
+                            ...(opts.supervise !== undefined ? { policy: opts.supervise } : {}),
+                        },
+                    }
                     : {}),
             };
             // Unit B: the DURABLE slot takes the `active` phase before the in-memory row takes the
@@ -3621,16 +3800,21 @@ export class Manager {
                 return { ok: false, error: readiness.detail };
             }
             if (managed.restart) {
-                try {
-                    await this.armSessionRecovery(managed);
-                    managed.launch.sessionId = this.readManagedSession(managed);
+                if (connector.supportsSessionContinuation) {
+                    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, "session-bind-failed");
+                        await hooks?.onOutcome?.({ kind: "failed", data: { error: detail } });
+                        return { ok: false, error: detail };
+                    }
                 }
-                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, "session-bind-failed");
-                    await hooks?.onOutcome?.({ kind: "failed", data: { error: detail } });
-                    return { ok: false, error: detail };
+                else {
+                    managed.restart.armed = true;
                 }
             }
             this.watchExit(managed);
@@ -4184,7 +4368,7 @@ export class Manager {
      *  `"presence"` event is only a wake; the roster is re-read as the source of truth (subscribe-then-check
      *  catches a join/exit that landed before we subscribed). Runtimes that stream no exit signal (external surfaces,
      *  whose `attach()` throws) race presence-vs-backstop only — better than the old "assume up". */
-    async awaitReadiness(a, readinessTimeoutMs) {
+    async awaitReadiness(a, readinessTimeoutMs, opts = {}) {
         let session;
         try {
             session = a.handle.attach();
@@ -4206,16 +4390,25 @@ export class Manager {
         // 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);
+        // A supervised restart keeps the same principal+uid, so a SIGKILL'd child's still-live
+        // presence row would otherwise satisfy this equality. `joinedAfter` is one millisecond
+        // past that row's last heartbeat: only a later heartbeat counts as THIS replacement joining.
+        const joined = () => this.ep.getRoster().some((p) => p.card.id === wanted
+            && p.status !== "offline"
+            && p.lifecycleUid === a.lifecycleUid
+            && (opts.joinedAfter === undefined || p.ts >= opts.joinedAfter));
         return await new Promise((resolve) => {
             let done = false;
             let timer;
             let unsubExit = () => { };
+            let joinedPoll;
             const finish = (r) => {
                 if (done)
                     return;
                 done = true;
                 clearTimeout(timer);
+                if (joinedPoll !== undefined)
+                    clearInterval(joinedPoll);
                 this.ep.off("presence", onPresence);
                 unsubExit();
                 resolve(r);
@@ -4224,6 +4417,11 @@ export class Manager {
                 if (joined())
                     finish({ ok: true });
             };
+            if (opts.joinedAfter !== undefined) {
+                // Heartbeats bump roster.ts without emitting "presence" (same status/uid/activity).
+                // A supervised restart needs that bump, so poll joined() rather than waiting on the event.
+                joinedPoll = setInterval(onPresence, 50);
+            }
             // Process exit → failed. Clear the backstop FIRST (synchronously) so it can't resolve UNCERTAIN while
             // the backlog reads async — the process is known dead, that's a failure, not an unknown. Reap through
             // onAgentExit so a child the launcher spawned in the window is reaped too.
@@ -4255,8 +4453,14 @@ export class Manager {
                 // └──────────────────────────────────────────────────────────────────────────────────────┘
                 const deliberate = a.terminalizing === true;
                 void (async () => {
-                    const tail = this.tail(await s.backlog());
-                    this.onAgentExit(a);
+                    // waitForExit may close the attach stream before this snapshot
+                    let tail = "";
+                    try {
+                        tail = this.tail(await s.backlog());
+                    }
+                    catch { }
+                    if (opts.reapOnExit !== false)
+                        this.onAgentExit(a);
                     // A DELIBERATE STOP IS NOT A LAUNCH FAILURE. The despawn path owns this goal's terminal
                     // and commits `cancel`; reporting `failed` here races it and, when it wins, tells the
                     // caller the agent died on launch when in fact an operator cancelled it. The process
@@ -4379,7 +4583,7 @@ export class Manager {
         const creds = await mintCreds(this.auth, identity, "lifecycle-executor", {
             lifecycleExecutor: { owner: pin.owner, actor: pin.actor, lifecycleUid: pin.lifecycleUid, alias: pin.alias },
         });
-        const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
+        const nc = await this.dial({ ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
         try {
             const kvm = new Kvm(nc);
             const recordsKv = await kvm.open(recordsBucket(this.space));
@@ -4404,7 +4608,7 @@ export class Manager {
             : undefined);
         if (!creds)
             throw new Error("withEndpointServeExecutor: no scoped executor authority (an open mesh must use the bare path)");
-        const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
+        const nc = await this.dial({ ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
         try {
             const kvm = new Kvm(nc);
             return await fn({ recordsKv: await kvm.open(recordsBucket(this.space)), authKv: await kvm.open(epAuthBucket(this.space)), nc });
@@ -4420,7 +4624,7 @@ export class Manager {
     async withOpenServeConnection(fn) {
         if (this.auth)
             throw new Error("withOpenServeConnection: an auth mesh must use the scoped endpoint-serve executor");
-        const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, maxReconnectAttempts: 0 });
+        const nc = await this.dial({ maxReconnectAttempts: 0 });
         try {
             const kvm = new Kvm(nc);
             // An open mesh may be a RAW broker (no `cotal up` provisioning ran), and `Kvm.open` binds
@@ -4439,6 +4643,7 @@ export class Manager {
         return {
             instanceId: this.managerInstanceId,
             runtime: this.runtime.kind,
+            custody: process.platform === "linux" && this.runtime.kind === "pty" ? "custodied" : "legacy",
             agentCount: this.agents.size,
             uptimeMs: Date.now() - this.startedAtMs,
             connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),
@@ -4519,8 +4724,7 @@ export class Manager {
                 creds: remote.serveCreds,
             };
             const enc = new TextEncoder();
-            const nc = await connect({
-                servers: this.servers ?? DEFAULT_SERVER,
+            const nc = await this.dial({
                 authenticator: (nonce) => credsAuthenticator(enc.encode(state.creds))(nonce),
                 inboxPrefix: `_INBOX_${state.identity.id}`,
                 maxReconnectAttempts: -1,
@@ -4553,7 +4757,7 @@ export class Manager {
         {
             // Open mesh: the bare connection holds the rights (there is no credential system to mint from).
             const provCreds = auth ? await mintCreds(auth, newIdentity(), "provisioner") : undefined;
-            const provNc = await connect({ servers: this.servers ?? DEFAULT_SERVER, ...standaloneConnectOpts({ creds: provCreds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
+            const provNc = await this.dial({ ...standaloneConnectOpts({ creds: provCreds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
             try {
                 // P2 item 2: the manager now WRITES goal facts (EPF) + progress events (EPE), so the §13.12
                 // endpoint streams must exist. Nothing provisioned them before spawn-as-action (no endpoint
@@ -4698,8 +4902,7 @@ export class Manager {
         // registered surface for its whole incarnation.
         const state = { handle: undefined, nc: undefined, identity: serveIdentity, grant, creds };
         const enc = new TextEncoder();
-        const nc = await connect({
-            servers: this.servers ?? DEFAULT_SERVER,
+        const nc = await this.dial({
             // Open mesh: a bare serve connection (no credential exists; the broker enforces nothing).
             ...(creds !== undefined ? { authenticator: (nonce) => credsAuthenticator(enc.encode(state.creds))(nonce) } : {}),
             inboxPrefix: `_INBOX_${serveIdentity.id}`,
@@ -4794,8 +4997,7 @@ export class Manager {
         // The mutable holder captured by the authenticator (mirrors the serve connection): a half-TTL
         // renewal updates `gw.creds` and the next (re)connect presents the refreshed credential.
         const gw = { nc: undefined, ctx: undefined, creds: (this.auth || this.remoteAuthority) ? this.goalWriterCreds : undefined, identity };
-        const nc = await connect({
-            servers: this.servers ?? DEFAULT_SERVER,
+        const nc = await this.dial({
             ...((this.auth || this.remoteAuthority) ? { authenticator: (nonce) => credsAuthenticator(enc.encode(gw.creds))(nonce) } : {}),
             inboxPrefix: `_INBOX_${identity.id}`,
             maxReconnectAttempts: -1,
@@ -4900,8 +5102,7 @@ export class Manager {
         // The mutable holder captured by the authenticator (mirrors the goal-writer): a half-TTL renewal
         // updates `sw.creds` and the next (re)connect presents the refreshed credential.
         const sw = { nc: undefined, creds: (this.auth || this.remoteAuthority) ? this.sessionLedgerCreds : undefined };
-        const nc = await connect({
-            servers: this.servers ?? DEFAULT_SERVER,
+        const nc = await this.dial({
             ...((this.auth || this.remoteAuthority) ? { authenticator: (nonce) => credsAuthenticator(enc.encode(sw.creds))(nonce) } : {}),
             inboxPrefix: `_INBOX_${identity.id}`,
             maxReconnectAttempts: -1,
@@ -5072,7 +5273,7 @@ export class Manager {
                 // FAIL LOUD: there is deliberately no shared connection to fall back to. Serving a session
                 // without its own credential is exactly the standing-writer shape this design removes.
                 const opts = (this.auth || this.remoteAuthority) ? standaloneConnectOpts({ creds: cred.creds, /* not yet wired to a recorded transport */ tls: false }) : {};
-                return connect({ servers: this.servers ?? DEFAULT_SERVER, ...opts, maxReconnectAttempts: -1 });
+                return this.dial({ ...opts, maxReconnectAttempts: -1 });
             },
             revoke: async (credentialId) => {
                 if (!this.auth && !this.remoteAuthority)
@@ -5127,8 +5328,8 @@ export class Manager {
         try {
             let entries = [];
             const nc = this.auth
-                ? await connect({ servers: this.servers ?? DEFAULT_SERVER, ...standaloneConnectOpts({ creds: await mintCreds(this.auth, newIdentity(), "provisioner"), /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 })
-                : await connect({ servers: this.servers ?? DEFAULT_SERVER, maxReconnectAttempts: 0 });
+                ? await this.dial({ ...standaloneConnectOpts({ creds: await mintCreds(this.auth, newIdentity(), "provisioner"), /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 })
+                : await this.dial({ maxReconnectAttempts: 0 });
             try {
                 const kvm = new Kvm(nc);
                 await ensureAuthorityStores(await jetstreamManager(nc), kvm, this.space);
@@ -6090,7 +6291,7 @@ export class Manager {
             return;
         const identity = newIdentity();
         const creds = await mintCreds(this.auth, identity, "provisioner");
-        const nc = await connect({ servers: this.servers ?? DEFAULT_SERVER, ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
+        const nc = await this.dial({ ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 });
         const slotRows = [];
         try {
             const jsm = await jetstreamManager(nc);