@crouton-kit/crouter 0.3.79 → 0.3.81

package/dist/core/runtime/package-health.d.ts

@@ -0,0 +1,15 @@
+export interface MissingPackage {
+    /** The raw `packages[]` entry as stored in settings.json. */
+    source: string;
+    /** Absolute path it resolved to (which does not exist). */
+    resolved: string;
+}
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export declare function findMissingPackagePaths(agentDir: string, homeDir?: string): MissingPackage[];
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export declare function missingPackageWarning(agentDir: string, homeDir?: string): string | null;

package/dist/core/runtime/package-health.js

@@ -0,0 +1,76 @@
+// package-health: detect pi packages configured in `<agentDir>/settings.json`
+// whose LOCAL-PATH source no longer exists on disk.
+//
+// Why this exists: pi installs a local-path package (e.g. crouter's bundled
+// `pi-crtr-extensions`, which surfaces `~/.claude` commands/skills/plugins as
+// slash commands) by storing its path in settings.json RELATIVE to the settings
+// dir. Moving the crouter repo silently invalidates that relative path — and pi
+// DISCARDS a missing package with no error, so the extension just never loads
+// and its whole feature (here: every Claude command/marketplace command) simply
+// vanishes with no diagnostic. This turns that silent failure into a loud,
+// actionable warning. The fix it points at is `crtr sys setup`, which re-resolves
+// package paths to the repo's current location.
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/** Expand a leading `~` against `homeDir` (pi's own convention). */
+function expandTilde(pathValue, homeDir) {
+    if (pathValue === '~')
+        return homeDir;
+    if (pathValue.startsWith('~/'))
+        return join(homeDir, pathValue.slice(2));
+    return pathValue;
+}
+/** A `packages[]` entry is a LOCAL PATH (not an npm ref) — the only kind that
+ *  can go stale on a repo move. `npm:...` and bare registry names resolve
+ *  through node/npm, not the filesystem, so they are out of scope here. */
+function isLocalPathSource(source) {
+    if (source.startsWith('npm:'))
+        return false;
+    return source.startsWith('.') || source.startsWith('/') || source.startsWith('~');
+}
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export function findMissingPackagePaths(agentDir, homeDir = homedir()) {
+    let raw;
+    try {
+        raw = readFileSync(join(agentDir, 'settings.json'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let packages;
+    try {
+        packages = JSON.parse(raw).packages;
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(packages))
+        return [];
+    const missing = [];
+    for (const entry of packages) {
+        if (typeof entry !== 'string' || !isLocalPathSource(entry))
+            continue;
+        const resolved = resolve(agentDir, expandTilde(entry, homeDir));
+        if (!existsSync(resolved))
+            missing.push({ source: entry, resolved });
+    }
+    return missing;
+}
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export function missingPackageWarning(agentDir, homeDir = homedir()) {
+    const missing = findMissingPackagePaths(agentDir, homeDir);
+    if (missing.length === 0)
+        return null;
+    const lines = missing.map((m) => `  • ${m.source}\n      → ${m.resolved} (missing)`);
+    return (`crtr: ${missing.length} configured pi package path${missing.length === 1 ? '' : 's'} ` +
+        `no longer exist${missing.length === 1 ? 's' : ''} — pi silently skips these, so their ` +
+        `slash commands (e.g. ~/.claude commands & marketplace plugins) will not load.\n` +
+        lines.join('\n') +
+        `\n  Fix: re-run \`crtr sys setup\` (re-resolves package paths to this repo's current location).`);
+}

package/dist/core/runtime/resume.d.ts

@@ -0,0 +1,6 @@
+/** Resolve a front-door resume: pick a target root (MRU or via picker), then
+ *  take over this terminal to view it. On success it execs the viewer inline and
+ *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
+ *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
+ *  caller exits without surprise-booting). */
+export declare function resumeRoot(cwd: string, pick: boolean): Promise<'empty' | 'aborted'>;

package/dist/core/runtime/resume.js

@@ -0,0 +1,207 @@
+// Front-door resume — `crtr -c` / `crtr -r`.
+//
+//   crtr -c | --continue   → revive + attach the MRU root pinned to this cwd,
+//                            inline in THIS terminal (no picker). If no root is
+//                            resumable here, boot a fresh one.
+//   crtr -r | --resume     → same, but choose from a keypress menu of the roots
+//                            pinned to this cwd first.
+//
+// A "session" in the Claude-Code sense is a crtr ROOT node: a durable pi
+// conversation pinned to a cwd that never dies, only goes dormant. So resuming
+// is reviving the last root here and making THIS pane its controller-viewer —
+// mirroring the front-door boot tail (register the pane as the viewer focus,
+// then exec `crtr surface attach` inline). cwd is the key so it never teleports
+// across projects; see `listResumableRoots`.
+import { spawn } from 'node:child_process';
+import { emitKeypressEvents } from 'node:readline';
+import { getNode, listResumableRoots } from '../canvas/index.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { reviveNode } from './revive.js';
+import { installTmuxBindings } from './tmux-chrome.js';
+import { registerViewerFocus, waitForBrokerViewSocket, viewerSplitEnv, currentTmux, inTmux, } from './placement.js';
+import { getFocusByNode, closeFocusRow } from '../canvas/focuses.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+import { stdoutColor } from '../output.js';
+const dim = stdoutColor.dim;
+const bold = stdoutColor.bold;
+const accent = stdoutColor.cyan;
+/** Resolve a front-door resume: pick a target root (MRU or via picker), then
+ *  take over this terminal to view it. On success it execs the viewer inline and
+ *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
+ *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
+ *  caller exits without surprise-booting). */
+export async function resumeRoot(cwd, pick) {
+    const roots = listResumableRoots(cwd);
+    if (roots.length === 0)
+        return 'empty';
+    let target;
+    if (pick && roots.length > 1) {
+        target = await pickRoot(roots, cwd);
+        if (target === null)
+            return 'aborted';
+    }
+    else {
+        target = roots[0]; // MRU (also the sole root under `-r` with one candidate)
+    }
+    await attachInline(target.node_id, cwd);
+    return 'aborted'; // unreachable — attachInline execs and exits
+}
+/** Revive the target root's broker if dormant, register THIS pane as its one
+ *  viewer, and exec `crtr surface attach` inline so this terminal becomes the
+ *  controller-viewer. Mirrors the front-door boot tail. Does not return. */
+async function attachInline(nodeId, cwd) {
+    void cwd;
+    if (!inTmux()) {
+        throw new Error('crtr must be resumed from inside a tmux session — start tmux first (e.g. `tmux new -s work`), then run `crtr -c` there.');
+    }
+    const meta = getNode(nodeId);
+    if (meta === null)
+        throw new Error(`resume: unknown node ${nodeId}`);
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    // Revive the broker engine if dormant. reviveNode double-launch-guards, so a
+    // still-alive broker no-ops and returns no launch handle; only a fresh launch
+    // needs the view-socket wait below.
+    const wasAlive = isPidAlive(meta.pi_pid ?? null);
+    const revived = reviveNode(nodeId, { resume: true });
+    try {
+        installTmuxBindings();
+    }
+    catch { /* best-effort */ }
+    // Make THIS pane the node's one viewer. A dormant root's prior focus row
+    // points at a stale/detached pane (the front door keeps the row across a
+    // clean detach), so drop it and claim the current pane — the exact --new-pane
+    // discipline from placement.focus (UNIQUE(node_id): one viewer per node).
+    const here = currentTmux();
+    if (here !== null) {
+        const prior = getFocusByNode(nodeId);
+        if (prior !== null) {
+            try {
+                closeFocusRow(prior.focus_id);
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            registerViewerFocus(nodeId, here.pane, here.session, here.window);
+        }
+        catch { /* best-effort */ }
+    }
+    // A fresh launch must bind its view socket before we attach; an already-alive
+    // broker already has one.
+    if (!wasAlive) {
+        const ok = await waitForBrokerViewSocket(nodeId, revived.launch?.exited);
+        if (!ok)
+            throw new Error(`the resumed root broker ${nodeId} never bound its view socket — cannot attach.`);
+    }
+    const attachEnv = { ...process.env, ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: '30000' };
+    const child = spawn('crtr', ['surface', 'attach', 'to', nodeId], { stdio: 'inherit', env: attachEnv });
+    const code = await new Promise((res) => {
+        child.once('exit', (c) => res(c ?? 0));
+        child.once('error', () => res(1));
+    });
+    process.exit(code);
+}
+// ---------------------------------------------------------------------------
+// `-r` picker — a minimal raw-mode keypress menu (pre-boot, we own the TTY).
+// ---------------------------------------------------------------------------
+const HILITE = accent('\u25b8');
+const cursorUp = (n) => (n > 0 ? `\u001b[${n}A\r` : '');
+const CLEAR_DOWN = '\u001b[0J';
+function label(r) {
+    // Liveness is the broker pid, not the row status: a dormant resident root
+    // keeps status='active' while its engine is down.
+    const live = isPidAlive(r.pi_pid ?? null) ? accent('\u25cf live') : dim('\u25cb dormant');
+    const name = r.name && r.name !== r.kind ? r.name : `${r.kind} root`;
+    return `${name}  ${live}`;
+}
+function detail(r, cwd) {
+    const when = ago(r.created);
+    const where = r.cwd === cwd ? '' : `  ${r.cwd}`;
+    return `${r.node_id}  ${when}${where}`;
+}
+function ago(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ms) || ms < 0)
+        return '';
+    const m = Math.floor(ms / 60000);
+    if (m < 1)
+        return 'just now';
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+/** Drive a highlighted keypress menu of resumable roots. ↑/↓ or j/k move,
+ *  digits jump, Enter picks, q/Esc/Ctrl-C abort → null. Restores the TTY on
+ *  every exit path so the inline viewer gets a clean terminal. */
+function pickRoot(roots, cwd) {
+    const title = 'Resume a session here';
+    const subtitle = `${roots.length} roots pinned to ${cwd}`;
+    return new Promise((resolve) => {
+        const out = process.stdout;
+        const input = process.stdin;
+        let sel = 0;
+        let prevLines = 0;
+        const render = () => {
+            let s = `\n  ${bold(title)}\n  ${dim(subtitle)}\n\n`;
+            roots.forEach((r, i) => {
+                const mark = i === sel ? HILITE : ' ';
+                const slot = i < 9 ? key(`${i + 1}`) : '  ';
+                s += `  ${mark} ${slot}  ${label(r)}  ${dim(detail(r, cwd))}\n`;
+            });
+            s += `\n  ${dim('↑/↓ move  enter resume  q quit')}\n`;
+            return s;
+        };
+        const draw = () => {
+            const block = render();
+            out.write((prevLines > 0 ? cursorUp(prevLines) + CLEAR_DOWN : '') + block);
+            prevLines = block.split('\n').length - 1;
+        };
+        emitKeypressEvents(input);
+        const wasRaw = input.isRaw ?? false;
+        if (input.isTTY)
+            input.setRawMode(true);
+        input.resume();
+        const finish = (result) => {
+            input.removeListener('keypress', onKey);
+            if (input.isTTY)
+                input.setRawMode(wasRaw);
+            input.pause();
+            out.write(cursorUp(prevLines) + CLEAR_DOWN);
+            resolve(result);
+        };
+        const onKey = (_str, k) => {
+            const name = k.name ?? '';
+            if (k.ctrl && name === 'c') {
+                finish(null);
+                process.exit(130);
+            }
+            if (name === 'q' || name === 'escape')
+                return finish(null);
+            if (name === 'up' || name === 'k') {
+                sel = (sel - 1 + roots.length) % roots.length;
+                return draw();
+            }
+            if (name === 'down' || name === 'j') {
+                sel = (sel + 1) % roots.length;
+                return draw();
+            }
+            if (name === 'return' || name === 'enter')
+                return finish(roots[sel]);
+            const digit = Number.parseInt(k.sequence ?? '', 10);
+            if (Number.isInteger(digit) && digit >= 1 && digit <= Math.min(9, roots.length)) {
+                sel = digit - 1;
+                return finish(roots[sel]);
+            }
+        };
+        input.on('keypress', onKey);
+        draw();
+    });
+}
+function key(s) {
+    return accent(s);
+}

package/dist/core/runtime/spawn.js

@@ -72,10 +72,10 @@ export async function bootRoot(opts) {
     // covering cwd > a synchronous create-or-root-profile prompt (the stable root
     // profile, headless).
     const profileId = await selectProfileForCwd(opts.cwd, opts.profile, opts.pickProfile ?? false);
-    // Immediate feedback: the broker + viewer boot take ~1s and the profile
-    // selector has just released the terminal — a silent cursor reads as a hang.
-    if (process.stdout.isTTY)
-        process.stdout.write('\u001b[2m  › starting…\u001b[0m\r\n');
+    // No boot spinner here: the attach viewer paints the crouton banner the moment
+    // the engine attaches (~1s), which is the real "we're up" signal. A separate
+    // `› starting…` line would just linger above it in scrollback (the viewer
+    // appends, it doesn't clear the screen), so it's redundant.
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false, cwd: opts.cwd, profileId });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.79",
+  "version": "0.3.81",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",