@crouter/api 0.3.387 → 0.3.389

package/dist/core/installed-plugins.js

@@ -0,0 +1,79 @@
+// installed-plugins.ts — the LEAF-LEVEL installed-plugin reader: list the
+// plugin packages physically present under one scope root, with their
+// manifests and enabled-state from that root's config.json `plugins` block.
+//
+// This lives below resolver.ts (which re-exports it for its existing callers)
+// so that config.ts can layer plugin-declared launch config (`kinds`) into
+// `readMergedLaunchConfig` without an import cycle: resolver.ts imports
+// config.ts, so config.ts can never import resolver.ts. Imports here stay
+// leaf-safe: types, fs-utils, manifest only.
+import { join } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
+import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
+import { readPluginManifest } from './manifest.js';
+import { awaitBundleSwap, bundleSwapInFlightElsewhere } from './plugin-swap-lock.js';
+import { userStore } from './scoped-state/paths.js';
+import { readRawSettings } from './scoped-state/settings.js';
+import { pluginsDir } from './scope.js';
+function pluginConfigForRoot(scope, root) {
+    const store = scope === 'user' ? userStore(root) : undefined;
+    const cfg = store
+        ? readRawSettings({ store, key: 'user', kind: 'user', root: store.root })
+        : readJsonIfExists(join(root, CONFIG_FILE));
+    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
+}
+/**
+ * A bundle-plugin swap replaces `<plugins>/<name>` with two renames, so there
+ * is a window in which the config names a plugin whose directory is not there.
+ * A list taken inside that window would drop a plugin that is installed and
+ * about to be present again — the caller would build a command tree missing it.
+ *
+ * That exact signal — named in config, absent on disk — is what we re-check,
+ * and only when another process's swap lock says a swap is actually running: a
+ * genuinely deleted directory holds no lock and is reported as gone at once.
+ * Every normal invocation, where each config-named plugin has its directory,
+ * pays one Set lookup per name and nothing else.
+ */
+function swapsToWaitOut(scopeRootPath, cfg, present) {
+    const names = Object.keys(cfg);
+    if (names.every((name) => present.has(name)))
+        return [];
+    return names.filter((name) => !present.has(name) && bundleSwapInFlightElsewhere(scopeRootPath, name));
+}
+export function listInstalledPluginsInRoot(scope, scopeRootPath) {
+    const dir = scope === 'user' ? pluginsDir('user') : join(scopeRootPath, 'plugins');
+    if (!pathExists(dir))
+        return [];
+    const cfg = pluginConfigForRoot(scope, scopeRootPath);
+    const first = collectInstalledPlugins(scope, dir, cfg);
+    const waiting = swapsToWaitOut(scopeRootPath, cfg, new Set(first.map((plugin) => plugin.name)));
+    if (waiting.length === 0)
+        return first;
+    for (const name of waiting)
+        awaitBundleSwap(scopeRootPath, name);
+    // One re-list, never a loop: the second read is taken after every swap we
+    // observed has finished. A swap that starts after it is a package this
+    // invocation was never going to see anyway.
+    return collectInstalledPlugins(scope, dir, cfg);
+}
+function collectInstalledPlugins(scope, dir, cfg) {
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg[name];
+        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
+            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
+            version,
+        });
+    }
+    return out;
+}

package/dist/core/io.d.ts

