@cotal-ai/manager 0.35.0 → 0.37.0

package/dist/manager.js

@@ -4,11 +4,11 @@ import { hostname } from "node:os";
 import { connect, credsAuthenticator } from "@nats-io/transport-node";
 import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
-import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, agentFilePath, clearSpaceHistory, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, loadAgentFile, loadCotalConfig, mintCreds, mintLifecycleUid, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, epRequestSubject, epCallerReplyFilter, parseEpSubject, controlServiceSubject, eventChannelPrincipal, } from "@cotal-ai/core";
-import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KEY, findCotalRoot, getSpaceAuth, hasUserAuthState, loadManagerInstanceIdentity, loadMeshes, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KEY, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, saveManagerInstanceIdentity, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
+import { 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 { AttachEndpoint } from "./attach-endpoint.js";
-import { makeManagerEndpointEvictor } from "./endpoint-evict.js";
+import { makeManagerEndpointEvictionEvidence, makeManagerEndpointEvictor } from "./endpoint-evict.js";
 import { makeManagerHolderLivenessProbe } from "./holder-liveness.js";
 import { GateReconcileRefused, reconcileEndpointGate } from "./reconcile-gate.js";
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts, parseLaunchSpec, persistLaunchSpec } from "./launch.js";
@@ -28,7 +28,7 @@ import { ManagerSessionPlane, openSessionLedgerKv } from "./session/index.js";
 // P2 item 1 (1a-serve): the manager as an ordinary v0.4 `service` endpoint — the §13.1
 // endpoint-serve credential subsystem (gate provisioning, registration barrier, mint fence) plus
 // 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, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, epeSubject, submissionFingerprint, EpEnvelopeError, } from "@cotal-ai/core";
+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, 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";
 /** Concurrency ceiling — the manager refuses to hold more than this many live + in-flight +
@@ -210,6 +210,8 @@ export class Manager {
     /** See {@link ManagerOptions.installedExtensions}. */
     installedExtensions;
     runtime;
+    /** Internal test seam. Production leaves this undefined and uses the scoped delivery-admin evictor. */
+    staticLifecycleEvict;
     preserveStopTimeoutMs;
     agents = new Map();
     /** Names whose spawn is in flight (reserved synchronously before the provision await) — counted
@@ -312,6 +314,9 @@ export class Manager {
     agentGoals = new Map();
     /** Process start, for the served `status` uptime. */
     startedAtMs = Date.now();
+    /** Connector harness paths resolved ONCE at boot. Missing binaries do not stop unrelated manager
+     * work, but they are named before the manager reports ready and remain visible in manager status. */
+    connectorStatuses = [];
     /** Static aliases whose startup exact-op terminal is still in flight. Scoped per alias: control
      * serves during the sweep, but no caller can reuse or attach an alias the sweep still owns. */
     reconcilingAliases = new Set();
@@ -453,6 +458,7 @@ export class Manager {
                 `refused outright and writes no creds file.`;
     }
     async start() {
+        await this.inspectConnectorsAtBoot();
         await this.attach.start();
         // In auth mode the manager is just another user in the space's account — it mints
         // itself creds from the same signing key it uses for the agents it spawns. The signer comes
@@ -542,9 +548,11 @@ export class Manager {
             watchChannels: false,
             card: { id, ...(this.remoteAuthority ? { owner: this.remoteAuthority.owner, actor: this.remoteAuthority.actors.supervisor } : {}), name: this.name, role: "manager", kind: "endpoint" },
         });
-        // Surface endpoint errors (incl. NATS permission denials) — without a listener an
-        // emitted "error" would crash the supervisor.
-        this.ep.on("error", (e) => console.error(`! manager endpoint: ${e.message}`));
+        // Raw failures ride error; conditions the endpoint is already surviving ride warning. Both
+        // matter to a supervisor operator, especially a failed standing-credential renewal.
+        const reportEndpoint = (e) => console.error(`! manager endpoint: ${e.message}`);
+        this.ep.on("error", reportEndpoint);
+        this.ep.on("warning", reportEndpoint);
         await this.ep.start();
         await this.ep.setActivity(`supervisor (${this.runtime.kind})`);
         // Per-instance liveness lease (P2 item 3 — the old per-space singleton is DEMOTED per D9). Acquire
