@cotal-ai/manager 0.50.1 → 0.52.0

package/dist/manager.js

@@ -2,8 +2,8 @@ import { execFile } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { credsAuthenticator } from "@nats-io/transport-node";
-import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { isAbsolute, join, dirname, resolve } from "node:path";
 import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, divergentSecretStoreNotice, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, 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, createManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, isCustodialRuntime, requireRuntimeAdopt, requireRuntimeReap, RuntimeReapUnproven, } from "./runtime/index.js";
@@ -147,9 +147,10 @@ function sameStrings(a, b) {
     return JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());
 }
 /** Operator-facing phrasing per cause. Kept beside the union so adding a member without a sentence
- *  is a type error rather than a blank in the log. */
+ *  is a type error rather than a blank in the log. The stop family's sentences carry the principal
+ *  from the cause, so they render through {@link STOP_CAUSE_TEXT} under the same exhaustive-Record
+ *  discipline: a new stop kind without a renderer is a type error too. */
 const FREE_SLOT_CAUSE_TEXT = {
-    "stopped": "this manager stopped it (despawn or shutdown)",
     "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",
@@ -158,6 +159,21 @@ const FREE_SLOT_CAUSE_TEXT = {
     "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",
 };
+/** The stop family's sentences — the same job {@link FREE_SLOT_CAUSE_TEXT} does for the string
+ *  causes, beside it so both stay the single place a cause becomes a sentence. A requested stop's
+ *  sentence embeds the authenticated principal and a recursive reap's embeds the parent that
+ *  left, so they cannot sit in a static Record keyed by kind; this exhaustive switch is their
+ *  single home, and the `satisfies never` default keeps the discipline: a new stop kind without a
+ *  sentence is a type error rather than a blank in the log. */
+function stopCauseText(cause) {
+    switch (cause.kind) {
+        case "stopped-requested": return `this manager stopped it at ${cause.requester}'s request`;
+        case "stopped-self": return "it stopped itself (self-stop)";
+        case "stopped-reap": return `this manager stopped it because its parent ${cause.parent} left (recursive reap)`;
+        case "stopped-shutdown": return "this manager stopped it on manager shutdown";
+        default: return cause;
+    }
+}
 function parseTurnNote(raw) {
     let o;
     try {
@@ -284,6 +300,7 @@ export class Manager {
     wsPort;
     name;
     workspaceRoot;
+    eventsRequired;
     /** P2 item 6: the operator-set global live-session ceiling (see {@link ManagerOptions.maxSessions}). */
     maxSessions;
     /** The ONE secret store for every kind this manager touches (daemon-cred remint + agent kinds).
@@ -535,6 +552,7 @@ export class Manager {
         this.servers = opts.servers;
         this.name = opts.name ?? "manager";
         this.workspaceRoot = opts.workspaceRoot ?? findCotalRoot();
+        this.eventsRequired = opts.eventsRequired === true;
         this.maxSessions = opts.maxSessions;
         this.remoteAuthority = opts.remoteAuthority;
         if (opts.remoteAuthority)
@@ -927,7 +945,7 @@ export class Manager {
     }
     /** One class-2 renewal pass (D5 slice 5): re-sign `.cotal/delivery.creds` + `.cotal/membership-rw.creds`
      *  for their existing nkeys, then request the delivery daemon's EXPLICIT `reloadCreds` adoption on the
-     *  delivery-admin rail and persist the audit record (`.cotal/renewal.json`) that `cotal doctor auth`
+     *  delivery-admin rail and persist the audit record (`.cotal/renewal.<spaceKey>.json`) that `cotal doctor auth`
      *  renders — so "file re-signed" and "daemon adopted" are distinguishable states. A missing daemon
      *  (no responder) is recorded honestly: each daemon's own 75% renewal timer remains the adoption backstop.
      *  Never throws — renewal failure must be LOUD (log + record), not fatal to the supervisor. */
@@ -985,7 +1003,7 @@ export class Manager {
             // A non-owner (#1634) re-signed nothing, so it writes no record: an empty one renders in
             // `doctor auth` as a pass that never ran.
             if (this.daemonRenewalOwner)
-                writeRenewalRecord(this.workspaceRoot, { ts: new Date().toISOString(), owner: "manager", results, adoption });
+                writeRenewalRecord(this.workspaceRoot, this.space, { ts: new Date().toISOString(), owner: "manager", results, adoption });
             this.warnOnSystemCredExpiry();
             // F5(b) (Unit B): the MANAGER is the renewal owner for its managed-static agent creds —
             // supervisor-side PUSH remint for recorded LIVE slots (the child JWT is never proof of
@@ -1480,6 +1498,9 @@ export class Manager {
                 shareTools: a.launch.shareTools,
                 forkSource: a.launch.forkSource,
                 sessionId: a.restart?.armed ? this.readManagedSession(a) : a.launch.sessionId,
+                // Additive and only when the connector supplied one. A seat with no pointer records no
+                // field, which is what keeps an older inventory and a fresh one the same document shape.
+                ...(a.restart?.sessionStatePath ? { sessionStatePath: a.restart.sessionStatePath } : {}),
                 unresolvedLaunchOptionKeys: a.launch.unresolvedLaunchOptionKeys,
             },
             dependencies,
@@ -1504,6 +1525,11 @@ export class Manager {
             this.agents.delete(a.name);
             this.stopHandle(a, false);
         }
+        // The slot delete above bypasses freeSlot, which is where the reap line lives — so say it here,
+        // once per seat, with the one stop cause that names this path: the shutdown itself. Without
+        // this a `--with-agents` stop left every seat unaccounted for in the log (see #1423).
+        for (const a of managed)
+            this.logSeatReaped(a, { kind: "stopped-shutdown" });
         // A runtime stop request is not exit proof. Do not release the manager lease or registration
         // while any seat may still hold this instance's broker rails: that creates the exact orphan
         // window where a successor sees a dead manager but live predecessor authority. Every shipped
@@ -2070,6 +2096,34 @@ export class Manager {
                 return a.name;
         return caller;
     }
+    /** A baseline seat may answer only the pause whose relay is pending on that exact incarnation.
+     *  Explicit `run` holders and unmanaged operator instruments keep the run capability's existing
+     *  answer reach. The relay payload is manager-held state written by the runtime, never request
+     *  input, and its token is checked against the open checkpoint before any answer is filed. */
+    authorizeRunAnswer(ctx, args, open) {
+        const caller = principalKey(ctx.subject.caller.owner, ctx.subject.caller.actor).key;
+        const agent = [...this.agents.values()].find((a) => this.managedPrincipal(a) === caller && a.lifecycleUid === ctx.subject.caller.uid);
+        if (agent === undefined || agent.launch.capabilities?.includes("run"))
+            return;
+        const pending = [...this.pendingTurns.values()].find((p) => p.seat.owner === ctx.subject.caller.owner
+            && p.seat.actor === ctx.subject.caller.actor
+            && p.seat.uid === ctx.subject.caller.uid);
+        if (pending === undefined)
+            throw new EpEnvelopeError("permission-denied", `run-answer is allowed to this baseline seat only for a pending ask or escalation addressed to its own incarnation; none is pending for ${agent.name}`);
+        let payload;
+        try {
+            payload = JSON.parse(pending.payload);
+        }
+        catch {
+            throw new EpEnvelopeError("permission-denied", `turn "${pending.goalId}" carries no readable ask or escalation authorization; run-answer is refused`);
+        }
+        const p = payload;
+        const addressedToken = typeof p.ask?.token === "string" ? p.ask.token
+            : p.checkpoint?.escalatedTo === agent.name && typeof p.checkpoint?.token === "string" ? p.checkpoint.token
+                : undefined;
+        if (p.run !== args.runId || p.step !== args.stepKey || addressedToken !== open.token)
+            throw new EpEnvelopeError("permission-denied", `run-answer is allowed to ${agent.name} only for the open pause named by its pending ask or escalation relay; ${args.runId} ${args.stepKey} is not that pause`);
+    }
     managerServiceDefs() {
         const args = (ctx) => (ctx.request.args ?? {});
         const callerOf = (ctx) => principalKey(ctx.subject.caller.owner, ctx.subject.caller.actor).key;
@@ -2139,15 +2193,16 @@ export class Manager {
                 const data = unwrap(await this.opModels(args(ctx)));
                 return { catalogs: Array.isArray(data) ? data : [data] };
             }),
+            resolveCwd: (ctx) => this.serveGated(ctx, () => this.resolveSpawnCwd(args(ctx).cwd)),
             // P2 item 2: `spawn` is an ACTION - accept a goal + reply the acceptance floor payload, drive
             // progress + terminal off-handler (no ~30s block). The blocking reply path is gone (pin 8).
-            spawn: (ctx) => this.serveGated(ctx, () => this.serveSpawnGoal(ctx, (h) => this.opStart(args(ctx), callerOf(ctx), h))),
+            spawn: (ctx) => this.serveGated(ctx, () => this.serveSpawnGoal(ctx, (h) => this.opStart(args(ctx), callerOf(ctx), h, ctx.subject.route))),
             despawn: (ctx) => this.serveGated(ctx, async () => {
                 const a = targetAgent(ctx);
                 const denied = await this.authorizeNamed(a, callerOf(ctx), await this.epAnyModeAdmin(ctx), ctx.subject.caller);
                 if (denied)
                     throw new EpEnvelopeError("permission-denied", denied);
-                return unwrap(this.despawnAuthorized(a, args(ctx).graceful !== false, true));
+                return unwrap(this.despawnAuthorized(a, args(ctx).graceful !== false, true, callerOf(ctx)));
             }),
             attach: (ctx) => this.serveGated(ctx, async () => {
                 const a = targetAgent(ctx);
@@ -2206,7 +2261,7 @@ export class Manager {
             // P2 item 2 (ruling 3): manifest `launch` is an ACTION through the SAME chokepoint as spawn -
             // the manifest resolve + owner-equality authz run in opLaunch's accept path, then the goal
             // drives progress + terminal. The acceptance floor is the allocated identity + goal coords.
-            launch: (ctx) => this.serveGated(ctx, () => this.serveSpawnGoal(ctx, (h) => this.opLaunch(args(ctx), callerOf(ctx), false, h))),
+            launch: (ctx) => this.serveGated(ctx, () => this.serveSpawnGoal(ctx, (h) => this.opLaunch(args(ctx), callerOf(ctx), false, h, ctx.subject.route))),
             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)))),
@@ -2214,7 +2269,10 @@ export class Manager {
             // (`run` capability / privileged instrument rows); the serve gate is the maintenance fence.
             runStart: (ctx) => this.serveGated(ctx, () => this.runHost().start(ctx, 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))),
+            runAnswer: (ctx) => this.serveGated(ctx, () => {
+                const input = args(ctx);
+                return this.runHost().answer(input, this.runAnswerer(ctx), (open) => this.authorizeRunAnswer(ctx, input, open));
+            }),
             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)))),