@@ -0,0 +1,122 @@
+import { CrtrError } from './errors.js';
+import { type ExitCodeValue } from '../types.js';
+import { ApiError } from '../api/index.js';
+/** The private result mirror for one crtr CLI invocation launched by the
+ * canvas bash-preview extension. This deliberately never enters stdout: bash
+ * text is model context, while Pi tool-result details are viewer-only.
+ *
+ * One bash tool call may run several crtr invocations (`read a && read b`), so
+ * the mirror file is JSONL: one record per invocation, appended in order. Each
+ * invocation is its own process and `beginPreview` resets this module's state,
+ * so the appends compose across them with no shared state or locking. */
+export interface CrtrPreviewRecord {
+    path: string;
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: ErrorPayload;
+}
+/** A preview is bounded UI metadata, never a bulk-data channel. One
+ * `crtr integration run` once mirrored a 3 MB CRM dump into every copy of the
+ * transcript that contains its tool result — the session file, every replay
+ * frame, and the host product's stored conversation — because pi's 50 KB
+ * stdout truncation never sees this channel. The mirror write is the one
+ * choke point every record passes, so the bound lives here: an oversized
+ * record is dropped, and the viewer falls back to rendering the agent-facing
+ * stdout text, which pi bounds itself.
+ *
+ * Because records accumulate, this bounds the FILE TOTAL, not one line: a
+ * record that would overrun the remaining budget is dropped whole, so every
+ * line on disk stays valid JSON. */
+export declare const PREVIEW_RESULT_MAX_BYTES: number;
+/** Begin collecting the current leaf's structured response, if its caller
+ * supplied the private per-tool-call result path. */
+export declare function beginPreview(path: string): void;
+/** Publish the single-object or collected JSONL result after leaf dispatch. */
+export declare function publishPreviewResult(result: Record<string, unknown> | void): void;
+/** Mirror a structured record whose caller renders it itself instead of using
+ * the generic dispatcher (JSONL and event-stream leaves). */
+export declare function recordPreviewLine(obj: Record<string, unknown>): void;
+/** Preserve a verbatim JSONL stream's structured frames without changing the
+ * bytes written to stdout. Invalid third-party lines remain raw-only. */
+export declare function recordPreviewJsonLine(line: string): void;
+/** Record a terminal streaming failure that correctly remains off stdout
+ * because prior frames have already been delivered. */
+export declare function recordPreviewError(payload: ErrorPayload): void;
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export declare function setJsonOutput(v: boolean): void;
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export declare function isJsonOutput(): boolean;
+/** Structured error payload. `error` is a stable code the agent branches on;
+ *  `next` is the recovery road sign. */
+interface ErrorPayloadBase {
+    error: string;
+    message: string;
+    received?: unknown;
+    field?: string;
+    /** Transport status of a failed backend call (HTTP-transport plugins). It is kept out
+     *  of `received` on purpose: `received` names the caller's offending VALUE, and
+     *  reporting an HTTP status there is a false claim about what was sent. */
+    http_status?: number;
+    next: string;
+}
+export type ErrorPayload = ErrorPayloadBase & ({
+    primaryCompleted: true;
+    result: Record<string, unknown>;
+} | {
+    primaryCompleted?: never;
+    result?: never;
+});
+/** A command-level failure: surfaces as the JSON response on stdout. */
+export declare class InputError extends CrtrError {
+    payload: ErrorPayload;
+    constructor(payload: ErrorPayload, exitCode?: ExitCodeValue);
+}
+/** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
+ *  Called by the argv parser for leaves declaring a `stdin` parameter. */
+export declare function readStdinRaw(): Promise<string>;
+/** Best-effort, non-hanging peek at whatever stdin bytes are already
+ *  buffered — used ONLY to detect a positional/stdin conflict, never to
+ *  consume the leaf's actual required stdin body. Genuine piped/redirected
+ *  content (a heredoc, `< file`, `cat x |`) is fully written into the pipe
+ *  before this process starts reading, so it resolves within one tick; a
+ *  non-TTY stdin that's simply inherited and held open with nothing written
+ *  to it (e.g. a caller subprocess that never closes its own stdin) would
+ *  otherwise hang `readStdinRaw()` forever — this bounds that wait instead
+ *  of blocking the whole invocation on an ambiguous pipe. Returns '' on a
+ *  TTY (nothing can be piped) or once the bound elapses with no bytes. */
+export declare function peekStdinRaw(timeoutMs?: number): Promise<string>;
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
+export declare function emit(obj: Record<string, unknown>): void;
+/** One JSONL record. Call per event in a stream; partial reads stay parseable. */
+export declare function emitLine(obj: Record<string, unknown>): void;
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export declare function writeStdout(s: string): Promise<boolean>;
+export declare function diag(message: string): void;
+/** Translate an `ApiError` into the clean CLI error a leaf should surface.
+ *  Three tiers, in priority order:
+ *   1. Daemon-down (`daemon_unavailable`) → a `network`-class `CrtrError`
+ *      so the exit code and next-hint match the operational failure it is.
+ *   2. A server-thrown `InputError` round-trips its FULL structured payload
+ *      through `toErrorBody` into `ApiError.details` (`{error,message,next,…}`) —
+ *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
+ *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
+ *      it before the re-plumb, preserving its SPECIFIC code + next.
+ *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *      and a caller-supplied-or-default `next`. */
+export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
+/** Terminal error handler. Command-level failures (bad input, not-found,
+ *  ambiguous) surface as the JSON response on stdout so the caller parses one
+ *  contract. A daemon `ApiError` is translated to that same clean contract
+ *  (`apiErrorToCliError`) as a safety net for any leaf that lets it propagate.
+ *  Runtime/internal failures go to stderr as `{error:"internal"}` — raw traces
+ *  never reach the agent. Exits non-zero either way. */
+export declare function handle(e: unknown): void;
+export {};