@@ -645,9 +653,9 @@ export class Manager {
                 // re-signed) so its reply proves it adopted THIS generation, not merely re-read some file.
                 const expected = {};
                 for (const r of resigned) {
-                    if (r.file === DELIVERY_CREDS_KEY && r.fingerprint)
+                    if (r.file === DELIVERY_CREDS_KIND && r.fingerprint)
                         expected.delivery = r.fingerprint;
-                    else if (r.file === MEMBERSHIP_RW_CREDS_KEY && r.fingerprint)
+                    else if (r.file === MEMBERSHIP_RW_CREDS_KIND && r.fingerprint)
                         expected.membership = r.fingerprint;
                 }
                 try {
@@ -686,7 +694,7 @@ export class Manager {
                     if (a.userOwner || a.terminalizing || !a.seed || !a.secretPaths?.creds)
                         continue;
                     try {
-                        const stored = await this.secrets.get(agentSecretKeyForFile(a.secretPaths.creds));
+                        const stored = await this.secrets.get(agentSecretKeyForFile(a.secretPaths.creds, this.space));
                         if (stored === undefined)
                             continue; // no materialized cred (never minted here) - nothing to renew
                         const health = inspectCredHealth(stored);
@@ -783,11 +791,18 @@ export class Manager {
      *  attempt it. An absent file is the unprovisioned space, reported by the daemon that needs it. */
     warnOnSystemCredExpiry() {
         for (const file of SYSTEM_CREDS_FILES) {
-            const path = join(this.workspaceRoot, ".cotal", file);
-            if (!existsSync(path))
-                continue;
             let health;
             try {
+                // The pair is PER-SPACE as of P7, so the location comes from the resolver and never from a
+                // path built here (§2 rule 1). Building `.cotal/<kind>` instead would not warn on a wrong
+                // file — it would silently warn on NOTHING, for every provisioned root, forever, which is
+                // exactly the signal #338 added this for. The resolver may also refuse (§2 rules 3, 4); that
+                // refusal is caught with the unreadable case for the reason on the tin — the daemon that
+                // NEEDS the pair resolves it through the same function and reports it loudly there, so a
+                // diagnostic pass has nothing to add by crashing renewal.
+                const path = join(this.workspaceRoot, ".cotal", spaceMaterialKey(file, this.space, { injected: false, root: this.workspaceRoot }));
+                if (!existsSync(path))
+                    continue;
                 health = inspectCredHealth(readFileSync(path, "utf8"));
             }
             catch {
@@ -1172,14 +1187,29 @@ export class Manager {
      *  touches NEITHER the lease NOR the endpoints — the caller owns those. */
     async teardownManagedAgents() {
         const managed = [...this.agents.values()];
+        const failures = [];
         for (const a of managed) {
             // Free the slot + hard-stop each; `stopHandle` is best-effort (never throws — see it), so one bad
             // stop can't strand the rest, and every snapshot entry is deprovisioned below regardless.
             this.agents.delete(a.name);
             this.stopHandle(a, false);
         }
+        // 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
+        // runtime now supplies waitForExit; absence or timeout is a failed shutdown, never a clean one.
+        await Promise.all(managed.map(async (a) => {
+            try {
+                await this.awaitHandleExit(a.handle);
+            }
+            catch (e) {
+                failures.push(`${a.name}: ${e.message}`);
+            }
+        }));
         // Deprovision EVERY snapshot entry regardless of whether its stop failed (allSettled + a loud log).
         await Promise.allSettled(managed.filter((a) => !a.suppressCleanup).map((a) => this.deprovision(a).catch((e) => console.error(`deprovision ${a.name} (${a.id}) on shutdown: ${e.message}`))));
+        if (failures.length)
+            throw new Error(`manager shutdown could not prove every seat exited: ${failures.join("; ")}`);
     }
     async stopRetainedAgentsOnExit() {
         const managed = [...this.agents.values()];
@@ -1709,6 +1739,17 @@ export class Manager {
             }),
             stopSelf: (ctx) => this.serveGated(ctx, () => unwrap(this.opStopSelf(callerOf(ctx), args(ctx)))),
             definePersona: (ctx) => this.serveGated(ctx, () => unwrap(this.opDefinePersona(args(ctx), callerOf(ctx), false))),
+            listPersonas: (ctx) => this.serveGated(ctx, () => unwrap(this.opListPersonas(callerOf(ctx), false))),
+            showPersona: (ctx) => this.serveGated(ctx, () => {
+                const r = this.opShowPersona(args(ctx), callerOf(ctx), false);
+                if (!r.ok) {
+                    const msg = r.error ?? "not found";
+                    if (msg.startsWith("no persona"))
+                        throw new EpEnvelopeError("not-found", msg);
+                    throw new EpEnvelopeError("failed-precondition", msg);
+                }
+                return r.data;
+            }),
             purge: (ctx) => this.serveGated(ctx, () => adminGated(ctx, async () => unwrap(await this.opPurge(args(ctx), callerOf(ctx))))),
             // launch is OWNER-EQUALITY on the ep door for every caller (freelance HIGH #2): the deploy
             // path is the only launch consumer and its spec stamps the CALLER's own owner, so
@@ -1961,7 +2002,7 @@ export class Manager {
         const secrets = this.secrets;
         // LIFECYCLE-KEYED family (SPEC 13.1 name-disjointness on the FS): this incarnation's files
         // embed its uid, so no teardown addressed to another incarnation can ever reach them.
-        const files = agentLifecycleSecretFilePaths(this.workspaceRoot, name, opts.lifecycleUid);
+        const files = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, name, opts.lifecycleUid);
         const { actorToken: tokenPath, sentinelCreds: sentinelPath, health: healthPath } = files;
         try {
             // The GRANT first — it is the envelope-rule enforcement point (a delegation must sit within
@@ -1992,10 +2033,10 @@ export class Manager {
             // The store holds the source of truth; the bearer re-exec (`--token-file`) and the launch's
             // sentinel handoff read FILES, so materialize both at the canonical paths (under the local
             // FS composition, a byte-identical rewrite of the keys' own locations).
-            await secrets.put(agentSecretKeyForFile(tokenPath), grant.actorToken);
-            await secrets.put(agentSecretKeyForFile(sentinelPath), grant.sentinelCreds);
-            await materializeSecretToFile(secrets, agentSecretKeyForFile(tokenPath), tokenPath);
-            await materializeSecretToFile(secrets, agentSecretKeyForFile(sentinelPath), sentinelPath);
+            await secrets.put(agentSecretKeyForFile(tokenPath, this.space), grant.actorToken);
+            await secrets.put(agentSecretKeyForFile(sentinelPath, this.space), grant.sentinelCreds);
+            await materializeSecretToFile(secrets, agentSecretKeyForFile(tokenPath, this.space), tokenPath);
+            await materializeSecretToFile(secrets, agentSecretKeyForFile(sentinelPath, this.space), sentinelPath);
             rmSync(healthPath, { force: true }); // a fresh start opens a fresh health window
             const bearerCmd = [
                 // The manager's own invocation prefix (node + loader flags + the cotal entry) — the agent
@@ -2022,8 +2063,8 @@ export class Manager {
             // may respawn the moment it reads the refusal, and a detached teardown would race (and
             // delete) that fresh spawn's just-provisioned durables.
             await provider.revokeAgent({ dir, owner, actor: name }).catch(() => { });
-            await secrets.delete(agentSecretKeyForFile(tokenPath)).catch(() => { });
-            await secrets.delete(agentSecretKeyForFile(sentinelPath)).catch(() => { });
+            await secrets.delete(agentSecretKeyForFile(tokenPath, this.space)).catch(() => { });
+            await secrets.delete(agentSecretKeyForFile(sentinelPath, this.space)).catch(() => { });
             rmSync(tokenPath, { force: true });
             rmSync(sentinelPath, { force: true });
             rmSync(healthPath, { force: true });
@@ -2162,9 +2203,9 @@ export class Manager {
         // standing `cotal mint` cred, a seeded workstation cred, a pre-split leftover): deleting an
         // unowned same-name file is the exact successor-clobber this ownership discipline removes.
         const secrets = this.secrets;
-        const files = a.secretPaths ?? agentLifecycleSecretFilePaths(this.workspaceRoot, a.name, a.lifecycleUid);
+        const files = a.secretPaths ?? agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, a.name, a.lifecycleUid);
         if (files.creds) {
-            await secrets.delete(agentSecretKeyForFile(files.creds));
+            await secrets.delete(agentSecretKeyForFile(files.creds, this.space));
             rmSync(files.creds, { force: true });
         }
         if (a.userOwner) {
@@ -2173,9 +2214,9 @@ export class Manager {
             // denied) and shred the secret/sentinel/health files. A copied actor token dies here; a
             // still-LIVE connection ends at its bearer-bound JWT expiry (≤ the agent TTL).
             if (files.actorToken)
-                await secrets.delete(agentSecretKeyForFile(files.actorToken));
+                await secrets.delete(agentSecretKeyForFile(files.actorToken, this.space));
             if (files.sentinelCreds)
-                await secrets.delete(agentSecretKeyForFile(files.sentinelCreds));
+                await secrets.delete(agentSecretKeyForFile(files.sentinelCreds, this.space));
             for (const f of [files.actorToken, files.sentinelCreds, files.health])
                 if (f)
                     rmSync(f, { force: true });
@@ -2714,6 +2755,48 @@ export class Manager {
     connectorNames() {
         return this.installedExtensions ? manifestExtensionNames("connector") : registry.all("connector").map((c) => c.name);
     }
+    /** Resolve every installed/registered connector's declared harness binaries before the manager
+     * reports ready. A missing harness degrades only that connector, never unrelated lifecycle work:
+     * boot continues, but prints a named refusal and records it on both manager status surfaces. */
+    async inspectConnectorsAtBoot() {
+        const rows = [];
+        let declared;
+        if (this.installedExtensions) {
+            try {
+                declared = loadExtensionsManifest().extensions.flatMap((ext) => extensionConnectors(ext));
+            }
+            catch (error) {
+                const reason = error.message;
+                console.error(`! manager boot: connector inventory unavailable - ${reason}`);
+                this.connectorStatuses = [{ agent: "(inventory)", state: "unavailable", binaries: {}, reason }];
+                return;
+            }
+        }
+        else {
+            declared = registry.all("connector").map((connector) => ({ name: connector.name, requires: connector.requires ?? [] }));
+        }
+        for (const connector of declared) {
+            const name = connector.name;
+            const binaries = {};
+            const missing = [];
+            for (const bin of connector.requires) {
+                const path = resolveOnPath(bin);
+                if (path)
+                    binaries[bin] = path;
+                else
+                    missing.push(bin);
+            }
+            if (missing.length) {
+                const reason = `${name} harness needs ${missing.join(", ")} on PATH - not found`;
+                rows.push({ agent: name, state: "unavailable", binaries, reason });
+                console.error(`! manager boot: connector ${name} unavailable - ${reason}`);
+            }
+            else {
+                rows.push({ agent: name, state: "available", binaries });
+            }
+        }
+        this.connectorStatuses = rows.sort((a, b) => a.agent.localeCompare(b.agent));
+    }
     /** 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
      *  fails to import shows an `error:` row (from manifest enumeration) and never blocks the others. */
@@ -2957,9 +3040,16 @@ export class Manager {
         // Harness preflight before reserving a slot or minting — a missing `claude`/`opencode` binary
         // 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 missing = (connector.requires ?? []).filter((bin) => !resolveOnPath(bin));
-        if (missing.length)
-            return { ok: false, error: `${agent} harness needs ${missing.join(", ")} on PATH - not found` };
+        const bootStatus = this.connectorStatuses.find((row) => row.agent === agent);
+        if (bootStatus?.state === "unavailable")
+            return { ok: false, error: bootStatus.reason };
+        // 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` };
+        }
         // 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
         // reject-before-side-effects window as the harness preflight above; buildLaunch stays the backstop.
@@ -3033,6 +3123,29 @@ export class Manager {
         const idErr = this.nameError(identityName);
         if (idErr)
             return { ok: false, error: opts.resolved ? `launch agent: ${idErr}` : `persona ${configPath}: ${idErr}` };
+        // #966: a seat labelled `manager` that cannot spawn is a worker wearing a label, and the label
+        // is what other agents ROUTE on (role is the anycast address). The gap is silent today because
+        // the mismatch is only discovered minutes in, when the seat first reaches for a worker. The
+        // persona write path takes content only (role/capabilities are POLICY, P6), so a peer-defined
+        // persona can never fix this by declaring the capability — the only honest outcomes are "the
+        // persona grants spawn" or "say so now". Refuse at accept, before any reserve/mint, naming the
+        // exact remediation for each author: an operator edits the file to add the grant; a peer that
+        // defined the persona over the wire must ask one, because capabilities cannot be declared over
+        // the wire by design. The check keys on the EFFECTIVE role (a spawn-time role: override wins
+        // over the file, mirroring the resolution above), not the file's, so the label other agents
+        // will actually see is the label that is held to account. `manager` is the label that MEANS
+        // spawn-holding: naming it literally keeps this the narrow guard for the observed harm, not a
+        // vocabulary any caller can trigger with a synonym (roles are free-form and mostly
+        // non-manager: this workspace's own catalog carries worker/reviewer/orchestrator seats with no
+        // spawn grant, all legitimate).
+        if (role === "manager" && !capabilities?.includes("spawn"))
+            return {
+                ok: false,
+                error: `persona "${ref}" would join with role "manager" but no spawn capability: it presents as a manager ` +
+                    `while being unable to seat workers, and it would discover that only on first use. ` +
+                    `An operator adds \`capabilities: [spawn]\` to ${configPath}; a peer-defined persona ` +
+                    `(cotal_persona) cannot declare capabilities by design — ask an operator to grant it.`,
+            };
         // The alias-reuse gate (#29 piece 3): a name whose previous agent is still retiring REFUSES
         // legibly (never a silent suffix), and the refusal re-drives the FULL durable teardown so
         // "retry the spawn" is also the nudge. It routes through `deprovision` (not `requestRetirement`
@@ -3044,10 +3157,8 @@ export class Manager {
         const held = this.retiring.get(identityName);
         if (held !== undefined) {
             void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, secretPaths: held.secretPaths }).catch(() => { });
-            return {
-                ok: false,
-                error: `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`,
-            };
+            const err = lifecycleBlocked("failed-precondition", `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`, { blockedOp: "retirement", headState: "retiring", opId: held.opId, remedy: "retry" });
+            return { ok: false, error: renderLifecycleBlocked(err.message, err), details: err.details };
         }
         if (variant && !connector.supportsModelVariant)
             return { ok: false, error: `${agent} connector does not support model variants (variant)` };
@@ -3247,9 +3358,9 @@ export class Manager {
                 const secrets = this.secrets;
                 // LIFECYCLE-KEYED (SPEC 13.1 on the FS): the incarnation's cred file embeds its uid, so a
                 // replayed/stale teardown can never address a same-name successor's credential.
-                credsPath = agentLifecycleSecretFilePaths(this.workspaceRoot, name, lifecycleUid).creds;
-                await secrets.put(agentSecretKeyForFile(credsPath), creds);
-                await materializeSecretToFile(secrets, agentSecretKeyForFile(credsPath), credsPath);
+                credsPath = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, name, lifecycleUid).creds;
+                await secrets.put(agentSecretKeyForFile(credsPath, this.space), creds);
+                await materializeSecretToFile(secrets, agentSecretKeyForFile(credsPath, this.space), credsPath);
                 provisioned = { id: identity.id, name, lifecycleUid, secretPaths: { creds: credsPath } }; // footprint now exists — the finally rolls it back if the spawn throws
             }
             // Personal MCP servers the operator opted to share with manager-spawned agents of this type
@@ -3305,6 +3416,7 @@ export class Manager {
                 events,
                 mcpServers,
                 envAllow,
+                resolvedBinaries: bootStatus?.binaries,
                 // So a connector that keeps per-agent local state can root it at the workspace, not the
                 // (possibly per-agent) launch cwd below. The cwd itself rides runtime.spawn, not the launch.
                 workspaceRoot: this.workspaceRoot,
@@ -3428,6 +3540,10 @@ export class Manager {
         catch (e) {
             // Failure after reserve (provision / launch threw): the slot was never live, so no cold-start
             // was paid — the reserved rollback (finally) is enough, no cooling stamp.
+            // A lifecycle-blocked envelope already named the barrier; keep its details on the ControlReply
+            // so follow/CLI/cotal_spawn do not collapse it to a generic string (#873).
+            if (e instanceof EpEnvelopeError)
+                return { ok: false, error: renderLifecycleBlocked(e.message, e), ...(e.details ? { details: e.details } : {}) };
             return { ok: false, error: e.message };
         }
         finally {
@@ -3570,8 +3686,8 @@ export class Manager {
             // layout) or the name-keyed one (a pre-split inventory being carried across the upgrade).
             // Anything else is a foreign path and refused exactly as before.
             const candidates = [
-                resolve(agentLifecycleSecretFilePaths(this.workspaceRoot, entry.name, entry.identity.lifecycleUid).creds),
-                resolve(agentSecretFilePaths(this.workspaceRoot, entry.name).creds),
+                resolve(agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, entry.name, entry.identity.lifecycleUid).creds),
+                resolve(agentSecretFilePaths(this.workspaceRoot, this.space, entry.name).creds),
             ];
             const expected = resolve(entry.identity.credential.path);
             if (!candidates.includes(expected))
@@ -3584,7 +3700,7 @@ export class Manager {
                 const st = lstatSync(expected);
                 if (!st.isFile() || st.isSymbolicLink())
                     throw new Error("not a regular non-symlink file");
-                const stored = await this.secrets.get(agentSecretKeyForFile(expected));
+                const stored = await this.secrets.get(agentSecretKeyForFile(expected, this.space));
                 if (stored === undefined)
                     throw new Error("the credential is not in the secret store");
                 credentialText = stored;
@@ -3613,17 +3729,20 @@ export class Manager {
             // the atomic family closes both: `health` is pinned by PATH EQUALITY (never by file existence,
             // so a transiently-absent health file still validates), and the store reads below key off the
             // RECORDED path, so a foreign path can neither pass the pin nor address a different row.
-            const lifecycleFiles = agentLifecycleSecretFilePaths(this.workspaceRoot, entry.name, entry.identity.lifecycleUid);
-            const legacyFiles = agentSecretFilePaths(this.workspaceRoot, entry.name);
+            // Both triples are derived under THIS manager's space, and the key builder is given
+            // `this.space` rather than reading the segment out of the recorded path: an inventory row is
+            // caller data, and a recorded path may not choose which tenant's material is addressed.
+            const lifecycleFiles = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, entry.name, entry.identity.lifecycleUid);
+            const legacyFiles = agentSecretFilePaths(this.workspaceRoot, this.space, entry.name);
             const recordedToken = resolve(entry.identity.actorToken.path);
             const recordedSentinel = resolve(entry.identity.sentinelCredential.path);
             const recordedHealth = resolve(entry.identity.health.path);
             const matchesFamily = (f) => recordedToken === resolve(f.actorToken) && recordedSentinel === resolve(f.sentinelCreds) && recordedHealth === resolve(f.health);
             if (!matchesFamily(lifecycleFiles) && !matchesFamily(legacyFiles))
-                throw new Error(`retained identity references for ${entry.name} are not one manager-owned secret family: all of actor-token, sentinel, and health must be the lifecycle-<uid> triple or the legacy name-keyed triple under ${agentCredsDir(this.workspaceRoot)} (no mixed families, no foreign health path)`);
+                throw new Error(`retained identity references for ${entry.name} are not one manager-owned secret family: all of actor-token, sentinel, and health must be the lifecycle-<uid> triple or the legacy name-keyed triple under ${agentCredsDir(this.workspaceRoot, this.space)} (no mixed families, no foreign health path)`);
             const secrets = this.secrets;
-            const actorToken = await secrets.get(agentSecretKeyForFile(recordedToken));
-            const sentinelCreds = await secrets.get(agentSecretKeyForFile(recordedSentinel));
+            const actorToken = await secrets.get(agentSecretKeyForFile(recordedToken, this.space));
+            const sentinelCreds = await secrets.get(agentSecretKeyForFile(recordedSentinel, this.space));
             if (actorToken === undefined || sentinelCreds === undefined)
                 throw new Error("the retained actor token / sentinel credential is not in the secret store");
             const adopted = await provider.validateRetainedAgent({
@@ -3829,7 +3948,7 @@ export class Manager {
             // preserve/resume — without it the adopted cred would die loud at its TTL with no remint.
             let adoptedSeed;
             if (entry.identity.mode === "static") {
-                const stored = await this.secrets.get(agentSecretKeyForFile(resolve(entry.identity.credential.path)));
+                const stored = await this.secrets.get(agentSecretKeyForFile(resolve(entry.identity.credential.path), this.space));
                 adoptedSeed = stored === undefined ? undefined : /-----BEGIN USER NKEY SEED-----\s*([A-Z0-9]+)\s*-----END USER NKEY SEED-----/.exec(stored)?.[1];
                 if (adoptedSeed === undefined)
                     console.error(`! resume ${entry.name}: the adopted credential carries no readable nkey seed - the manager cannot renew it (it dies loud at its exp)`);
@@ -4212,6 +4331,7 @@ export class Manager {
             runtime: this.runtime.kind,
             agentCount: this.agents.size,
             uptimeMs: Date.now() - this.startedAtMs,
+            connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),
         };
     }
     /** Complete a crashed predecessor's FROZEN registration gate before this incarnation starts a
@@ -4429,7 +4549,12 @@ export class Manager {
             // one). Key-pinned to this instance's own status key on the SAME executor.
             await writeServiceStatus(recordsKv, {
                 endpoint: MANAGER_ENDPOINT, instanceId: iid, epoch: observed.processEpoch,
-                status: { state: SERVICE_READY, epoch: observed.processEpoch, observedSpecRevision: registrationRevision },
+                status: {
+                    state: SERVICE_READY,
+                    epoch: observed.processEpoch,
+                    observedSpecRevision: registrationRevision,
+                    connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),
+                },
                 readProcessEpoch: async () => {
                     const g = await fence.observe();
                     if (g === null)
@@ -5138,13 +5263,13 @@ export class Manager {
                 // exists that early — the goal spec does not carry it and the terminal does not exist yet.
                 // A same-goalId attempt that loses the bind while the winner is still in flight can then
                 // serve what the winner actually allocated instead of inventing an empty identity.
-                const idx = await recordGoalIndex(gw.ctx, ref, executor.lifecycleUid, { name, actor: agentTriple.actor, uid: agentTriple.uid });
+                const idx = await recordGoalIndex(gw.ctx, ref, executor.lifecycleUid, { name, actor: agentTriple.actor, uid: agentTriple.uid, readinessDeadlineMs: readinessTimeoutMs });
                 // A create loss is an idempotent retry ONLY for the same incarnation. A FOREIGN iid means a
                 // sibling instance accepted this goalId (the live vector is a client retry over ANYCAST, not
                 // a journal consumer): this attempt provisions nothing and answers with the winner's floor,
                 // or refuses if that instance never persisted one.
                 if (!idx.recorded && idx.existing.iid !== executor.lifecycleUid) {
-                    acceptance = this.acceptanceFromIndex(idx.existing, goalId, fingerprint, executor);
+                    acceptance = await this.acceptanceFromIndex(idx.existing, ref, goalId, fingerprint, executor);
                     resolveAccept(acceptance);
                     // No claim needed here: `ownsGoal` is still false, so the commit path refuses this attempt.
                     throw new EpEnvelopeError("failed-precondition", `goal "${goalId}" was accepted by instance "${idx.existing.iid}"; that instance's acceptance is served and this attempt provisions nothing (SPEC 13.6)`);
@@ -5180,7 +5305,7 @@ export class Manager {
                     acceptedAt,
                     readinessDeadlineMs: readinessTimeoutMs,
                 });
-                acceptance = { name, owner: agentTriple.owner, actor: agentTriple.actor, uid: agentTriple.uid, goalId, fingerprint, executor };
+                acceptance = { name, owner: agentTriple.owner, actor: agentTriple.actor, uid: agentTriple.uid, goalId, fingerprint, readinessDeadlineMs: readinessTimeoutMs, executor };
                 this.goalAcceptances.set(goalId, acceptance);
                 this.agentGoals.set(name, ref); // M4: a despawn of this name mid-goal drives the cancel path
                 resolveAccept(acceptance);
@@ -5197,7 +5322,8 @@ export class Manager {
         bg.then((reply) => {
             // Refused BEFORE onAccepted (M6 hard-pin collision, capacity, persona-not-found) — no goal bound.
             if (acceptance === undefined) {
-                rejectAccept(new EpEnvelopeError("failed-precondition", reply.error ?? "spawn refused at accept"));
+                const details = reply.details;
+                rejectAccept(new EpEnvelopeError("failed-precondition", reply.error ?? "spawn refused at accept", details));
                 return;
             }
             // H1: `run` CATCHES its own body (a throw in buildLaunch/runtime.spawn) and RESOLVES `{ok:false}`
@@ -5206,7 +5332,7 @@ export class Manager {
             // the caller follows epe to a terminal that never comes, and the reconcile index that would
             // settle it is only swept at BOOT, so a manager that stays up never converges it.
             if (reply.ok === false && !terminalEntered)
-                return onOutcome({ kind: "failed", data: { error: reply.error ?? "spawn failed after accept" } });
+                return onOutcome({ kind: "failed", data: { error: reply.error ?? "spawn failed after accept", ...(reply.details ? { details: reply.details } : {}) } });
         }).catch((e) => {
             if (acceptance === undefined) {
                 rejectAccept(e);
@@ -5214,7 +5340,7 @@ export class Manager {
             }
             // Same obligation for a genuine rejection (one that escaped `run`'s own catch).
             if (!terminalEntered)
-                return onOutcome({ kind: "failed", data: { error: e?.message ?? String(e) } });
+                return onOutcome({ kind: "failed", data: { error: e?.message ?? String(e), ...(e instanceof EpEnvelopeError && e.details ? { details: e.details } : {}) } });
             console.error(`! spawn-as-action async body for ${goalId}: ${e?.message ?? String(e)}`);
         }).catch((e) => console.error(`! goal terminal fallback for ${goalId}: ${e?.message ?? String(e)}`));
         return acceptP;
@@ -5222,10 +5348,13 @@ export class Manager {
     /** H2: an acceptance served from a WINNER'S durable acceptance floor (the goal-index entry it
      *  wrote before its own ack). Refuses `unavailable` rather than inventing one — see
      *  {@link cachedSpawnAcceptance} for why an empty identity is never an acceptable answer. */
-    acceptanceFromIndex(entry, goalId, fingerprint, executor) {
+    async acceptanceFromIndex(entry, ref, goalId, fingerprint, executor) {
         if (entry.allocated === undefined)
             throw new EpEnvelopeError("unavailable", `goal "${goalId}" was accepted by instance "${entry.iid}", which persisted no acceptance floor; its allocated identity is not readable from here (SPEC 13.6)`);
-        return { name: entry.allocated.name, owner: DEV_OWNER, actor: entry.allocated.actor, uid: entry.allocated.uid, goalId, fingerprint, executor };
+        const readinessDeadlineMs = entry.allocated.readinessDeadlineMs ?? (await readGoalSpec(this.goalWriter.ctx, ref))?.value.readinessDeadlineMs;
+        if (readinessDeadlineMs === undefined)
+            throw new EpEnvelopeError("unavailable", `goal "${goalId}" is accepted but its readiness deadline is not readable; a synchronous follower cannot bound its wait honestly (SPEC 13.6)`);
+        return { name: entry.allocated.name, owner: DEV_OWNER, actor: entry.allocated.actor, uid: entry.allocated.uid, goalId, fingerprint, readinessDeadlineMs, executor };
     }
     /** Reconstruct a cached acceptance for a same-goalId retry NOT in the live map (a prior incarnation
      *  accepted it, or a concurrent winner whose map write this reader has not yet observed).
@@ -5241,13 +5370,15 @@ export class Manager {
     async cachedSpawnAcceptance(ref, goalId, fingerprint, executor) {
         const entry = await readGoalIndex(this.goalWriter.ctx, ref);
         if (entry?.allocated !== undefined)
-            return this.acceptanceFromIndex(entry, goalId, fingerprint, executor);
+            return this.acceptanceFromIndex(entry, ref, goalId, fingerprint, executor);
         // The index is CLEARED at terminal, so a settled goal legitimately has no entry: fall back to
         // the terminal's data, which carries the same identity for exactly that case.
         const result = await readGoalResult(this.goalWriter.ctx, ref);
         const d = (result?.data ?? {});
-        if (typeof d.name === "string" && d.name.length > 0 && typeof d.id === "string" && d.id.length > 0 && typeof d.lifecycleUid === "string" && d.lifecycleUid.length > 0)
-            return { name: d.name, owner: DEV_OWNER, actor: d.id, uid: d.lifecycleUid, goalId, fingerprint, executor };
+        const spec = await readGoalSpec(this.goalWriter.ctx, ref);
+        const readinessDeadlineMs = spec?.value.readinessDeadlineMs;
+        if (typeof d.name === "string" && d.name.length > 0 && typeof d.id === "string" && d.id.length > 0 && typeof d.lifecycleUid === "string" && d.lifecycleUid.length > 0 && readinessDeadlineMs !== undefined)
+            return { name: d.name, owner: DEV_OWNER, actor: d.id, uid: d.lifecycleUid, goalId, fingerprint, readinessDeadlineMs, executor };
         throw new EpEnvelopeError("unavailable", `goal "${goalId}" is already accepted but its allocated identity is not readable (no acceptance floor, and no terminal carrying one); retry (SPEC 13.6)`);
     }
     /** M4 (settle race): a despawn MID-GOAL drives the goal's cancel terminal - transition to
@@ -5289,11 +5420,17 @@ export class Manager {
         if (acceptedRenewal)
             await acceptedRenewal.catch(() => { });
         const opId = retireOpId(a.lifecycleUid);
+        const evict = this.staticLifecycleEvict ?? makeManagerEndpointEvictionEvidence({
+            space: this.space,
+            servers: this.servers ?? DEFAULT_SERVER,
+            auth: this.auth,
+            log: (line) => console.error(`static retirement ${a.name}: ${line}`),
+        });
         const cleanup = async () => {
             const secrets = this.secrets;
-            const files = a.secretPaths ?? agentLifecycleSecretFilePaths(this.workspaceRoot, a.name, a.lifecycleUid);
+            const files = a.secretPaths ?? agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, a.name, a.lifecycleUid);
             if (files.creds) {
-                await secrets.delete(agentSecretKeyForFile(files.creds));
+                await secrets.delete(agentSecretKeyForFile(files.creds, this.space));
                 rmSync(files.creds, { force: true });
             }
             await this.deprovisionBroker(a);
@@ -5307,7 +5444,10 @@ export class Manager {
                     await cleanup();
                     return;
                 }
-                await runStaticTerminal(t, { owner: DEV_OWNER, alias: a.name, actor: a.id, lifecycleUid: a.lifecycleUid, opId }, { cleanup, log: (line) => console.error(`static retirement ${a.name}: ${line}`) });
+                await runStaticTerminal(t, {
+                    owner: DEV_OWNER, alias: a.name, actor: a.id, lifecycleUid: a.lifecycleUid, opId,
+                    managerInstance: this.managerInstanceId, managerProcessUid: this.managerLifecycleUid,
+                }, { cleanup, evict, log: (line) => console.error(`static retirement ${a.name}: ${line}`) });
             });
             this.retiredPrincipals.add(principalKey(DEV_OWNER, a.id).key);
             const cur = this.retiring.get(a.name);
@@ -5364,15 +5504,15 @@ export class Manager {
         });
         const secrets = this.secrets;
         const credsPath = a.secretPaths.creds;
-        await secrets.put(agentSecretKeyForFile(credsPath), creds);
-        await materializeSecretToFile(secrets, agentSecretKeyForFile(credsPath), credsPath);
+        await secrets.put(agentSecretKeyForFile(credsPath, this.space), creds);
+        await materializeSecretToFile(secrets, agentSecretKeyForFile(credsPath, this.space), credsPath);
         console.error(`managed cred renewal ${a.name}: re-signed for the same identity (exp +${MANAGED_STATIC_TTL_SEC}s); the agent endpoint's source re-read adopts it`);
     }
     /** The Unit B reconciliation (F3 "no active orphan"): ensure the authority stores, then sweep
      *  every durable slot row and act by the TOTAL resume table — `provisioning`/`terminalizing`
      *  re-drive the exact-op terminal; an `active` row survives ONLY when a LIVE managed agent this
-     *  process owns backs it at the same uid (`adopted`), else its process is gone and it
-     *  terminalizes; `retired` rows seed the F5 refusal index. Two call sites: the BOOT sweep
+     *  manager process owns backs it at the same uid (`adopted`), else no managed owner claimed it and
+     *  its broker authority is contained and terminalized; `retired` rows seed the F5 refusal index. Two call sites: the BOOT sweep
      *  (`postAdoption=false`, under the lease before control serving) DEFERS active-non-adopted
      *  slots while a resume is still pending (adoption runs after it); the POST-ADOPTION sweep
      *  (`postAdoption=true`, inside finalizeResume while `resumeRequired` still fences ordinary
@@ -5598,6 +5738,78 @@ export class Manager {
         }
         return { ok: true, data: { name, path } };
     }
+    /** Whether this caller may READ a catalog card's details (role/model/description/body). Same
+     *  ownership rule as redefine: owner == caller, or admin. Ownerless / operator-written files are
+     *  admin-only. Names of parseable files still appear on the list so a definer can see a taken
+     *  spawn name; details stay off the wire unless this is true. */
+    canReadPersona(owner, caller, admin) {
+        return personaCatalogReadable(owner, caller, admin);
+    }
+    /** Mesh-side catalog list (#402). Every parseable name is returned so a definer can see a taken
+     *  spawn name. Role / model / description / owner ride only when the caller could redefine the
+     *  file (same ownership as `definePersona`); other cards are name-only, so a peer cannot read a
+     *  prompt it does not own. Unparseable files are omitted for non-admin (no existence leak of a
+     *  broken card). */
+    opListPersonas(caller, admin) {
+        const personas = [];
+        for (const e of listPersonaCatalog(this.workspaceRoot)) {
+            if (e.error) {
+                if (!admin)
+                    continue;
+                personas.push({ name: e.name, error: "unparseable" });
+                continue;
+            }
+            const def = e.def;
+            if (!this.canReadPersona(def.owner, caller, admin)) {
+                personas.push({ name: e.name });
+                continue;
+            }
+            const description = personaCatalogDescription(def);
+            personas.push({
+                name: e.name,
+                ...(def.role ? { role: def.role } : {}),
+                ...(def.model ? { model: def.model } : {}),
+                ...(description ? { description } : {}),
+                ...(def.owner ? { owner: def.owner } : {}),
+            });
+        }
+        return { ok: true, data: { personas } };
+    }
+    /** Mesh-side catalog show (#402). Same ownership as list. Unknown, unauthorized, or unparseable
+     *  names are not-found (no existence or parser-diagnostic leak). The body is included so a peer can
+     *  inspect a prompt it owns before spawn; policy fields stay off the wire. */
+    opShowPersona(args, caller, admin) {
+        const name = String(args.name ?? "").trim();
+        if (!name)
+            return { ok: false, error: "name required" };
+        const nameErr = this.nameError(name);
+        if (nameErr)
+            return { ok: false, error: nameErr };
+        const path = agentFilePath(this.workspaceRoot, name);
+        if (!existsSync(path))
+            return { ok: false, error: `no persona "${name}"` };
+        let def;
+        try {
+            def = loadAgentFile(path);
+        }
+        catch {
+            return { ok: false, error: `no persona "${name}"` };
+        }
+        if (!this.canReadPersona(def.owner, caller, admin))
+            return { ok: false, error: `no persona "${name}"` };
+        const description = personaCatalogDescription(def);
+        return {
+            ok: true,
+            data: {
+                name,
+                ...(def.role ? { role: def.role } : {}),
+                ...(def.model ? { model: def.model } : {}),
+                ...(description ? { description } : {}),
+                ...(def.owner ? { owner: def.owner } : {}),
+                ...(def.persona ? { persona: def.persona } : {}),
+            },
+        };
+    }
     /** The post-authorization `input` effect (C3): type `text` into the seat's terminal as if a human
      *  had. The single call an external UI needs to deliver a harness command (`/compact`, `/clear`,
      *  `/model`) without holding a terminal open on the caller's side.
@@ -5734,7 +5946,7 @@ export class Manager {
             // FAIL-CLOSED: a failed record is the failure + repair sentence; a missing/malformed or
             // stale record on a live agent is auth-unknown/auth-stale, NEVER silently healthy.
             const health = a.userOwner
-                ? agentAuthState(a.secretPaths?.health ?? agentLifecycleSecretFilePaths(this.workspaceRoot, a.name, a.lifecycleUid).health)
+                ? agentAuthState(a.secretPaths?.health ?? agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, a.name, a.lifecycleUid).health)
                 : undefined;
             return {
                 name: a.name,