@cotal-ai/manager 0.51.0 → 0.52.1

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 {
@@ -929,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. */
@@ -987,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
@@ -1509,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
@@ -2075,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;
@@ -2144,6 +2193,7 @@ 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, ctx.subject.route))),
@@ -2152,7 +2202,7 @@ export class Manager {
                 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);
@@ -2219,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)))),
@@ -2363,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
@@ -2397,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
@@ -2405,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.
@@ -2420,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,
@@ -2564,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?.();
@@ -2576,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)
@@ -2939,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) {
@@ -3301,6 +3357,33 @@ export class Manager {
             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
@@ -4935,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 } };
     }