@cotal-ai/cli 0.16.0 → 0.17.0

package/dist/lib/control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACb,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE;2CAC2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;wBAKwB;AACxB,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAgB/D;AAED;;;;;;;uDAOuD;AACvD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,GAAE,WAAgB,EACtB,IAAI,GAAE,WAAgC,EACtC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CA4BvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAUrD"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,YAAY,EACjB,KAAK,QAAQ,EAEb,KAAK,OAAO,EACb,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAE1F;;6EAE6E;AAC7E,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAa1H;;;;;wBAKwB;AACxB,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CA+D/D;AA0BD;;yFAEyF;AACzF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,CAAC;AA0F3C;;;;;;;;;4DAS4D;AAC5D,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,GAAE,WAAgB,EACtB,KAAK,GAAE,YAAsB,EAC7B,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAYvB;AAED;;4GAE4G;AAC5G,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,oBAAoB,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA6C1G;;;;8EAI8E;AAC9E,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,WAAgB,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAOvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAUrD"}

package/dist/lib/control.js

@@ -1,7 +1,18 @@
-import { CotalEndpoint, DEFAULT_SPACE, CONTROL_PRIVILEGED, CONTROL_ADMIN, } from "@cotal-ai/core";
-import { authDir, endpointAuth, findCotalRoot, loadSpaceAuth, soleSpaceOf } from "@cotal-ai/workspace";
+import { DEFAULT_SPACE, DEV_OWNER, BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, GOAL_BEARING_COMMANDS, invokeCommand, submitAndFollowGoal, scatterCommand, mintLifecycleUid, newIdentity, resolveService, standaloneConnectOpts, } from "@cotal-ai/core";
+import { connect } from "@nats-io/transport-node";
+import { authDir, endpointAuth, findCotalRoot, isWorkspaceTargetError, loadSpaceAuth, resolveMeshTarget, pruneStaleMeshes, renderWorkspaceError, soleSpaceOf, } from "@cotal-ai/workspace";
 import { c, staleStoreHint } from "../ui.js";