package/dist/core/io.js

@@ -0,0 +1,373 @@
+// The agent-facing I/O contract. Flags and positional args on input; stdout is
+// agent-ready markdown/XML the caller acts on directly (the result rendered FOR
+// the model, not data it parses); structured errors; stderr is diagnostics only
+// and never carries the result. The raw JSON object is available behind the
+// `--json` global for tooling. See the cli-design reference.
+import { appendFileSync, statSync } from 'node:fs';
+import { CrtrError } from './errors.js';
+import { ExitCode } from '../types.js';
+import { PREVIEW_RESULT_PATH_ENV } from './preview-result-path.js';
+import { renderError } from './render.js';
+import { ApiError } from '../api/index.js';
+// output mode — prose (default) vs raw JSON (--json global, for tooling)
+let jsonOutput = false;
+let preview;
+/** A preview is bounded UI metadata, never a bulk-data channel. One
+ * `crtr integration run` once mirrored a 3 MB CRM dump into every copy of the
+ * transcript that contains its tool result — the session file, every replay
+ * frame, and the host product's stored conversation — because pi's 50 KB
+ * stdout truncation never sees this channel. The mirror write is the one
+ * choke point every record passes, so the bound lives here: an oversized
+ * record is dropped, and the viewer falls back to rendering the agent-facing
+ * stdout text, which pi bounds itself.
+ *
+ * Because records accumulate, this bounds the FILE TOTAL, not one line: a
+ * record that would overrun the remaining budget is dropped whole, so every
+ * line on disk stays valid JSON. */
+export const PREVIEW_RESULT_MAX_BYTES = 256 * 1024;
+/** Begin collecting the current leaf's structured response, if its caller
+ * supplied the private per-tool-call result path. */
+export function beginPreview(path) {
+    const resultPath = process.env[PREVIEW_RESULT_PATH_ENV];
+    preview = resultPath === undefined || resultPath === '' ? undefined : { path, jsonl: [] };
+}
+function publishPreview(record) {
+    const resultPath = process.env[PREVIEW_RESULT_PATH_ENV];
+    if (resultPath === undefined || resultPath === '')
+        return;
+    const line = `${JSON.stringify({ path: preview?.path ?? '', ...record })}\n`;
+    try {
+        const spent = statSync(resultPath, { throwIfNoEntry: false })?.size ?? 0;
+        if (spent + Buffer.byteLength(line, 'utf8') > PREVIEW_RESULT_MAX_BYTES)
+            return;
+        appendFileSync(resultPath, line, 'utf8');
+    }
+    catch {
+        // Preview transport is optional UI metadata. Its failure must never alter
+        // the CLI's stdout/error contract.
+    }
+}
+/** Publish the single-object or collected JSONL result after leaf dispatch. */
+export function publishPreviewResult(result) {
+    if (preview === undefined)
+        return;
+    if (result !== undefined && result !== null)
+        publishPreview({ result });
+    else if (preview.jsonl.length > 0 || preview.error !== undefined) {
+        publishPreview({ ...(preview.jsonl.length > 0 ? { jsonl: preview.jsonl } : {}), ...(preview.error === undefined ? {} : { error: preview.error }) });
+    }
+}
+/** Mirror a structured record whose caller renders it itself instead of using
+ * the generic dispatcher (JSONL and event-stream leaves). */
+export function recordPreviewLine(obj) {
+    preview?.jsonl.push(obj);
+}
+/** Preserve a verbatim JSONL stream's structured frames without changing the
+ * bytes written to stdout. Invalid third-party lines remain raw-only. */
+export function recordPreviewJsonLine(line) {
+    try {
+        const value = JSON.parse(line);
+        if (value !== null && typeof value === 'object' && !Array.isArray(value))
+            recordPreviewLine(value);
+    }
+    catch { /* a malformed remote frame remains the command's raw truth */ }
+}
+/** Record a terminal streaming failure that correctly remains off stdout
+ * because prior frames have already been delivered. */
+export function recordPreviewError(payload) {
+    if (preview !== undefined)
+        preview.error = payload;
+}
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export function setJsonOutput(v) {
+    jsonOutput = v;
+}
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export function isJsonOutput() {
+    return jsonOutput;
+}
+/** A command-level failure: surfaces as the JSON response on stdout. */
+export class InputError extends CrtrError {
+    payload;
+    constructor(payload, exitCode = ExitCode.USAGE) {
+        super(payload.error, payload.message, exitCode, { ...payload });
+        this.name = 'InputError';
+        this.payload = payload;
+    }
+}
+// stdin
+/** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
+ *  Called by the argv parser for leaves declaring a `stdin` parameter. */
+export async function readStdinRaw() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Best-effort, non-hanging peek at whatever stdin bytes are already
+ *  buffered — used ONLY to detect a positional/stdin conflict, never to
+ *  consume the leaf's actual required stdin body. Genuine piped/redirected
+ *  content (a heredoc, `< file`, `cat x |`) is fully written into the pipe
+ *  before this process starts reading, so it resolves within one tick; a
+ *  non-TTY stdin that's simply inherited and held open with nothing written
+ *  to it (e.g. a caller subprocess that never closes its own stdin) would
+ *  otherwise hang `readStdinRaw()` forever — this bounds that wait instead
+ *  of blocking the whole invocation on an ambiguous pipe. Returns '' on a
+ *  TTY (nothing can be piped) or once the bound elapses with no bytes. */
+export async function peekStdinRaw(timeoutMs = 200) {
+    if (process.stdin.isTTY)
+        return '';
+    return await new Promise((resolve) => {
+        const chunks = [];
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeListener('data', onData);
+            process.stdin.removeListener('end', onEnd);
+            process.stdin.removeListener('error', onError);
+            process.stdin.pause();
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        };
+        const onData = (chunk) => chunks.push(chunk);
+        const onEnd = () => finish();
+        const onError = () => finish();
+        const timer = setTimeout(finish, timeoutMs);
+        process.stdin.on('data', onData);
+        process.stdin.on('end', onEnd);
+        process.stdin.on('error', onError);
+        process.stdin.resume();
+    });
+}
+// stdout — the result, nothing else
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
+export function emit(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+/** One JSONL record. Call per event in a stream; partial reads stay parseable. */
+export function emitLine(obj) {
+    recordPreviewLine(obj);
+    process.stdout.write(JSON.stringify(obj) + '\n');
+}
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export function writeStdout(s) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const onErr = (e) => {
+            if (e.code === 'EPIPE')
+                finish(false);
+        };
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stdout.off('error', onErr);
+            resolve(ok);
+        };
+        process.stdout.on('error', onErr);
+        try {
+            process.stdout.write(s, (err) => finish(err === null || err === undefined));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+// stderr — diagnostics the agent MAY capture, never the result
+export function diag(message) {
+    process.stderr.write(message + '\n');
+}
+// errors
+function payloadOf(e) {
+    if (e instanceof InputError)
+        return e.payload;
+    const d = (e.details !== undefined ? e.details : {});
+    const result = d.primaryCompleted === true
+        && d.result !== null
+        && typeof d.result === 'object'
+        && !Array.isArray(d.result)
+        ? jsonSafeResult(d.result)
+        : undefined;
+    const next = d.next !== undefined
+        ? d.next
+        : 'Inspect the error and adjust the call. See -h for the schema.';
+    const base = {
+        error: e.code,
+        message: e.message,
+        received: d.received,
+        field: d.field,
+        ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
+    };
+    return result === undefined
+        ? { ...base, next }
+        : { ...base, primaryCompleted: true, result, next };
+}
+/** Detach completed results from getters/prototypes and keep every error sink
+ * JSON-safe. Tagged values preserve a truthful representation when a trusted
+ * primary violates its declared JSON result contract. */
+function jsonSafeResult(result) {
+    const seen = new WeakSet();
+    try {
+        const encoded = JSON.stringify(result, (_key, value) => {
+            if (typeof value === 'bigint')
+                return { $crtrType: 'bigint', value: value.toString() };
+            if (typeof value === 'number' && !Number.isFinite(value))
+                return { $crtrType: 'number', value: String(value) };
+            if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+                return { $crtrType: typeof value };
+            }
+            if (value !== null && typeof value === 'object') {
+                if (seen.has(value))
+                    return { $crtrType: 'circular' };
+                seen.add(value);
+            }
+            return value;
+        });
+        if (encoded !== undefined) {
+            const decoded = JSON.parse(encoded);
+            if (decoded !== null && typeof decoded === 'object' && !Array.isArray(decoded)) {
+                return decoded;
+            }
+        }
+    }
+    catch { /* a throwing getter/toJSON must not suppress the partial failure */ }
+    return {
+        $crtrType: 'unavailable',
+        message: 'The completed primary result could not be represented as JSON.',
+    };
+}
+// ApiError → clean CLI error — the ONE shared translation (plan C-5)
+//
+// A daemon `ApiError` is NOT a `CrtrError`, so left unhandled it falls through
+// `handle()` as an "internal crtr bug" — the wrong UX for an operational
+// failure. This is the single place that maps it back to the clean, structured
+// error the pre-API leaves surfaced, so every re-plumbed verb shares one
+// contract instead of re-implementing the mapping per command. io.ts importing
+// `ApiError` from `src/api` is canvas-clean (src/api is Node-built-ins only).
+/** Map a daemon HTTP status to the stable CLI error code the pre-API leaves
+ *  used, so agent-facing error contracts survive the re-plumb. Used only as the
+ *  fallback when the server did NOT round-trip a full structured payload. */
+const STATUS_TO_CLI_CODE = {
+    400: 'invalid_request',
+    404: 'not_found',
+    409: 'conflict',
+    422: 'unprocessable',
+};
+/** Translate an `ApiError` into the clean CLI error a leaf should surface.
+ *  Three tiers, in priority order:
+ *   1. Daemon-down (`daemon_unavailable`) → a `network`-class `CrtrError`
+ *      so the exit code and next-hint match the operational failure it is.
+ *   2. A server-thrown `InputError` round-trips its FULL structured payload
+ *      through `toErrorBody` into `ApiError.details` (`{error,message,next,…}`) —
+ *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
+ *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
+ *      it before the re-plumb, preserving its SPECIFIC code + next.
+ *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *      and a caller-supplied-or-default `next`. */
+export function apiErrorToCliError(err, next) {
+    // A handover is NOT a down daemon: the successor is already up (the client
+    // waited for its /healthz), so telling anyone to start one is wrong — the
+    // only thing left is to re-issue the call.
+    if (err.code === 'daemon_restarting') {
+        return new CrtrError('daemon_restarting', err.message, ExitCode.NETWORK, {
+            next: 'crtrd is now on the new generation — retry the command.',
+        });
+    }
+    if (err.code === 'layout_migration_required') {
+        return new CrtrError('layout_migration_required', err.message, ExitCode.NETWORK, {
+            next: 'Run `crtr sys migrate` while the runtime is offline, then restart it.',
+        });
+    }
+    if (err.code === 'daemon_unavailable') {
+        return new CrtrError('daemon_unavailable', err.message, ExitCode.NETWORK, {
+            next: 'Start it with `crtr sys daemon start`, then retry.',
+        });
+    }
+    // A responding daemon can relay an unavailable provider or storage service.
+    // HTTP 503 alone does not mean that crtrd is down.
+    if (err.status === 503) {
+        return new CrtrError(err.code, err.message, ExitCode.NETWORK, {
+            next: next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
+        });
+    }
+    const d = err.details;
+    // A `/v1` request validator reports each bad field in `details.violations`;
+    // the message alone only says the request was invalid.
+    const violations = Array.isArray(d?.violations)
+        ? d.violations
+            .map((v) => `${String(v.field)} ${String(v.problem)}${v.received !== undefined ? ` (received ${JSON.stringify(v.received)})` : ''}`)
+        : [];
+    const payload = d && typeof d.error === 'string' && typeof d.message === 'string' && typeof d.next === 'string'
+        ? d
+        : {
+            error: STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message,
+            next: next ??
+                (err.status >= 500
+                    ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
+                    : err.status === 404
+                        ? 'List nodes with `crtr node inspect list`.'
+                        : 'Inspect the error and adjust the call. See -h for the schema.'),
+        };
+    // Preserve the exit-code class the server leaf carried instead of collapsing
+    // every non-503 to USAGE(2): a not-found (404 / `not_found`) surfaces exit 3
+    // and an ambiguous match exit 4, matching the codes the local-only leaves
+    // (memory/pkg/sys) still emit so the taxonomy stays uniform across the CLI.
+    return new InputError(payload, exitForCliCode(payload.error, err.status));
+}
+/** The `ExitCode` class a reconstructed API error should carry, keyed off the
+ *  round-tripped CLI code (and the 404 status as the not-found signal — the
+ *  server maps NOT_FOUND's exit class to status 404, but folds AMBIGUOUS and
+ *  USAGE both onto 400, so `ambiguous` is recoverable only from the code). */
+function exitForCliCode(code, status) {
+    if (code === 'not_found' || status === 404)
+        return ExitCode.NOT_FOUND;
+    if (code === 'ambiguous')
+        return ExitCode.AMBIGUOUS;
+    return ExitCode.USAGE;
+}
+/** Terminal error handler. Command-level failures (bad input, not-found,
+ *  ambiguous) surface as the JSON response on stdout so the caller parses one
+ *  contract. A daemon `ApiError` is translated to that same clean contract
+ *  (`apiErrorToCliError`) as a safety net for any leaf that lets it propagate.
+ *  Runtime/internal failures go to stderr as `{error:"internal"}` — raw traces
+ *  never reach the agent. Exits non-zero either way. */
+export function handle(e) {
+    if (e instanceof ApiError) {
+        handle(apiErrorToCliError(e));
+        return;
+    }
+    if (e instanceof CrtrError) {
+        const payload = payloadOf(e);
+        if (preview !== undefined)
+            publishPreview({ error: payload });
+        const out = jsonOutput
+            ? JSON.stringify(payload, null, 2)
+            : renderError(payload);
+        process.stdout.write(out + '\n');
+        process.exitCode = e.exitCode;
+        return;
+    }
+    const err = e;
+    const message = err !== null && err !== undefined && typeof err.message === 'string'
+        ? err.message
+        : String(e);
+    process.stderr.write(JSON.stringify({
+        error: 'internal',
+        message,
+        next: 'This is a crtr bug, not a bad call. Retry; if it persists, report it.',
+    }, null, 2) + '\n');
+    process.exitCode = ExitCode.GENERAL;
+}

