@cotal-ai/manager 0.44.0 → 0.46.0

package/dist/manager.js

@@ -6,7 +6,7 @@ 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 { 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
@@ -495,6 +502,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 +710,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 +865,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 {
@@ -1336,6 +1369,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 +1796,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 +1860,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 +1965,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 +2200,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.
@@ -2635,9 +2734,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 +2746,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 +2763,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 +2809,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 +2823,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 +2839,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 +2943,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 +2994,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 +3316,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 +3738,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 +3791,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 +4359,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 +4381,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 +4408,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.
@@ -4256,7 +4445,8 @@ export class Manager {
                 const deliberate = a.terminalizing === true;
                 void (async () => {
                     const tail = this.tail(await s.backlog());
-                    this.onAgentExit(a);
+                    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
@@ -4439,6 +4629,7 @@ export class Manager {
         return {
             instanceId: this.managerInstanceId,
             runtime: this.runtime.kind,
+            custody: "legacy",
             agentCount: this.agents.size,
             uptimeMs: Date.now() - this.startedAtMs,
             connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),