-import { connectOrExit } from "./connect.js";
+import { connectOrExit, connectUserControlOrExit } from "./connect.js";
+/** The only {@link MeshTargetErrorCode}s that mean "there is NO registry entry here", and so the
+ *  only ones the mode peek in {@link resolveControlTarget} may absorb. **Every other code is
+ *  NON-ABSENCE and must fail loud** — which is the precise claim, and covers more than one
+ *  situation: `stale-auth-root` / `unreadable-auth` / `user-auth-unrecorded` are an entry that
+ *  exists and is broken, while `ambiguous-target` can be several perfectly healthy entries and
+ *  `default-occupied` an intended local target with no entry at all. What unites them is not
+ *  breakage, it is that absence has NOT been established, so falling through to a
+ *  credential-less raw-open connect would be unsound. Deliberately a closed allow-list, not a
+ *  deny-list: a new code defaults to failing loud. */
+const TARGET_ABSENT_CODES = new Set(["unknown-space", "no-meshes"]);
 /** Client-side request window for the manager's readiness-waiting launch ops (`start`, and the
  *  manifest `launch` — both funnel into the same startAgent readiness wait). #159 B1: the manager
  *  replies only on a REAL outcome — presence join, process exit, or its ~30s readiness backstop —
@@ -23,58 +34,254 @@ export async function resolveControlTarget(flags, profile) {
     const withSpace = flags.creds
         ? { ...flags, space: flags.space ?? soleSpaceOf(authDir(findCotalRoot())) ?? DEFAULT_SPACE }
         : flags;
-    // USER MODE rides through: the control call connects with the operator's bearer (actor `cli`) and
-    // publishes on its OWN ctl principal subject — the broker grants that publish only when the cli
-    // actor's ledger scope carries the matching capability (`spawn` → privileged, `admin` → admin).
-    // The preflight probe STAYS, and the duplicate handshake with it. Removing it saved one connect
-    // per control command, and cost two things worth more: the classified failure (a live broker
-    // rejecting stale registry creds reads as `registry-creds-rejected`/`stale-auth` with the right
-    // repair, not "is it running? run cotal up"), and the probe's 8s bound — `CotalEndpoint` passes no
-    // connect timeout, so nats-core's 20s default would apply and a blackholed target would hang more
-    // than twice as long to produce worse copy. Reusing the real connection is the right idea; it needs
-    // the endpoint to accept a deadline and the classifier to move with it, which is not this change.
+    // USER MODE: ledger-scoped bearer is the control surface; there is no instrument mint.
+    // `connectOrExit` refuses control-caller-* on a user mesh (those profiles carry freeze rows the
+    // bearer does not hold). Route through {@link connectUserControlOrExit}, which takes NO role —
+    // a dummy Profile would be meaningless today and wrong the day the user path starts consulting
+    // it. Declared translation at this layer (the one that knows), not a silent substitute inside
+    // connectOrExit.
+    //
+    // Cost: the target is resolved here for the mode check and again inside the connect helper.
+    // Accepted for this slice so mode choice stays where it is knowable. The two reads are not
+    // atomic; a mesh that flips mode between them is an operator action mid-command.
+    //
+    // This peek reads the MODE and NOTHING ELSE — it must never decide the command's fate. It used
+    // to run through `resolveTargetOrExit`, which EXITS on a WorkspaceTargetError, so it killed a
+    // legitimate input on the way past: `--server` with an UNREGISTERED `--space` is the raw-open
+    // escape hatch, and by definition it has no registry entry to carry a mode. Resolve through the
+    // THROWING form instead and read ABSENCE as "not a registry mesh, therefore not user mode",
+    // leaving that path to `connectOrExit` below, which owns it.
+    //
+    // ABSENCE ONLY. The two absent codes are the entire escape hatch; every other
+    // MeshTargetErrorCode is NON-ABSENCE, and swallowing those is a
+    // fallback, not a restoration. `stale-auth-root` is the one that bites: `targetFromEntry`
+    // PRUNES the entry before throwing it, so absorbing it leaves `connectOrExit` seeing no
+    // registration at all — and with an explicit `--server` it then takes the raw-open arm and
+    // connects with NO CREDENTIALS. A misconfigured AUTH mesh would silently become an OPEN one,
+    // hiding the misconfiguration and switching identity planes under the operator. Those codes
+    // rethrow and the command dies loud, exactly as it did before this peek existed.
+    // Raw `--creds` skips the peek entirely (static/raw path below).
+    if (!withSpace.creds) {
+        // Sweep first when no space is named, exactly as `resolveTargetOrExit` does before ITS
+        // resolve. Without it the peek reads a world `connectOrExit` never sees: a dead entry
+        // alongside a live one makes a bare resolve `ambiguous-target` here while the connect,
+        // having pruned, resolves the single survivor cleanly. Same sweep, same view, one answer.
+        if (!withSpace.space)
+            await pruneStaleMeshes();
+        let mode;
+        try {
+            mode = resolveMeshTarget(process.cwd(), { server: withSpace.server, space: withSpace.space }).mode;
+        }
+        catch (e) {
+            // Non-absence propagates and ends the command. It is rethrown rather than rendered-and-exited
+            // here so this function stays composable and testable; the CLI boundary renders every
+            // WorkspaceTargetError through `renderWorkspaceError` (see the dispatcher's catch), which is
+            // what turns "entry X points at a root holding Y" into the removed-fact plus a recovery line.
+            if (!isWorkspaceTargetError(e) || !TARGET_ABSENT_CODES.has(e.code))
+                throw e;
+        }
+        if (mode === "user") {
+            const conn = await connectUserControlOrExit(withSpace);
+            return {
+                space: conn.space,
+                server: conn.server,
+                auth: { ...endpointAuth(conn), ...(conn.epCaller ? { epCaller: conn.epCaller } : {}) },
+            };
+        }
+    }
+    // Static / open / raw-creds: mint the requested instrument (or bare open connect).
     const conn = await connectOrExit(withSpace, profile);
-    return { space: conn.space, server: conn.server, auth: endpointAuth(conn) };
+    return {
+        space: conn.space,
+        server: conn.server,
+        auth: { ...endpointAuth(conn), ...(conn.epCaller ? { epCaller: conn.epCaller } : {}) },
+    };
+}
+/** v0.3 ctl op → v0.4 typed command (P2 item 1, 1c.2b): the wire names the manager REGISTERS
+ *  (manager-service-contract ROWS). `start` is creation (`spawn`), a NAMED `stop` is the one
+ *  owner/any-mode terminal (`despawn`), the per-agent `status` read is `inspect`; the camelCase
+ *  admin family maps to its kebab-case wire names. `targeted` marks the two commands whose
+ *  `{name}` argument becomes a §13.2 target block (resolved to the agent's principal triple via
+ *  the name-keyed `inspect` read — it rides the spawn capability arm, so resolution reach equals
+ *  despawn/attach reach; the wire target is (owner, actor, lifecycleUid), never an alias). */
+const EP_COMMANDS = {
+    start: { command: "spawn" },
+    stop: { command: "despawn", targeted: true },
+    attach: { command: "attach", targeted: true },
+    status: { command: "inspect" },
+    ps: { command: "ps" },
+    models: { command: "models" },
+    launch: { command: "launch" },
+    purge: { command: "purge" },
+    resumePreserved: { command: "resume-preserved" },
+    commitResume: { command: "commit-resume" },
+    finalizeResume: { command: "finalize-resume" },
+    preparePreservation: { command: "prepare-preservation" },
+    commitPreservation: { command: "commit-preservation" },
+    abortPreservation: { command: "abort-preservation" },
+};
+/** The ep-rail control call — since 1d {@link askManager}'s ONLY path: one short-lived raw
+ *  connection, a fresh `resolveService` (describe → §13.7 store fetch → digest-verified recompile
+ *  — the generic item-5 caller, no hand-imported manager schemas), then the mapped command.
+ *  Targeted ops resolve the alias to its CURRENT principal triple through the name-keyed
+ *  `inspect` read first and ride mode `any` (admin instruments) or `owner` per {@link
+ *  ControlReach}. */
+async function askManagerEp(space, server, op, args, auth, reach, timeoutMs, instanceId) {
+    const mapped = EP_COMMANDS[op];
+    if (!mapped)
+        return { ok: false, error: `unknown manager op "${op}" (no v0.4 command mapping)` };
+    const caller = auth.epCaller;
+    // standaloneConnectOpts handles all three auth shapes: static creds, the user bearer + sentinel
+    // (client-chosen inbox nonce; the callout scopes the reply inbox on it), or BARE on an open
+    // mesh (no credential system; the broker enforces nothing).
+    const nc = await connect({
+        servers: server,
+        ...standaloneConnectOpts(auth.creds ? { creds: auth.creds, tls: auth.tls === true } : auth.bearer ? { bearer: auth.bearer, sentinelCreds: auth.sentinelCreds, tls: auth.tls === true } : { tls: auth.tls === true }),
+        maxReconnectAttempts: 0,
+    });
+    try {
+        // P2 item 3 `--on <instance>`: pin the resolve to the exact manager instance's `inst` route so a
+        // multi-manager space addresses the intended manager, never whichever wins the class anycast.
+        const service = await resolveService(nc, space, BASELINE_LIFECYCLE_ENDPOINT, caller, { deadlineMs: 10_000, ...(instanceId !== undefined ? { instanceId } : {}) });
+        let target;
+        let sendArgs = args;
+        if (mapped.targeted) {
+            const name = String(args?.name ?? "").trim();
+            if (!name)
+                return { ok: false, error: `${op} requires a name` };
+            // Alias -> CURRENT principal triple via the manager's name-keyed `inspect` read (§13.2: a
+            // target is a triple, never an alias) - the same resolution the connector uses. `inspect`
+            // rides the SPAWN capability arm as well as the instrument read set, so every caller class
+            // that can despawn/attach can also resolve its target (a `ps` SCAN here broker-drops exactly
+            // the spawn-scoped user bearers - the 1c.2b read narrowing - and hangs their stop/attach).
+            const info = await invokeCommand(nc, space, service, "inspect", { name }, { deadlineMs: 10_000 });
+            if (info.reply.ok !== true)
+                return { ok: false, error: `could not resolve "${name}": ${info.reply.error?.message ?? info.reply.error?.code ?? "inspect failed"}` };
+            const row = info.reply.data;
+            // A STATIC row's `id` is the bare actor under the caller's own owner; a USER-mode row's `id`
+            // is the composite `owner.actor` principal key - split it (an embedded dot would break the
+            // target block's subject arity). Mode `any` spans owners (operator reach); mode `owner` pins
+            // the caller's own, so a foreign-owner target is broker-denied at publish.
+            const dot = row.id.indexOf(".");
+            const [tOwner, tActor] = dot > 0 ? [row.id.slice(0, dot), row.id.slice(dot + 1)] : [caller.owner, row.id];
+            // Target mode from the RESOLVED target owner: an own-domain target rides `owner` mode (pinned
+            // to the caller's own owner); a CROSS-owner target rides `any` mode - which the broker admits
+            // only for a caller holding the admin instrument rows (a static admin instrument, or a user
+            // bearer whose ledger `admin` scope the callout minted them into). `reach: "any"` forces
+            // any-mode for a static admin instrument even on its own domain. So a spawn-scoped caller's
+            // cross-owner despawn/attach is broker-denied at publish (no any-mode row), while an
+            // admin-scoped operator's is admitted and the manager's fresh ledger check governs.
+            const mode = reach === "any" || tOwner !== caller.owner ? "any" : "owner";
+            target = {
+                mode,
+                owner: tOwner,
+                actor: tActor,
+                lifecycleUid: row.lifecycleUid,
+            };
+            const { name: _dropped, ...rest } = args ?? {};
+            sendArgs = Object.keys(rest).length ? rest : undefined;
+        }
+        const invokeOpts = { ...(target ? { target } : {}), deadlineMs: timeoutMs ?? 10_000 };
+        const submit = () => invokeCommand(nc, space, service, mapped.command, sendArgs, invokeOpts);
+        // P2 item 2 (2b): a goal-bearing command (spawn/launch) FOLLOWS its acceptance to the goal
+        // terminal, so `spawn --detach` still returns on the real outcome (join / exit / ~30s uncertain)
+        // exactly like the pre-action blocking reply — UX unchanged, no --no-wait.
+        const r = GOAL_BEARING_COMMANDS.includes(mapped.command)
+            ? await submitAndFollowGoal(nc, space, BASELINE_LIFECYCLE_ENDPOINT, caller, timeoutMs ?? START_TIMEOUT_MS, submit)
+            : await submit();
+        if (r.reply.ok !== true)
+            return { ok: false, error: r.reply.error?.message ?? r.reply.error?.code ?? "error" };
+        // The ep `models` reply is normalized to `{catalogs}` — unwrap so call sites keep the ctl shape.
+        const data = mapped.command === "models" ? r.reply.data.catalogs : r.reply.data;
+        return { ok: true, ...(data !== undefined ? { data } : {}) };
+    }
+    catch (e) {
+        const msg = e instanceof EpEnvelopeError ? `${e.code}: ${e.message}` : e.message;
+        return { ok: false, error: `no manager reachable on the ep rails (${msg})` };
+    }
+    finally {
+        await nc.drain().catch(() => nc.close());
+    }
+}
+/** Send one control command to the manager over the v0.4 service-endpoint rails and disconnect —
+ *  since 1d the manager's ONLY control door (the `ctl` tiers are deleted). The target is already
+ *  reachability- + auth-preflighted by {@link resolveControlTarget}. `reach` picks the operator
+ *  mode for the two targeted ops (stop/attach): `owner` = the caller's own domain (the spawn
+ *  capability's standing mint / a user bearer's own owner), `any` = the admin instrument's
+ *  cross-agent reach. Three auth shapes reach the rails: a static instrument's caller triple, a
+ *  user bearer's triple, or an OPEN mesh (no credential system — a bare connection under a
+ *  synthesized DEV_OWNER triple, since the manager registered under DEV_OWNER and the broker
+ *  enforces nothing). A raw `--creds` file from an older generation carries no ep rows and is
+ *  refused loud (no silent ctl fallback exists anymore). */
+export async function askManager(space, server, op, args, auth = {}, reach = "owner", timeoutMs, instanceId) {
+    // A user bearer or a minted static instrument carries its own ep caller triple: ride it.
+    if (auth.epCaller && (auth.creds || (auth.bearer && auth.sentinelCreds)))
+        return askManagerEp(space, server, op, args, auth, reach, timeoutMs, instanceId);
+    // A raw `--creds` file with NO minted triple is a pre-1c generation's cred (no ep rows). The ctl
+    // rail it used to ride is gone (1d), so refuse loud with the recovery rather than hang.
+    if (auth.creds)
+        return { ok: false, error: `this --creds file predates the v0.4 control surface (no endpoint-serve rows); re-mint it with a current cotal, or drive the manager from its project folder (\`cotal ps\`/\`cotal stop\`) which mints the instrument for you` };
+    // OPEN mesh: no credential system. The manager registered its service under DEV_OWNER and the
+    // broker enforces nothing, so synthesize a fresh DEV_OWNER caller triple and connect bare.
+    const openAuth = { epCaller: { owner: DEV_OWNER, actor: newIdentity().id, uid: mintLifecycleUid() } };
+    return askManagerEp(space, server, op, args, openAuth, reach, timeoutMs, instanceId);
 }