package/dist/core/keybindings/attach-control.d.ts

@@ -0,0 +1,49 @@
+export declare const ATTACH_CONTROL_BINDINGS: readonly [{
+    readonly menuId: "crtr.tmux.menu.attach.detach";
+    readonly actionId: "crtr.attach.detach";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.clear-or-detach";
+    readonly actionId: "crtr.attach.clear-or-detach";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.graph.toggle";
+    readonly actionId: "crtr.attach.graph.toggle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.help.toggle";
+    readonly actionId: "crtr.attach.help.toggle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.inbox.toggle";
+    readonly actionId: "crtr.attach.inbox.toggle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.inbox-strip";
+    readonly actionId: "crtr.attach.inbox-strip";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.model-ladder.next";
+    readonly actionId: "crtr.attach.model-ladder.next";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.model-ladder.previous";
+    readonly actionId: "crtr.attach.model-ladder.previous";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.command.inspect";
+    readonly actionId: "crtr.attach.command.inspect";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.file-review";
+    readonly actionId: "crtr.attach.file-review";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.profile-files";
+    readonly actionId: "crtr.attach.profile-files";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.search";
+    readonly actionId: "crtr.attach.search";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.whip";
+    readonly actionId: "crtr.attach.whip";
+}];
+export type AttachBindingId = typeof ATTACH_CONTROL_BINDINGS[number]['actionId'];
+export type AttachMenuBindingId = typeof ATTACH_CONTROL_BINDINGS[number]['menuId'];
+export interface ExtractedAttachControlInput {
+    readonly actionId: AttachBindingId;
+    readonly remaining: string;
+}
+export declare function decodeAttachControlInput(data: string): AttachBindingId | undefined;
+export declare function encodeAttachControlInput(actionId: AttachBindingId): string;
+export declare function extractAttachControlInput(data: string): ExtractedAttachControlInput | undefined;