@@ -2358,7 +2416,7 @@ export class Manager {
             return { ok: false, error: `self-stop: caller ${callerId} is not a managed agent` };
         const graceful = args.graceful !== false;
         this.stopHandle(target, graceful);
-        this.trackStoppedHandle(target, true);
+        this.trackStoppedHandle(target, true, { kind: "stopped-self" });
         return { ok: true, data: { name: target.name, stopped: true, graceful } };
     }
     // Plane-3 durable join/leave/list ops moved OFF the manager onto the server-side delivery daemon's
@@ -2392,7 +2450,9 @@ export class Manager {
         }
     }
     /** Keep an accepted stop inside the lifecycle drain until the runtime proves the child is gone,
-     * so a maintenance prepare can never fence ahead of a child that is still dying.
+     * so a maintenance prepare can never fence ahead of a child that is still dying. The `cause` is
+     * the stop-family cause the door already knows (which door, and who asked); it rides every
+     * freeSlot below so the reap line can say it.
      *
      * An operator-accepted stop frees its slot at once: `stop` replying ✓ means `ps` no longer lists
      * the agent. That cannot omit a still-live child from a cut, because runPreparation drains the
@@ -2400,7 +2460,7 @@ export class Manager {
      * slot lingering. A recursive reap (`requireAuthoritativeExit`) instead keeps the slot until the
      * wait proves exit: nobody asked for those children to be gone, so they stay managed until the
      * runtime says otherwise, and a runtime that cannot prove exit records an unverified stop. */