-/** Connect a short-lived client with the resolved creds, send one control request to the manager,
- *  disconnect. The target is already reachability- + auth-preflighted by
- *  {@link resolveControlTarget}, so this connects straight through. `tier` picks the control
- *  subject: privileged for spawn --detach/ps — and, on a user mesh, for stop/attach too (the
- *  operator's bearer publishes there with scope "spawn"; the MANAGER authorizes owner-domain vs
- *  ledger-admin). On a static mesh stop/attach stay admin-tier ops. `creds` is the tier-scoped
- *  caller cred (`control-caller-privileged` / `control-caller-admin` — each holds ONLY its own
- *  tier's pub grant), or undefined on an open mesh. */
-export async function askManager(space, server, op, args, auth = {}, tier = CONTROL_PRIVILEGED, timeoutMs) {
-    const ep = new CotalEndpoint({
-        space,
+/** The ep-rail CLASS SCATTER (P2 item 3, `cotal ps` default): one short-lived connection, a fresh
+ *  UNPINNED {@link resolveService} (any instance answers `describe` for the shared command surface),
+ *  then {@link scatterCommand} — freeze the live class from the records registry, publish once on the
+ *  `all` rail, and gather one attributed reply per instance. Every frozen instance is accounted for:
+ *  a reachable one carries its reply, a non-answering one is labeled unreachable (never omitted). */
+async function askManagerScatterEp(space, server, op, auth, timeoutMs) {
+    const mapped = EP_COMMANDS[op];
+    if (!mapped)
+        return { ok: false, error: `unknown manager op "${op}" (no v0.4 command mapping)` };
+    if (mapped.targeted)
+        return { ok: false, error: `${op} is targeted and cannot be scattered across instances` };
+    const caller = auth.epCaller;
+    const nc = await connect({
         servers: server,
-        ...auth,
-        channels: [],
-        consume: false, // request/reply only — binds no consumers (and under auth has no pre-created DM durable)
-        registerPresence: false,
-        watchPresence: false,
-        card: { name: "cli", kind: "endpoint" },
+        ...standaloneConnectOpts(auth.creds ? { creds: auth.creds, tls: auth.tls === true } : auth.bearer ? { bearer: auth.bearer, sentinelCreds: auth.sentinelCreds, tls: auth.tls === true } : { tls: auth.tls === true }),
+        maxReconnectAttempts: 0,
     });
-    ep.on("error", (e) => console.error(c.red("! " + e.message)));
-    await ep.start();
     try {
-        return await ep.requestControl(tier, { op, args }, timeoutMs);
+        const service = await resolveService(nc, space, BASELINE_LIFECYCLE_ENDPOINT, caller, { deadlineMs: 10_000 });
+        const result = await scatterCommand(nc, space, service, mapped.command, undefined, {
+            deadlineMs: timeoutMs ?? 8_000,
+            reconcileDeadlineMs: 3_000,
+        });
+        const instances = [];
+        for (const [instanceId, ar] of result.replies) {
+            if (ar.reply.ok === true)
+                instances.push({ instanceId, reachable: true, data: ar.reply.data });
+            else
+                instances.push({ instanceId, reachable: true, error: ar.reply.error?.message ?? ar.reply.error?.code ?? "error" });
+        }
+        // A frozen instance that never answered is UNREACHABLE — surfaced, never silently dropped (pin 3).
+        for (const instanceId of result.missing)
+            instances.push({ instanceId, reachable: false });
+        return { ok: true, instances };
     }
     catch (e) {
-        // A user-mode caller whose cli actor lacks the tier's scope gets a broker publish denial (the
-        // red endpoint error above) and then this timeout — name the grant, not just the silence.
-        // The re-grant REPLACES the scope list, so the hint must say "add", never a bare one-token
-        // --scope that would silently strip the caller's spawn/role capabilities.
-        const need = tier === CONTROL_ADMIN ? "admin" : "spawn";
-        const scopeHint = auth.bearer
-            ? ` - on a user-auth mesh this op needs scope "${need}" on your cli actor. Re-grant with "${need}" ADDED to your current scope (the upsert replaces the list; see \`cotal actor list\`), e.g. \`cotal actor grant cli --sub <your IdP subject> --scope 'spawn,role:default,${need}'\``
-            : "";
-        return { ok: false, error: `no manager reachable (${e.message})${scopeHint}` };
+        const msg = e instanceof EpEnvelopeError ? `${e.code}: ${e.message}` : e.message;
+        return { ok: false, error: `no manager reachable on the ep rails (${msg})` };
     }
     finally {
-        await ep.stop();
+        await nc.drain().catch(() => nc.close());
     }
 }
+/** SCATTER one untargeted read (`ps`) across EVERY registered manager instance in the space and merge
+ *  the attributed results — the `cotal ps` default in a multi-manager space (P2 item 3). Auth shapes
+ *  match {@link askManager}: a minted instrument or user bearer rides its own caller triple; a raw
+ *  pre-1c `--creds` file is refused loud; an OPEN mesh synthesizes a DEV_OWNER triple and connects
+ *  bare (the broker enforces nothing, so the records freeze reads freely). */
+export async function scatterManager(space, server, op, auth = {}, timeoutMs) {
+    if (auth.epCaller && (auth.creds || (auth.bearer && auth.sentinelCreds)))
+        return askManagerScatterEp(space, server, op, auth, timeoutMs);
+    if (auth.creds)
+        return { ok: false, error: `this --creds file predates the v0.4 control surface (no endpoint-serve rows); re-mint it with a current cotal, or drive the manager from its project folder (\`cotal ps\`) which mints the instrument for you` };
+    const openAuth = { epCaller: { owner: DEV_OWNER, actor: newIdentity().id, uid: mintLifecycleUid() } };
+    return askManagerScatterEp(space, server, op, openAuth, timeoutMs);
+}
 export function failIfNotOk(reply) {
     if (!reply.ok) {
         const msg = reply.error ?? "error";

package/dist/lib/control.js.map

@@ -1 +1 @@
-{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"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"}

package/dist/lib/delivery-proc.d.ts

@@ -1,19 +1,34 @@
+import { type LivenessProbe } from "@cotal-ai/workspace";
+import { type SignalFn } from "./manager-proc.js";
+/** `tls` is the broker's transport decision, propagated to the daemon's argv. It is not optional
+ *  information the daemon can do without: it cannot derive the transport itself (see the note at
+ *  the argv site), and omitting it leaves a standing-credential daemon connecting
+ *  plaintext-capable to a TLS broker while looking entirely healthy.
+ *  `wsPort` is the broker's loopback websocket listener (P2 item 6), forwarded to the manager. */
 type Opts = {
     space?: string;
     server?: string;
+    tls?: boolean;
     spawn?: string[];
     runtime?: string;
     launch?: string;
     attachHost?: string;
     resumeAttempt?: string;
     resumeCommitToken?: string;
+    wsPort?: number;
 };
-/** True if the delivery daemon we started for this folder is still running (pid file + liveness). */
+/** The recorded daemon's liveness, THREE-VALUED plus absent. See {@link managerLiveness} for why the
+ *  boolean collapse is the defect: `unknown` is reachable on a real kernel (a seccomp
+ *  `SECCOMP_RET_ERRNO` filter or an LSM policy answers `kill(pid, 0)` with an arbitrary errno and
+ *  libuv preserves it), and both ways of folding it into a boolean fail silently. */
+export declare function deliveryLiveness(probe?: LivenessProbe): "alive" | "dead" | "unknown" | "absent" | "unattributable";
+/** True only if the daemon is PROVABLY running. Callers that ACT on the answer take
+ *  {@link deliveryLiveness} instead; this cannot express "cannot tell". */
 export declare function deliveryUp(): boolean;
 /** Cutover preflight — the FIRST action, BEFORE the daemon can bind: stop any old Plane-3-hosting
  *  manager (live `manager.pid` without the delivery-aware marker) so it never double-binds the
  *  daemon's durables. A delivery-aware (this-build) manager is left running. No-op on a fresh install. */
-export declare function stopOldHostingManagerIfPresent(): void;
+export declare function stopOldHostingManagerIfPresent(probe?: LivenessProbe, signal?: SignalFn): Promise<void>;
 /** Start the delivery daemon detached (pid in `.cotal/delivery.pid`, output to `.cotal/delivery.log`),
  *  stopped by `cotal down`. Re-execs this CLI's `deliver` command; the daemon loads the pre-minted
  *  scoped `delivery.creds` (written by {@link ensureDelivery}) — it never sees the signer. */
@@ -23,14 +38,14 @@ export declare function startDeliveryDetached(o?: Opts): number;
  *  never double-binds. Mints a SCOPED `delivery` cred from the local signer ONCE, writes it to
  *  `.cotal/delivery.creds` (0600), and launches the daemon WITHOUT signer access. Best-effort — callers
  *  treat it as non-fatal (a missing daemon degrades durable delivery, never live). */
-export declare function ensureDelivery(o?: Opts): Promise<{
+export declare function ensureDelivery(o?: Opts, probe?: LivenessProbe): Promise<{
     running: boolean;
 }>;
 /** Stop the detached delivery daemon if we started one, and drop its creds from the store. The pid
  *  kill runs even if the creds delete fails (finally) — a delete error must never leave the daemon
  *  alive to outlive the teardown and reattach to a restarted broker; the error still propagates
  *  after the kill so the caller can surface it. */
-export declare function stopDelivery(): Promise<void>;
+export declare function stopDelivery(probe?: LivenessProbe, signal?: SignalFn): Promise<void>;
 /** Bring up the control plane in the correct cutover order: OLD-manager preflight → delivery daemon
  *  (auth only, fails closed on a live old manager) → manager (lifecycle, writes the delivery-aware
  *  marker). The manager no longer depends on the daemon (it hosts no Plane-3), so the daemon is started

package/dist/lib/delivery-proc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delivery-proc.d.ts","sourceRoot":"","sources":["../../src/lib/delivery-proc.ts"],"names":[],"mappings":"AAmBA,KAAK,IAAI,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAW9K,qGAAqG;AACrG,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AAeD;;0GAE0G;AAC1G,wBAAgB,8BAA8B,IAAI,IAAI,CAKrD;AAED;;8FAE8F;AAC9F,wBAAgB,qBAAqB,CAAC,CAAC,GAAE,IAAS,GAAG,MAAM,CAkB1D;AAED;;;;sFAIsF;AACtF,wBAAsB,cAAc,CAAC,CAAC,GAAE,IAAS,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA+BhF;AAED;;;mDAGmD;AACnD,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBlD;AAED;;;;+FAI+F;AAC/F,wBAAsB,kBAAkB,CAAC,CAAC,GAAE,IAAS,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAIpF"}
+{"version":3,"file":"delivery-proc.d.ts","sourceRoot":"","sources":["../../src/lib/delivery-proc.ts"],"names":[],"mappings":"AAQA,OAAO,EAA4G,KAAK,aAAa,EAAwB,MAAM,qBAAqB,CAAC;AAIzL,OAAO,EAA2F,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAO3I;;;;kGAIkG;AAClG,KAAK,IAAI,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9M;;;qFAGqF;AACrF,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,aAA6B,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,gBAAgB,CAQjI;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AA6BD;;0GAE0G;AAC1G,wBAAsB,8BAA8B,CAAC,KAAK,GAAE,aAA6B,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB3H;AAED;;8FAE8F;AAC9F,wBAAgB,qBAAqB,CAAC,CAAC,GAAE,IAAS,GAAG,MAAM,CA2B1D;AAED;;;;sFAIsF;AACtF,wBAAsB,cAAc,CAAC,CAAC,GAAE,IAAS,EAAE,KAAK,GAAE,aAA6B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAyCtH;AAED;;;mDAGmD;AACnD,wBAAsB,YAAY,CAAC,KAAK,GAAE,aAA6B,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEzG;AAED;;;;+FAI+F;AAC/F,wBAAsB,kBAAkB,CAAC,CAAC,GAAE,IAAS,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAIpF"}