@cotal-ai/cli 0.9.0 → 0.10.0

package/dist/lib/attach-client.js

@@ -0,0 +1,218 @@
+import WebSocket from "ws";
+import { c } from "../ui.js";
+/**
+ * The detach key — Ctrl-] (0x1d) by default, as in telnet/ssh escape conventions. `COTAL_DETACH_KEY`
+ * rebinds it to another control key when Ctrl-] clashes with a keybinding inside the agent's TUI;
+ * accepts `ctrl-<char>` or `^<char>` (e.g. `ctrl-b`, `^_`). Read at point of use, per the repo's
+ * `COTAL_*` convention. An unparseable value — including a set-but-empty or whitespace-only one —
+ * throws (named), never silently falling back; the caller turns that into a loud exit. Only an
+ * unset var = the Ctrl-] default.
+ */
+export function detachKey() {
+    const spec = process.env.COTAL_DETACH_KEY;
+    if (spec === undefined)
+        return { byte: 0x1d, label: "Ctrl-]", overridden: false };
+    const m = /^(?:ctrl-|\^)([a-z@[\\\]^_])$/i.exec(spec.trim());
+    if (!m) {
+        throw new Error(`invalid COTAL_DETACH_KEY "${spec}" — expected ctrl-<char> or ^<char> for a control key ` +
+            `(a-z, or one of @ [ \\ ] ^ _), e.g. ctrl-b`);
+    }
+    const ch = m[1].toUpperCase();
+    return { byte: ch.charCodeAt(0) & 0x1f, label: `Ctrl-${ch}`, overridden: true };
+}
+/**
+ * Terminal modes a full-screen child (a fullscreen TUI: OpenCode, or Claude under `/tui fullscreen`)
+ * commonly turns on but that we must undo locally on detach/exit: the agent keeps running after
+ * Ctrl-], so it never restores OUR terminal. Without this, detaching from a mouse-tracking TUI leaves
+ * the terminal reporting every cursor move as input (a stream of `ESC[<…M` escape codes), or its
+ * focus in/out as `ESC[I`/`ESC[O`. Disables all mouse-report modes + focus reporting + bracketed
+ * paste, resets the keypad/cursor-key modes, shows the cursor, and resets attributes. Leaving the
+ * alternate screen is handled separately (ALT_LEAVE_SEQ), only when we actually entered it — see
+ * cleanup().
+ */
+const MOUSE_OFF = "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l"; // all mouse tracking off
+const RESTORE = MOUSE_OFF +
+    "\x1b[?1004l" + // focus reporting off
+    "\x1b[?2004l" + // bracketed paste off
+    "\x1b[?1l" + // application cursor keys off (DECCKM): a full-screen TUI enables it; left on, arrows emit ESC O A not ESC [ A
+    "\x1b>" + // keypad → numeric (DECKPNM)
+    "\x1b[?25h" + // show cursor
+    "\x1b[0m"; // reset attributes
+// Leave the alternate screen on detach, but ONLY if the child put us there (altScreen). The attach
+// snapshot faithfully re-enters the child's alt-screen (`?1049h`) on our terminal; without a matching
+// leave we strand it in the alt buffer, which has no scrollback and — with xterm alt-scroll — turns
+// the wheel into ↑/↓ that walk shell history. Leaving the alt buffer IS the whole fix: alt-scroll
+// (`?1007`) only acts inside the alt buffer, so `?1049l` alone makes it inert. We deliberately don't
+// send `?1007l` — nothing on this path ever enabled it (unlike console.ts, which sets `?1007h` on
+// entry), so disabling it would clobber the operator's own alternate-scroll preference for later apps.
+const ALT_LEAVE_SEQ = "\x1b[?1049l"; // leave alt-screen — alt-scroll is inert once back in the main buffer
+// Wheel-scroll for full-screen children. A fullscreen TUI (OpenCode, or Claude under `/tui
+// fullscreen`) runs in the alternate screen — where the terminal's native scrollback is dead — and
+// scrolls its content itself off mouse reports. But it enables that mouse capture on ITS pty, and the
+// enable doesn't reliably survive the attach hop (backlog eviction / nested pty), so our terminal
+// never reports the wheel and scrolling dies. So while the child is in the alternate screen we enable
+// SGR mouse reporting on OUR terminal and translate each wheel tick into PageUp/PageDown — the
+// keystrokes a fullscreen TUI treats as "scroll the view" (OpenCode: `messages_page_up`/`_down`;
+// Claude's fullscreen binds PageUp/PageDown too). A child in the normal screen (inline Claude) keeps
+// altScreen=false, so this stays off and its native terminal-scrollback wheel is untouched.
+const MOUSE_ON = "\x1b[?1002h\x1b[?1006h"; // button+drag tracking, SGR encoding
+const PAGE_UP = "\x1b[5~";
+const PAGE_DOWN = "\x1b[6~";
+// Enter/leave the alternate screen: xterm `?1049`, plus the older `?1047`/`?47`.
+const ALT_ENTER = /\x1b\[\?(?:1049|1047|47)h/g;
+const ALT_LEAVE = /\x1b\[\?(?:1049|1047|47)l/g;
+// A complete SGR mouse report: `ESC [ < btn ; col ; row (M|m)`.
+const SGR_MOUSE = /^\x1b\[<(\d+);\d+;\d+[Mm]/;
+const lastIndexOfRe = (re, s) => {
+    re.lastIndex = 0;
+    let last = -1;
+    for (let m = re.exec(s); m; m = re.exec(s))
+        last = m.index;
+    return last;
+};
+/**
+ * Drive a manager's attach endpoint from the terminal: raw-mode stdin streams to
+ * the PTY, PTY output streams to stdout, and SIGWINCH-style resizes are forwarded.
+ * The detach key (Ctrl-] by default, {@link detachKey}) detaches without killing the agent.
+ */
+export function attachClient(url) {
+    // Resolve the detach key before connecting so a bad COTAL_DETACH_KEY fails loudly up front
+    // (matching the manager's other fail-fast exits) instead of after an attach we'd only tear down.
+    let detach;
+    try {
+        detach = detachKey();
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e.message}`));
+        process.exit(1);
+    }
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw ?? false;
+        // A broken local pipe (terminal closed / SIGHUP) makes stdout writes async-error on a later
+        // tick; with no listener that EPIPE/EIO becomes an uncaughtException — crashing on the per-frame
+        // PTY write or the on-detach restore write. Register a no-op listener once here (not in cleanup,
+        // so it outlives the async error tick) to turn it into a handled no-op.
+        process.stdout.on("error", () => { });
+        // Wheel-scroll state (see MOUSE_ON above): whether the child is in the alternate screen, and a
+        // buffer for an SGR mouse report split across stdin reads.
+        let altScreen = false;
+        let mouseBuf = "";
+        // Carry the tail of the previous output frame so an alt-screen escape split across ws frames
+        // (e.g. `ESC[?10` then `49h`) is still detected; 16 bytes covers these private-mode sequences.
+        // Acting only on state *change* below makes re-scanning the carried bytes idempotent.
+        let scanTail = "";
+        // Track the child's alt-screen transitions in its output so we can arm/disarm wheel translation.
+        const trackAltScreen = (data) => {
+            const s = scanTail + data.toString("latin1");
+            scanTail = s.slice(-16);
+            const enter = lastIndexOfRe(ALT_ENTER, s);
+            const leave = lastIndexOfRe(ALT_LEAVE, s);
+            if (enter === -1 && leave === -1)
+                return;
+            const nowAlt = enter > leave;
+            if (nowAlt === altScreen)
+                return;
+            altScreen = nowAlt;
+            if (altScreen) {
+                if (process.stdout.isTTY)
+                    process.stdout.write(MOUSE_ON);
+            }
+            else {
+                // Leaving alt-screen mid-session: undo the mouse modes WE enabled so the terminal stops
+                // reporting the wheel/clicks and native scrollback works again — don't wait for detach.
+                mouseBuf = "";
+                if (process.stdout.isTTY)
+                    process.stdout.write(MOUSE_OFF);
+            }
+        };
+        const sendResize = () => ws.send(`r:${process.stdout.columns ?? 80},${process.stdout.rows ?? 24}`);
+        const onInput = (d) => {
+            if (d.length === 1 && d[0] === detach.byte) {
+                ws.close();
+                return;
+            }
+            // Inline child: forward keystrokes raw (its wheel scrolls the local terminal, not the app).
+            if (!altScreen) {
+                ws.send(d);
+                return;
+            }
+            // Full-screen child: rewrite wheel reports to PageUp/PageDown, pass everything else through.
+            mouseBuf += d.toString("latin1");
+            let out = "";
+            for (;;) {
+                const i = mouseBuf.indexOf("\x1b[<");
+                if (i === -1) {
+                    // A report split right before `<` (`ESC[` now, `<…M` next) would slip through untranslated:
+                    // hold a trailing `ESC[` for the next read. Never hold a bare trailing `ESC` — that's the
+                    // Escape key and must forward at once (e.g. OpenCode's interrupt); the rarer `ESC`|`[<…`
+                    // split stays raw by design.
+                    const keep = mouseBuf.endsWith("\x1b[") ? 2 : 0;
+                    out += mouseBuf.slice(0, mouseBuf.length - keep);
+                    mouseBuf = mouseBuf.slice(mouseBuf.length - keep);
+                    break;
+                }
+                out += mouseBuf.slice(0, i);
+                const rest = mouseBuf.slice(i);
+                const m = SGR_MOUSE.exec(rest);
+                if (!m) {
+                    // Hold only a still-valid partial report (`ESC[<` + digits/semicolons) for the next read;
+                    // anything else can't become an SGR mouse report, so pass it straight through.
+                    if (/^\x1b\[<[\d;]*$/.test(rest))
+                        mouseBuf = rest;
+                    else {
+                        out += rest;
+                        mouseBuf = "";
+                    }
+                    break;
+                }
+                const btn = Number(m[1]);
+                if (btn & 0x40)
+                    out += btn & 1 ? PAGE_DOWN : PAGE_UP; // wheel: 64=up, 65=down
+                else
+                    out += m[0]; // other mouse (click/drag): forward raw so the TUI still gets it
+                mouseBuf = rest.slice(m[0].length);
+            }
+            if (out)
+                ws.send(Buffer.from(out, "latin1"));
+        };
+        const cleanup = () => {
+            stdin.off("data", onInput);
+            process.stdout.off("resize", sendResize);
+            // Undo terminal modes the (still-running) agent's TUI enabled — it won't restore us on detach.
+            // If the child put us in its alternate screen (altScreen), leave it too so the terminal isn't
+            // stranded in the alt buffer; an inline child (altScreen=false) keeps its scrollback.
+            if (process.stdout.isTTY)
+                process.stdout.write(RESTORE + (altScreen ? ALT_LEAVE_SEQ : ""));
+            if (stdin.isTTY)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        ws.on("open", () => {
+            // Make an override visible (the CLI's "attached to X — Ctrl-] to detach" hint still prints the
+            // default label). Only on override, so the default case stays free of duplicate noise.
+            if (detach.overridden)
+                console.error(c.dim(`detach key: ${detach.label} (via COTAL_DETACH_KEY)`));
+            if (stdin.isTTY)
+                stdin.setRawMode(true);
+            stdin.resume();
+            sendResize();
+            process.stdout.on("resize", sendResize);
+            stdin.on("data", onInput);
+        });
+        ws.on("message", (data) => {
+            trackAltScreen(data);
+            process.stdout.write(data);
+        });
+        ws.on("close", () => {
+            cleanup();
+            resolve();
+        });
+        ws.on("error", (e) => {
+            cleanup();
+            reject(e);
+        });
+    });
+}
+//# sourceMappingURL=attach-client.js.map

package/dist/lib/attach-client.js.map

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

package/dist/lib/completion.d.ts

@@ -0,0 +1,8 @@
+import type { FlagSpec } from "@cotal-ai/core";
+/** The string flag whose value is currently being completed, if the cursor is in one. */
+export declare function completingFlagValue(argv: string[], flags: readonly FlagSpec[]): FlagSpec | undefined;
+/** Strip declared flags and their values, leaving the positional cursor shape for sub-grammars. */
+export declare function positionalsForCompletion(argv: string[], flags: readonly FlagSpec[]): string[];
+export declare function hasCompletedFlagValue(argv: string[], flags: readonly FlagSpec[], name: string): boolean;
+export declare function completedFlagValue(argv: string[], flags: readonly FlagSpec[], name: string): string | undefined;
+//# sourceMappingURL=completion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/lib/completion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,GAAG,SAAS,CAKpG;AAED,mGAAmG;AACnG,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,EAAE,CAqB7F;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvG;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAe/G"}

package/dist/lib/completion.js

@@ -0,0 +1,66 @@
+/** The string flag whose value is currently being completed, if the cursor is in one. */
+export function completingFlagValue(argv, flags) {
+    const prev = argv[argv.length - 2];
+    if (!prev)
+        return undefined;
+    const flag = flagForToken(prev, flags);
+    return flag?.type === "string" ? flag : undefined;
+}
+/** Strip declared flags and their values, leaving the positional cursor shape for sub-grammars. */
+export function positionalsForCompletion(argv, flags) {
+    const out = [];
+    let positionalOnly = false;
+    for (let i = 0; i < argv.length; i++) {
+        const word = argv[i];
+        if (!positionalOnly && word === "--") {
+            positionalOnly = true;
+            continue;
+        }
+        if (!positionalOnly) {
+            const inline = /^--([^=]+)=/.exec(word);
+            if (inline && flagForLong(inline[1], flags))
+                continue;
+            const flag = flagForToken(word, flags);
+            if (flag) {
+                if (flag.type === "string" && i + 1 < argv.length)
+                    i++;
+                continue;
+            }
+        }
+        out.push(word);
+    }
+    return out;
+}
+export function hasCompletedFlagValue(argv, flags, name) {
+    return completedFlagValue(argv, flags, name) !== undefined;
+}
+export function completedFlagValue(argv, flags, name) {
+    for (let i = 0; i < argv.length; i++) {
+        const word = argv[i];
+        const inline = /^--([^=]+)=(.*)$/.exec(word);
+        if (inline) {
+            const flag = flagForLong(inline[1], flags);
+            if (flag?.name === name && inline[2] !== "")
+                return inline[2];
+            continue;
+        }
+        const flag = flagForToken(word, flags);
+        if (flag?.name !== name || flag.type !== "string")
+            continue;
+        const value = argv[i + 1];
+        if (value !== undefined && value !== "" && i + 1 < argv.length - 1)
+            return value;
+    }
+    return undefined;
+}
+function flagForToken(token, flags) {
+    if (token.startsWith("--"))
+        return flagForLong(token.slice(2), flags);
+    if (/^-[^-]$/.test(token))
+        return flags.find((f) => f.short === token.slice(1));
+    return undefined;
+}
+function flagForLong(name, flags) {
+    return flags.find((f) => f.name === name);
+}
+//# sourceMappingURL=completion.js.map

package/dist/lib/completion.js.map

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

package/dist/lib/connect.d.ts

@@ -1,74 +1,2 @@
-import { type Profile, type SpaceAuth } from "@cotal-ai/core";
-import { type MeshTarget } from "@cotal-ai/workspace";
-export { classifyPreflightFailure, type PreflightFailure } from "@cotal-ai/workspace";
-/**
- * The one way every command that touches a running mesh figures out WHICH mesh + with what creds,
- * and confirms it's actually up — so `spawn`, `send`/`dm`/`msg`/`ask`, `console`, `join`, `web`,
- * `channels`, `history`, and `personas --running` all behave identically from any directory instead
- * of each re-deriving it from a cwd walk-up (which mistook `$HOME/.cotal` for a space and crashed
- * with a raw NATS auth violation). Two escape hatches take a RAW off-registry connection (no
- * registry lookup, no stale-prune): explicit `--creds`, and `--server` + an unregistered `--space`
- * (an open remote mesh that has no creds to pass).
- */
-export interface ConnectFlags {
-    server?: string;
-    space?: string;
-    /** Explicit creds file — triggers a raw off-registry connection (see {@link connectOrExit}). */
-    creds?: string;
-}
-/** Raw NATS auth for an off-registry connection — a join link / --token / --user+--pass / --creds.
- *  Structurally matches what `probeConnect` accepts. */
-export interface RawAuth {
-    token?: string;
-    user?: string;
-    pass?: string;
-    creds?: string;
-    tls?: boolean;
-}
-export interface Connection {
-    server: string;
-    space: string;
-    creds?: string;
-    /** The mesh's trust material when resolved from the registry on an auth mesh — undefined for an
-     *  open mesh or a raw off-registry connection (`--creds` or `--server`+unregistered `--space`).
-     *  (web keeps it for its per-delete manager mint.) */
-    auth?: SpaceAuth;
-    /** The resolved mesh's recorded checkout root, for a REGISTERED mesh — undefined for a raw
-     *  off-registry connection (`--creds`, or `--server`+unregistered `--space`). `spawn -f`/`down -f`
-     *  use it to enforce the same-checkout invariant: local launch artifacts + the ledger live under
-     *  this checkout, so deploying onto a mesh recorded by another checkout would decouple them. */
-    root?: string;
-    /** How the target was resolved (registry / current / flag-space / …) — undefined for raw. */
-    source?: MeshTarget["source"];
-}
-/**
- * Resolve where a mesh-touching command connects + with what creds.
- *  • Explicit `--creds` → a RAW off-registry connection: straight to `--server` (default loopback)
- *    as `--space`, with those creds. No registry lookup, no stale-prune, plain reachability message
- *    (the user is deliberately off-registry — e.g. a remote mesh that isn't locally recorded).
- *  • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
- *    on an auth mesh, and preflight with the registry's stale-prune.
- */
-export declare function connectOrExit(flags: ConnectFlags, role: Profile): Promise<Connection>;
-/** Reachability check for a RAW (off-registry) connection — one plain sentence, never a registry/
- *  stale-entry message and never a prune. Used by the `--creds` escape hatch and `join`'s explicit
- *  (link/token/creds) path, both of which connect to a broker the user named, not the registry. */
-export declare function reachableOrExit(server: string, auth?: RawAuth): Promise<void>;
-/** Resolve the mesh a command targets, exiting with one human sentence on an unresolved/ambiguous
- *  registry rather than a stack trace. Prunes dead registry entries first so a crashed mesh doesn't
- *  block a bare command or appear in the "pick one" list — but ONLY when resolving without an
- *  explicit `--space`. A named `--space` is resolved + preflighted directly, so pre-pruning can't
- *  erase a dead-recorded mesh the operator is recovering with a live `--server` override; preflight
- *  still prunes it (with the friendly message) when no override revives it. */
-export declare function resolveTargetOrExit(flags: {
-    server?: string;
-    space?: string;
-}): Promise<MeshTarget>;
-/** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
- *  Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
- *  The probe + classify + render live in `@cotal-ai/workspace` (shared with the manager control
- *  commands); this wrapper owns the CLI's I/O — it acts on the prune decision, colours, and exits.
- *  Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise workspace mints
- *  a throwaway identity from the target's own trust material. */
-export declare function preflightOrExit(target: MeshTarget, probeCreds?: string): Promise<void>;
+export { connectOrExit, reachableOrExit, resolveTargetOrExit, preflightOrExit, classifyPreflightFailure, type ConnectFlags, type Connection, type RawAuth, type PreflightFailure, } from "@cotal-ai/workspace";
 //# sourceMappingURL=connect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/lib/connect.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EASL,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,EAAE,wBAAwB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEtF;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;wDACwD;AACxD,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;0DAEsD;IACtD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;oGAGgG;IAChG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAoB3F;AAED;;mGAEmG;AACnG,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;AAED;;;;;+EAK+E;AAC/E,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBtB;AAED;;;;;iEAKiE;AACjE,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/lib/connect.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC"}

package/dist/lib/connect.js

@@ -1,91 +1,5 @@
-import { readFileSync } from "node:fs";
-import { DEFAULT_SERVER, DEFAULT_SPACE, mintCreds, newIdentity, probeConnect, } from "@cotal-ai/core";
-import { findMesh, getCurrent, isWorkspaceTargetError, preflightTarget, pruneStaleMeshes, removeMesh, renderWorkspaceError, resolveMeshTarget, } from "@cotal-ai/workspace";
-import { c } from "../ui.js";
-// The workstation mechanics (target resolution, probe → classify → command-copy renderer +
-// stale-prune) live in `@cotal-ai/workspace`, shared with the manager control commands. Re-exported
-// here so existing importers — and `connect.smoke.ts` — keep resolving them from this module unchanged.
-export { classifyPreflightFailure } from "@cotal-ai/workspace";
-/**
- * Resolve where a mesh-touching command connects + with what creds.
- *  • Explicit `--creds` → a RAW off-registry connection: straight to `--server` (default loopback)
- *    as `--space`, with those creds. No registry lookup, no stale-prune, plain reachability message
- *    (the user is deliberately off-registry — e.g. a remote mesh that isn't locally recorded).
- *  • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
- *    on an auth mesh, and preflight with the registry's stale-prune.
- */
-export async function connectOrExit(flags, role) {
-    if (flags.creds) {
-        const server = flags.server ?? DEFAULT_SERVER;
-        const space = flags.space ?? DEFAULT_SPACE;
-        const creds = readFileSync(flags.creds, "utf8");
-        await reachableOrExit(server, { creds });
-        return { server, space, creds };
-    }
-    // A raw OPEN remote mesh: explicit `--server` + a `--space` that isn't locally registered. Naming
-    // both is as deliberate as `--creds`, but an open broker has no creds to pass — connect bare,
-    // off-registry (no registry lookup, no prune). A registered `--space` still goes through the
-    // resolver below (which honors `--server` as an override); `--server` alone resolves there too.
-    if (flags.server && flags.space && !findMesh(flags.space)) {
-        await reachableOrExit(flags.server, {});
-        return { server: flags.server, space: flags.space };
-    }
-    const target = await resolveTargetOrExit({ server: flags.server, space: flags.space });
-    const creds = target.auth ? await mintCreds(target.auth, newIdentity(), role) : undefined;
-    await preflightOrExit(target, creds);
-    return { server: target.server, space: target.space, creds, auth: target.auth, root: target.root, source: target.source };
-}
-/** Reachability check for a RAW (off-registry) connection — one plain sentence, never a registry/
- *  stale-entry message and never a prune. Used by the `--creds` escape hatch and `join`'s explicit
- *  (link/token/creds) path, both of which connect to a broker the user named, not the registry. */
-export async function reachableOrExit(server, auth = {}) {
-    const probe = await probeConnect(server, auth);
-    if (probe.ok)
-        return;
-    console.error(c.red(renderWorkspaceError({ kind: "reachable", reason: probe.reason, server })));
-    process.exit(1);
-}
-/** Resolve the mesh a command targets, exiting with one human sentence on an unresolved/ambiguous
- *  registry rather than a stack trace. Prunes dead registry entries first so a crashed mesh doesn't
- *  block a bare command or appear in the "pick one" list — but ONLY when resolving without an
- *  explicit `--space`. A named `--space` is resolved + preflighted directly, so pre-pruning can't
- *  erase a dead-recorded mesh the operator is recovering with a live `--server` override; preflight
- *  still prunes it (with the friendly message) when no override revives it. */
-export async function resolveTargetOrExit(flags) {
-    if (!flags.space)
-        await pruneStaleMeshes();
-    let target;
-    try {
-        target = resolveMeshTarget(process.cwd(), flags);
-    }
-    catch (e) {
-        if (isWorkspaceTargetError(e)) {
-            console.error(c.red(renderWorkspaceError({ kind: "target", error: e })));
-            process.exit(1);
-        }
-        throw e;
-    }
-    // If a dangling `current` was silently bypassed — it named a mesh that's since gone and we fell
-    // back to the only live one — say so. The N>1 case errors loudly; this is the one spot that would
-    // otherwise quietly redirect a stale default.
-    const cur = getCurrent();
-    if (cur && !findMesh(cur) && target.source === "registry")
-        console.error(c.dim(`note: default mesh "${cur}" is down — using "${target.space}"`));
-    return target;
-}
-/** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
- *  Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
- *  The probe + classify + render live in `@cotal-ai/workspace` (shared with the manager control
- *  commands); this wrapper owns the CLI's I/O — it acts on the prune decision, colours, and exits.
- *  Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise workspace mints
- *  a throwaway identity from the target's own trust material. */
-export async function preflightOrExit(target, probeCreds) {
-    const r = await preflightTarget(target, probeCreds);
-    if (r.ok)
-        return;
-    if (r.prune)
-        removeMesh(target.space);
-    console.error(c.red(renderWorkspaceError({ kind: "preflight", failure: r.kind, target, pruned: r.prune })));
-    process.exit(1);
-}
+// The connect-or-exit wrappers moved into `@cotal-ai/workspace` (stage 4) so every command
+// surface — this CLI and cotal-web — resolves meshes identically. Re-exported here
+// so existing importers (and `connect.smoke.ts`) keep resolving them from this module unchanged.
+export { connectOrExit, reachableOrExit, resolveTargetOrExit, preflightOrExit, classifyPreflightFailure, } from "@cotal-ai/workspace";
 //# sourceMappingURL=connect.js.map

package/dist/lib/connect.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/lib/connect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/lib/connect.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,mFAAmF;AACnF,iGAAiG;AACjG,OAAO,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,wBAAwB,GAKzB,MAAM,qBAAqB,CAAC"}

package/dist/lib/control.d.ts

@@ -0,0 +1,34 @@
+import { type ControlReply, type ControlTier, type Profile } from "@cotal-ai/core";
+import { type ConnectFlags } from "./connect.js";
+/** 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 —
+ *  so these requests must OUTLIVE that window, not the 5s op default. The tier rule forbids
+ *  importing the manager's READINESS_TIMEOUT_MS here; the launch-parity smoke enforces the
+ *  relation by test. */
+export declare const START_TIMEOUT_MS = 40000;
+/**
+ * Resolve which running mesh a control command (`spawn --detach` / `stop` / `ps` / `attach`)
+ * targets. Exactly {@link connectOrExit}'s precedence (--creds raw > --server+unregistered-space
+ * open > registry/`current` with mint + preflight + stale-prune) with ONE control-specific delta:
+ * on the raw `--creds` path the space defaults to THIS FOLDER's `.cotal/auth` space, not
+ * `DEFAULT_SPACE` — a control op addresses the manager of the folder's mesh, which is more
+ * correct for a non-default-space project (deliberate, kept from the pre-move manager client).
+ * Lived in `@cotal-ai/manager` before stage 2a moved the control clients into the CLI; the
+ * duplicated resolution/preflight wrappers collapsed onto `lib/connect.ts`.
+ */
+export declare function resolveControlTarget(flags: ConnectFlags, profile: Profile): Promise<{
+    space: string;
+    server: string;
+    creds?: string;
+}>;
+/** 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; admin for the operator's cross-agent ops
+ *  (stop/attach), which the manager refuses on the privileged subject for a non-owner. `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 declare function askManager(space: string, server: string, op: string, args?: Record<string, unknown>, creds?: string, tier?: ControlTier, timeoutMs?: number): Promise<ControlReply>;
+export declare function failIfNotOk(reply: ControlReply): void;
+//# sourceMappingURL=control.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACb,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;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,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAM5D;AAED;;;;;;oEAMoE;AACpE,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,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,GAAE,WAAgC,EACtC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAoBvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAKrD"}

package/dist/lib/control.js

@@ -0,0 +1,65 @@
+import { CotalEndpoint, DEFAULT_SPACE, CONTROL_PRIVILEGED, } from "@cotal-ai/core";
+import { authDir, findCotalRoot, loadSpaceAuth } from "@cotal-ai/workspace";
+import { c } from "../ui.js";
+import { connectOrExit } from "./connect.js";
+/** 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 —
+ *  so these requests must OUTLIVE that window, not the 5s op default. The tier rule forbids
+ *  importing the manager's READINESS_TIMEOUT_MS here; the launch-parity smoke enforces the
+ *  relation by test. */
+export const START_TIMEOUT_MS = 40_000;
+/**
+ * Resolve which running mesh a control command (`spawn --detach` / `stop` / `ps` / `attach`)
+ * targets. Exactly {@link connectOrExit}'s precedence (--creds raw > --server+unregistered-space
+ * open > registry/`current` with mint + preflight + stale-prune) with ONE control-specific delta:
+ * on the raw `--creds` path the space defaults to THIS FOLDER's `.cotal/auth` space, not
+ * `DEFAULT_SPACE` — a control op addresses the manager of the folder's mesh, which is more
+ * correct for a non-default-space project (deliberate, kept from the pre-move manager client).
+ * Lived in `@cotal-ai/manager` before stage 2a moved the control clients into the CLI; the
+ * duplicated resolution/preflight wrappers collapsed onto `lib/connect.ts`.
+ */
+export async function resolveControlTarget(flags, profile) {
+    const withSpace = flags.creds
+        ? { ...flags, space: flags.space ?? loadSpaceAuth(authDir(findCotalRoot()))?.space ?? DEFAULT_SPACE }
+        : flags;
+    const { space, server, creds } = await connectOrExit(withSpace, profile);
+    return { space, server, creds };
+}
+/** 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; admin for the operator's cross-agent ops
+ *  (stop/attach), which the manager refuses on the privileged subject for a non-owner. `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, creds, tier = CONTROL_PRIVILEGED, timeoutMs) {
+    const ep = new CotalEndpoint({
+        space,
+        servers: server,
+        creds,
+        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" },
+    });
+    ep.on("error", (e) => console.error(c.red("! " + e.message)));
+    await ep.start();
+    try {
+        return await ep.requestControl(tier, { op, args }, timeoutMs);
+    }
+    catch (e) {
+        return { ok: false, error: `no manager reachable (${e.message})` };
+    }
+    finally {
+        await ep.stop();
+    }
+}
+export function failIfNotOk(reply) {
+    if (!reply.ok) {
+        console.error(c.red(`✗ ${reply.error ?? "error"}`));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/lib/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/lib/control.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,kBAAkB,GAInB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAqB,MAAM,cAAc,CAAC;AAEhE;;;;;wBAKwB;AACxB,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAmB,EACnB,OAAgB;IAEhB,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK;QAC3B,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,IAAI,aAAa,EAAE;QACrG,CAAC,CAAC,KAAK,CAAC;IACV,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;oEAMoE;AACpE,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,MAAc,EACd,EAAU,EACV,IAA8B,EAC9B,KAAc,EACd,OAAoB,kBAAkB,EACtC,SAAkB;IAElB,MAAM,EAAE,GAAG,IAAI,aAAa,CAAC;QAC3B,KAAK;QACL,OAAO,EAAE,MAAM;QACf,KAAK;QACL,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,KAAK,EAAE,yFAAyF;QACzG,gBAAgB,EAAE,KAAK;QACvB,aAAa,EAAE,KAAK;QACpB,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE;KACxC,CAAC,CAAC;IACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAA0B,CAAW,CAAC,OAAO,GAAG,EAAE,CAAC;IAChF,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

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

@@ -2,6 +2,8 @@ type Opts = {
     space?: string;
     server?: string;
     spawn?: string[];
+    runtime?: string;
+    launch?: string;
 };
 /** True if the delivery daemon we started for this folder is still running (pid file + liveness). */
 export declare function deliveryUp(): boolean;