package/dist/core/keybindings/attach-control.js

@@ -0,0 +1,42 @@
+export const ATTACH_CONTROL_BINDINGS = [
+    { menuId: 'crtr.tmux.menu.attach.detach', actionId: 'crtr.attach.detach' },
+    { menuId: 'crtr.tmux.menu.attach.clear-or-detach', actionId: 'crtr.attach.clear-or-detach' },
+    { menuId: 'crtr.tmux.menu.attach.graph.toggle', actionId: 'crtr.attach.graph.toggle' },
+    { menuId: 'crtr.tmux.menu.attach.help.toggle', actionId: 'crtr.attach.help.toggle' },
+    { menuId: 'crtr.tmux.menu.attach.inbox.toggle', actionId: 'crtr.attach.inbox.toggle' },
+    { menuId: 'crtr.tmux.menu.attach.inbox-strip', actionId: 'crtr.attach.inbox-strip' },
+    { menuId: 'crtr.tmux.menu.attach.model-ladder.next', actionId: 'crtr.attach.model-ladder.next' },
+    { menuId: 'crtr.tmux.menu.attach.model-ladder.previous', actionId: 'crtr.attach.model-ladder.previous' },
+    { menuId: 'crtr.tmux.menu.attach.command.inspect', actionId: 'crtr.attach.command.inspect' },
+    { menuId: 'crtr.tmux.menu.attach.file-review', actionId: 'crtr.attach.file-review' },
+    { menuId: 'crtr.tmux.menu.attach.profile-files', actionId: 'crtr.attach.profile-files' },
+    { menuId: 'crtr.tmux.menu.attach.search', actionId: 'crtr.attach.search' },
+    { menuId: 'crtr.tmux.menu.attach.whip', actionId: 'crtr.attach.whip' },
+];
+const ATTACH_CONTROL_PREFIX = '\x1b_crtr;';
+const ATTACH_CONTROL_SUFFIX = '\x1b\\';
+const ATTACH_BINDING_IDS = new Set(ATTACH_CONTROL_BINDINGS.map(({ actionId }) => actionId));
+export function decodeAttachControlInput(data) {
+    if (!data.startsWith(ATTACH_CONTROL_PREFIX) || !data.endsWith(ATTACH_CONTROL_SUFFIX))
+        return undefined;
+    const actionId = data.slice(ATTACH_CONTROL_PREFIX.length, -ATTACH_CONTROL_SUFFIX.length);
+    return ATTACH_BINDING_IDS.has(actionId) ? actionId : undefined;
+}
+export function encodeAttachControlInput(actionId) {
+    return `${ATTACH_CONTROL_PREFIX}${actionId}${ATTACH_CONTROL_SUFFIX}`;
+}
+export function extractAttachControlInput(data) {
+    let match;
+    for (const { actionId } of ATTACH_CONTROL_BINDINGS) {
+        const encoded = encodeAttachControlInput(actionId);
+        const index = data.indexOf(encoded);
+        if (index >= 0 && (match === undefined || index < match.index))
+            match = { actionId, encoded, index };
+    }
+    if (match === undefined)
+        return undefined;
+    return {
+        actionId: match.actionId,
+        remaining: data.slice(0, match.index) + data.slice(match.index + match.encoded.length),
+    };
+}