-    trackStoppedHandle(a, floor, requireAuthoritativeExit = false) {
+    trackStoppedHandle(a, floor, cause, requireAuthoritativeExit = false) {
         if (!a.handle.waitForExit) {
             // Preserve ordinary external-runtime stop behavior, but retain enough evidence for a later
             // maintenance prepare to fail if that runtime still cannot prove the surface disappeared.
@@ -2415,14 +2475,14 @@ export class Manager {
             });
             if (requireAuthoritativeExit)
                 return;
-            this.freeSlot(a, floor, "stopped", true);
+            this.freeSlot(a, floor, cause, true);
             return;
         }
         if (!requireAuthoritativeExit)
-            this.freeSlot(a, floor, "stopped", true);
+            this.freeSlot(a, floor, cause, true);
         this.lifecycleInFlight++;
         void this.awaitHandleExit(a.handle)
-            .then(() => this.freeSlot(a, floor, "stopped", true)) // no-op once an accepted stop already freed it
+            .then(() => this.freeSlot(a, floor, cause, true)) // no-op once an accepted stop already freed it
             .catch((e) => {
             this.unverifiedStops.push({
                 name: a.name,
@@ -2559,6 +2619,7 @@ export class Manager {
      * that could not provide it.
      */
     logSeatReaped(a, cause) {
+        const causeText = typeof cause === "string" ? FREE_SLOT_CAUSE_TEXT[cause] : stopCauseText(cause);
         let detail;
         try {
             const info = a.handle.exitInfo?.();
@@ -2571,7 +2632,7 @@ export class Manager {
             // log line (or the free path it sits on) down with it.
             detail = `exit detail unreadable from runtime "${a.handle.kind}": ${e.message}`;
         }
-        console.error(`seat reaped: ${a.name} (${a.id}, uid ${a.lifecycleUid}${a.handle.pid !== undefined ? `, pid ${a.handle.pid}` : ""}) - ${FREE_SLOT_CAUSE_TEXT[cause]}; ${detail}`);
+        console.error(`seat reaped: ${a.name} (${a.id}, uid ${a.lifecycleUid}${a.handle.pid !== undefined ? `, pid ${a.handle.pid}` : ""}) - ${causeText}; ${detail}`);
     }
     freeSlot(a, floor, cause, acceptedBeforeFence = false) {
         if (this.agents.get(a.name) !== a)
@@ -2934,7 +2995,7 @@ export class Manager {
                 continue;
             this.reapChildrenOf(this.managedPrincipal(child));
             this.stopHandle(child, false);
-            this.trackStoppedHandle(child, true, true);
+            this.trackStoppedHandle(child, true, { kind: "stopped-reap", parent: parentId }, true);
         }
     }
     readSessionStatePath(path) {
@@ -3227,7 +3288,7 @@ export class Manager {
         return false;
     }
     /** Parse an untyped control-plane `start` request into {@link StartAgentOpts}. */
-    opStart(args, caller, hooks) {
+    opStart(args, caller, hooks, route = "inst") {
         // `resume`, when present, must be a non-empty session id. An empty/whitespace value is a
         // malformed request, not an implicit "spawn fresh" (no fallbacks). The CLI surfaces reject it,
         // but a raw control message could otherwise slip an empty value through and silently start fresh.
@@ -3293,8 +3354,36 @@ export class Manager {
             allowPublish,
             shareTools: args.shareTools !== undefined ? String(args.shareTools) : undefined,
             ...(supervise !== undefined ? { supervise } : {}),
+            route,
         }, caller, hooks);
     }
+    /** Resolve a placed spawn directory on this manager's host. The manager serves any existing
+     * absolute directory it can resolve. It creates nothing and never substitutes the workspace root. */
+    resolveSpawnCwd(value) {
+        const asked = typeof value === "string" ? value : String(value ?? "");
+        const refuse = (reason) => {
+            throw new EpEnvelopeError("failed-precondition", `cwd does not resolve on this host: ${JSON.stringify(asked)} (${reason})`);
+        };
+        if (!isAbsolute(asked))
+            refuse("expected an absolute path");
+        let cwd = asked;
+        try {
+            cwd = realpathSync(asked);
+        }
+        catch (error) {
+            refuse(`path cannot be resolved: ${error.message}`);
+        }
+        try {
+            if (!statSync(cwd).isDirectory())
+                refuse("path is not a directory");
+        }
+        catch (error) {
+            if (error instanceof EpEnvelopeError)
+                throw error;
+            refuse(error.message);
+        }
+        return { cwd, host: hostname() };
+    }
     /** Resolve a connector by agent type. Library composition (installedExtensions off) → a registry
      *  hit, exactly as before (the composition root imported what it wants). The published binary gates
      *  on MANIFEST membership FIRST — so a live `cotal ext remove` is honored even though the registry
@@ -3328,6 +3417,7 @@ export class Manager {
                 const reason = error.message;
                 console.error(`! manager boot: connector inventory unavailable - ${reason}`);
                 this.connectorStatuses = [{ agent: "(inventory)", state: "unavailable", binaries: {}, reason }];
+                console.error("! manager boot: no connector available - spawn and launch stay on this instance rail only so a sibling that can launch them can take the class queue");
                 return;
             }
         }
@@ -3355,6 +3445,27 @@ export class Manager {
             }
         }
         this.connectorStatuses = rows.sort((a, b) => a.agent.localeCompare(b.agent));
+        if (!this.classSpawnEnabled())
+            console.error("! manager boot: no connector available - spawn and launch stay on this instance rail only so a sibling that can launch them can take the class queue");
+    }
+    /** True when at least one declared connector is available. Empty inventory (or a failed
+     *  inventory load) skips the class `one` subscribe for spawn/launch so this member cannot
+     *  consume an unpinned request a sibling could serve. */
+    classSpawnEnabled() {
+        return this.connectorStatuses.some((row) => row.state === "available");
+    }
+    omitClassCommands() {
+        return this.classSpawnEnabled() ? undefined : ["spawn", "launch"];
+    }
+    /** Named harness-unavailable refusal. On the class rail a partial inventory must not look
+     *  like the space cannot launch: name `--on` so the caller can pin a sibling. The standing
+     *  serve credential cannot enumerate sibling `svc.*.status` inventories, so the residual
+     *  is the flag, not a list of capable instance ids. Instance-pinned calls keep the local
+     *  reason only. */
+    harnessUnavailableError(reason, route) {
+        if (route !== "one")
+            return reason;
+        return `${reason}. This manager cannot launch that harness. The space may have other managers; pin one with --on <instance> (the whole id, as ps prints it)`;
     }
     /** Return connector-provided model catalogs for selector UIs. Optional by connector: a host with no
      *  local model-list API reports `supported:false` rather than blocking the manager. A connector that
@@ -3444,7 +3555,7 @@ export class Manager {
      *  (collision-numbered) name + nkey id creds are filed under, plus the manifest `requested` name,
      *  `runId`, and resolved `hash`. USER mesh: a privileged-tier launch is owner-equality-authorized
      *  (spec owner === caller owner) before any side effect; the admin tier keeps operator behavior. */
-    async opLaunch(args, caller, admin, hooks) {
+    async opLaunch(args, caller, admin, hooks, route = "inst") {
         const runId = String(args.runId ?? "").trim();
         const name = String(args.name ?? "").trim();
         if (!runId || !name)
@@ -3496,7 +3607,7 @@ export class Manager {
         catch (e) {
             return { ok: false, error: e.message };
         }
-        const reply = await this.startAgent(launchAgentToStartOpts(la, configPath, spec.owner, runId), caller, hooks);
+        const reply = await this.startAgent({ ...launchAgentToStartOpts(la, configPath, spec.owner, runId), route }, caller, hooks);
         if (reply.ok)
             // `data.name` stays the spawned (numbered) identity — what creds are filed under and the ledger
             // keys on; `requested`/`runId`/`hash` give the CLI the manifest name + drift hash for the ledger.
@@ -3599,14 +3710,15 @@ export class Manager {
         // fails here with a clear name, not obscurely at process spawn. No fallback. All synchronous, so
         // the reserve gate stays atomic. (The connector itself was resolved up top, before the capacity gate.)
         const bootStatus = this.connectorStatuses.find((row) => row.agent === agent);
+        const route = opts.route ?? "inst";
         if (bootStatus?.state === "unavailable")
-            return { ok: false, error: bootStatus.reason };
+            return { ok: false, error: this.harnessUnavailableError(bootStatus.reason ?? `${agent} harness is unavailable`, route) };
         // A connector registered after boot has no inventory row. Keep the existing pre-mint backstop
         // for that dynamic library-composition case; ordinary installed connectors were checked at boot.
         if (!bootStatus) {
             const missing = (connector.requires ?? []).filter((bin) => !resolveOnPath(bin));
             if (missing.length)
-                return { ok: false, error: `${agent} harness needs ${missing.join(", ")} on PATH - not found` };
+                return { ok: false, error: this.harnessUnavailableError(`${agent} harness needs ${missing.join(", ")} on PATH - not found`, route) };
         }
         // Resume is a connector capability: reject an unsupported resume HERE, before the reserve/mint, so
         // it can never provision creds + durables and then throw at buildLaunch (mint-then-orphan). Same
@@ -3759,19 +3871,25 @@ export class Manager {
             name = this.uniqueName(identityName);
         }
         this.reserved.add(name);
-        // The AG-UI event plane (opt-in: `--events` / COTAL_EVENTS_DEFAULT=1). Refused HERE, before
+        // The AG-UI event plane is on unless the launch explicitly opted out. Refused HERE, before
         // anything is minted: a connector that cannot
         // emit must fail before provisioning rather than after, exactly as an unsupported `resume` does.
         // The GRANT itself cannot be derived yet. It is keyed on the agent's PRINCIPAL, and in user mode
         // the principal's owner is resolved further down, so deriving it from anything in scope here
         // would mean guessing at the identity the child will actually connect as. It is added at the
         // accept seam below, where the allocated triple exists.
-        const events = opts.events ?? process.env.COTAL_EVENTS_DEFAULT === "1";
+        if (this.eventsRequired && opts.events === false) {
+            this.reserved.delete(name);
+            return { ok: false, error: `space "${this.space}" requires the event plane by registration policy; --no-events (events: false on the start op) is not allowed` };
+        }
+        const events = this.eventsRequired || opts.events !== false;
         if (events && !connector.eventChannel) {
             // Release the just-reserved name on this fail-fast path. A leaked reserve is silent: it costs
             // the next spawn of this persona its un-suffixed name and nothing reports why.
             this.reserved.delete(name);
-            return { ok: false, error: `connector "${connector.name}" does not publish an AG-UI event plane, but events was requested` };
+            return { ok: false, error: this.eventsRequired
+                    ? `space "${this.space}" requires the event plane by registration policy, but connector "${connector.name}" does not publish one`
+                    : `connector "${connector.name}" does not publish an AG-UI event plane; pass --no-events (events: false on the start op) to launch it without one` };
         }
         // F2 (Unit B): a STATIC managed spawn REFUSES endpoint capabilities, fail-closed IN CODE (not
         // a doc note): the static terminal has no obligation-drain/frontier steps yet, so an accepted-
@@ -3995,6 +4113,7 @@ export class Manager {
                 allowPublish,
                 capabilities,
                 events,
+                eventsRequired: this.eventsRequired,
                 mcpServers,
                 envAllow,
                 resolvedBinaries: bootStatus?.binaries,
@@ -4899,13 +5018,15 @@ export class Manager {
         const denied = await this.authorizeNamed(a, caller, admin);
         if (denied)
             return { ok: false, error: denied };
-        return this.despawnAuthorized(a, graceful, !admin);
+        return this.despawnAuthorized(a, graceful, !admin, caller);
     }
     /** The post-authorization terminal effect (both doors). `trackNonAdmin` mirrors the ctl door's
-     *  `trackStoppedHandle(a, !admin)` disposition. */
-    despawnAuthorized(a, graceful, trackNonAdmin) {
+     *  `trackStoppedHandle(a, !admin)` disposition. The reap line names `caller` — the AUTHENTICATED
+     *  wire principal the door already resolved — so an operator reading the log can tell one peer's
+     * despawn from another's. */
+    despawnAuthorized(a, graceful, trackNonAdmin, caller) {
         this.stopHandle(a, graceful);
-        this.trackStoppedHandle(a, trackNonAdmin);
+        this.trackStoppedHandle(a, trackNonAdmin, { kind: "stopped-requested", requester: caller });
         void this.cancelAgentGoal(a.name, graceful ? "graceful" : "terminate"); // M4: cancel a live spawn goal
         return { ok: true, data: { name: a.name, stopped: true, graceful } };
     }
@@ -5036,6 +5157,7 @@ export class Manager {
             agentCount: this.agents.size,
             uptimeMs: Date.now() - this.startedAtMs,
             connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),
+            classSpawn: this.classSpawnEnabled(),
             staticReconciliation: this.staticReconciliationStatus(),
         };
     }
@@ -5145,6 +5267,7 @@ export class Manager {
                                 return { lifecycleUid: a.lifecycleUid, mappingRevision: 0 };
                         return undefined;
                     },
+                    ...(this.omitClassCommands() ? { omitClassCommands: this.omitClassCommands() } : {}),
                 });
             }
             catch (e) {
@@ -5384,6 +5507,7 @@ export class Manager {
                             return { lifecycleUid: a.lifecycleUid, mappingRevision: 0 };
                     return undefined;
                 },
+                ...(this.omitClassCommands() ? { omitClassCommands: this.omitClassCommands() } : {}),
             });
         }
         catch (e) {