@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/pi-extensions/canvas-nav.js

@@ -18,15 +18,22 @@
 // alt+c is a tmux display-menu (not a pi key), so prefix chords (m/e/1-9/custom)
 // are tmux menu items that route through `crtr canvas chord`.
 //
-// Selection / liveness signals:
-//   CURSOR (selected) = reverse-video bar (ESC[7m), full width — an attribute,
-//                       not a colour, so it reads under NO_COLOR. Plus a ▸ caret.
-//   ACTIVE (running)  = a coloured background bar (status 'active'); the dot
-//                       glyph still carries the signal where colour is stripped.
-//   SELF              = bold name — a quiet "you are here" marker.
+// Selection / attachment signals:
+//   CURSOR (selected)  = reverse-video bar (ESC[7m), full width — an attribute,
+//                        not a colour, so it reads under NO_COLOR.
+//   ATTACHED (watched) = a coloured background bar — a human is currently
+//                        viewing the node: a `focuses` viewport points at it
+//                        (tmux host) or ≥1 helloed viewer is connected to its
+//                        broker (job/attach.json). Running is a separate axis,
+//                        signaled by the dot glyph alone (● = engine active on
+//                        its host — which may be an unwatched backstage pane
+//                        or a paneless broker).
+//   SELF               = bold name — a quiet "you are here" marker.
 //
 // Folding is auto by default: a branch stays COLLAPSED unless its subtree holds
 // a running ('active') agent or self. h/l override that per-node and persist.
+// A ▸ caret marks an expandable (collapsed-with-kids) row — but NOT the cursor
+// row, whose reverse-video bar already sets it apart.
 //
 // ⚑K pending-asks is PER-NODE, inline on each waiting node's own row (manager,
 // reports, tree rows; self shows a trailing ⚑ line in BASE). ⤳M direct-children
@@ -39,7 +46,7 @@
 import { execFile, execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, subscribersOf, subscriptionsOf, jobDir, fullName } from '../core/canvas/index.js';
+import { getNode, subscribersOf, subscriptionsOf, jobDir, fullName, listFocuses } from '../core/canvas/index.js';
 import { readConfig } from '../core/config.js';
 // ---------------------------------------------------------------------------
 // Module-level state — persists across /reload so guards don't stack and fold
@@ -80,17 +87,19 @@ const VIEWPORT_FALLBACK_ROWS = 30;
 // ANSI styling. pi renders embedded escapes in widget lines and measures width
 // ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
 // (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
-// NO_COLOR; the active-row tint is a background COLOUR, but the differing dot
-// glyph (●/○/✓/✗) keeps the running signal even where colour is stripped.
+// NO_COLOR; the attached-row tint is a background COLOUR, while the dot glyph
+// (●/○/✓/✗) carries the running signal independently, even where colour is
+// stripped.
 // ---------------------------------------------------------------------------
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
 const BOLD = `${ESC}1m`;
 const DIM = `${ESC}2m`;
 const REVERSE = `${ESC}7m`;
-/** Dark-green background bar marking a running ('active') node — distinct from
- *  the cursor's reverse-video bar; chosen so default-fg text stays readable. */
-const BG_ACTIVE = `${ESC}48;5;22m`;
+/** Dark-green background bar marking an ATTACHED node (a human is currently
+ *  watching it) — distinct from the cursor's reverse-video bar; chosen so
+ *  default-fg text stays readable. */
+const BG_ATTACHED = `${ESC}48;5;22m`;
 const GREEN = `${ESC}32m`;
 const RED = `${ESC}31m`;
 const YELLOW = `${ESC}33m`;
@@ -150,7 +159,7 @@ function fillWidth() {
     return Math.max(20, Math.min((process.stdout.columns ?? 80) - 2, 180));
 }
 /** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
- *  the cursor, BG_ACTIVE for a running node). `open` is re-asserted after every
+ *  the cursor, BG_ATTACHED for a human-watched node). `open` is re-asserted after every
  *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
  *  bar; the visible width is padded out to `width`; the line closes with a real
  *  RESET so the style never bleeds into the editor below. */
@@ -181,6 +190,42 @@ function shortId(id) {
     return id.slice(0, 8);
 }
 // ---------------------------------------------------------------------------
+// Attachment — is a human currently WATCHING a node? A separate axis from
+// running (status 'active' = the engine is live on its host, which may be an
+// unwatched backstage pane or a paneless broker). Two hosts, two signals:
+//   tmux   — a `focuses` row points at the node (one cheap sqlite read per
+//            render pass; pane-existence alone is NOT the signal).
+//   broker — the broker persists its helloed-viewer count to job/attach.json
+//            on every viewer change (src/core/runtime/broker.ts). Trusted only
+//            while the node is 'active': a broker crash can leave a stale file.
+// ---------------------------------------------------------------------------
+/** Node ids currently shown in a tmux focus viewport. Built once per render. */
+function focusedNodeIds() {
+    try {
+        return new Set(listFocuses().map((f) => f.node_id));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** True when a human is watching `id` right now (tmux focus or broker viewer). */
+function isAttached(id, node, focused) {
+    if (focused.has(id))
+        return true;
+    if (node?.status !== 'active')
+        return false; // stale attach.json from a crash
+    try {
+        const p = join(jobDir(id), 'attach.json');
+        if (!existsSync(p))
+            return false;
+        const rec = JSON.parse(readFileSync(p, 'utf8'));
+        return typeof rec.viewers === 'number' && rec.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
 // Per-node ask counts — ONE shell-out per poll. `crtr canvas attention map`
 // buckets a whole sub-DAG's pending asks by node in a single process, so the
 // timer stays cheap (< 2 s) regardless of how many nodes are visible. --json
@@ -357,12 +402,13 @@ function buildGraphModel(self) {
     walk(rootId, '', true, true);
     return rows;
 }
-/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ACTIVE
- *  (running) node → a coloured background bar; SELF → bold name. The cursor
- *  outranks the active tint when both land on the same row. */
-function renderGraphRow(r, isCursor) {
-    const wrap = (line, active) => isCursor ? fillBar(line, fillWidth(), REVERSE)
-        : active ? fillBar(line, fillWidth(), BG_ACTIVE)
+/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
+ *  (human-watched) node → a coloured background bar; SELF → bold name. The
+ *  cursor outranks the attached tint when both land on the same row. Running
+ *  is signaled by the dot glyph alone (● green = active engine). */
+function renderGraphRow(r, isCursor, focused) {
+    const wrap = (line, attached) => isCursor ? fillBar(line, fillWidth(), REVERSE)
+        : attached ? fillBar(line, fillWidth(), BG_ATTACHED)
             : truncate(line);
     if (r.cycle) {
         const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
@@ -374,10 +420,14 @@ function renderGraphRow(r, isCursor) {
     const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
     const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
     const tokens = `${DIM}${tokensCell(r.id)}${RESET}`;
-    const caret = isCursor ? `${BOLD}▸${RESET} ` : '  ';
-    const fold = r.hasKids && r.collapsed ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
+    // ▸ marks an expandable (collapsed-with-kids) row. The cursor row gets no
+    // caret — its reverse-video bar already distinguishes it — so the triangle
+    // reads purely as "this unfolds".
+    const expandable = r.hasKids && r.collapsed;
+    const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
+    const fold = expandable ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
     const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${childBadge(node)}${fold}${askBadge(r.id)}`;
-    return wrap(line, node?.status === 'active');
+    return wrap(line, isAttached(r.id, node, focused));
 }
 /** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
  *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
@@ -481,6 +531,10 @@ export function registerCanvasNav(pi) {
     // Captured from session_start; used in every subsequent render.
     let ui;
     let renderScheduled = false;
+    // Run mode captured at session_start. The nav chrome + ask-poll timer are
+    // interactive-only; a headless ('print') broker leaves this non-'tui' so the
+    // timer no-ops (no per-tick `crtr` shell-out) and no chrome is rendered.
+    let liveMode;
     // Cache config once (binds rarely change within a session; readConfig is sync
     // and never throws). prefixKey drives the non-tmux GRAPH toggle shortcut.
     let navConfig;
@@ -576,10 +630,11 @@ export function registerCanvasNav(pi) {
         }
         const end = Math.min(rows.length, scrollTop + viewportH);
         const lines = [];
+        const focused = focusedNodeIds(); // one sqlite read per render pass
         if (scrollTop > 0)
             lines.push(`${DIM}  ↑ ${scrollTop} more${RESET}`);
         for (let i = scrollTop; i < end; i++)
-            lines.push(renderGraphRow(rows[i], i === cursorIdx));
+            lines.push(renderGraphRow(rows[i], i === cursorIdx, focused));
         if (end < rows.length)
             lines.push(`${DIM}  ↓ ${rows.length - end} more${RESET}`);
         const hint = pendingConfirm !== undefined
@@ -844,6 +899,12 @@ export function registerCanvasNav(pi) {
     // Event handlers
     // -------------------------------------------------------------------------
     pi.on('session_start', (_event, ctx) => {
+        liveMode = ctx.mode;
+        // The nav chrome (widgets, key taps, the ask-poll timer) is interactive-only.
+        // A headless (print-mode) broker loads this extension but renders no chrome
+        // and must not poll. Under tmux ctx.mode is always 'tui' — byte-identical.
+        if (ctx.mode !== 'tui')
+            return;
         ui = ctx.ui;
         // Fresh session / hot-swap: start in BASE and clear any legacy or
         // inactive-view widgets so nothing stale bleeds through.
@@ -887,6 +948,9 @@ export function registerCanvasNav(pi) {
     if (liveTimer !== undefined)
         clearInterval(liveTimer);
     const timer = setInterval(() => {
+        // Inert in a headless ('print') broker — never shell out to `crtr` per tick.
+        if (liveMode !== 'tui')
+            return;
         try {
             const rootId = climbRoot(nodeId);
             const fresh = fetchAsksMap(rootId);

package/dist/pi-extensions/canvas-stophook.js

@@ -500,14 +500,23 @@ export function registerCanvasStophook(pi) {
             // down; the daemon watches its inbox and revives it (resume) the moment a
             // subscribed worker delivers. An 'attended' root never releases: the human
             // is its wake source, so we keep its window live and dormant.
-            if (decision.reason === 'awaiting') {
-                // AWAITING = F3. transition('release') marks it idle-released. If this
-                // node is FOCUSED its pane FREEZES in place (remain-on-exit, armed at
-                // focus time) so the daemon can respawn-pane -k it back into the SAME
-                // focus pane when a worker pushes; if UNFOCUSED its backstage pane
-                // closes (dormant) and the daemon revives it into the backstage on the
-                // inbox. Both are the same release — tmux's per-window remain-on-exit
-                // decides freeze vs close. NO manager-takeover (awaiting ≠ done).
+            if (decision.reason === 'awaiting' || decision.reason === 'scheduled') {
+                // AWAITING ≠ done (no manager-takeover). What happens next splits on
+                // whether the user is WATCHING this node:
+                //   • FOCUSED → it holds the user's viewport, so keep pi LIVE and
+                //     dormant (exactly like a resident root): do NOT release or shut
+                //     down. The in-process inbox-watcher (still alive) wakes it the
+                //     instant a worker pushes — no respawn, no frozen pane, the pane
+                //     stays interactive. When the user later focuses AWAY, placement's
+                //     retarget reclassifies it as a parked terminal viewer and releases
+                //     it then (transition 'release' + pane reaped), so the kept-alive
+                //     pi is reclaimed on focus-away, never held forever.
+                //   • UNFOCUSED → no one is watching, so holding a live pi for a window
+                //     is waste. Release it (idle + idle-release) and shut pi down; its
+                //     backstage pane closes and the daemon revives it (resume) on the
+                //     next unseen inbox entry.
+                if (focusOf(nodeId) !== null)
+                    return; // focused → stay alive, dormant
                 transition(nodeId, 'release');
                 try {
                     ctx?.shutdown?.();

package/dist/pi-extensions/canvas-view.d.ts

@@ -0,0 +1,21 @@
+interface CommandUI {
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+}
+interface CommandCtx {
+    mode: string;
+    ui: CommandUI;
+}
+interface PiLike {
+    registerCommand?(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: CommandCtx) => void | Promise<void>;
+    }): void;
+}
+/**
+ * Register the /view command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasView(pi: PiLike): void;
+export default registerCanvasView;

package/dist/pi-extensions/canvas-view.js

@@ -0,0 +1,75 @@
+// canvas-view.ts — pi extension registering the /view canvas command.
+//
+//   /view          — open the view picker (`crtr view pick`) as a tmux popup:
+//     a raw-ANSI list of every available view; Enter hands off (one-way exec)
+//     to `crtr view run <id>`, which paints the full-screen view inside the
+//     same popup. Quitting the view closes the popup back to THIS pi pane.
+//   /view <name>   — skip the picker and popup `crtr view run <name>` directly.
+//
+//   Views are stateless render surfaces with NO pi session. Unlike /resume-node
+//   this command MUST NOT touch the node-focus / swap-pane / reviveNode path
+//   (spec Decision 8) — there is no pane to return to and no session to revive.
+//   The popup is fire-and-forget: it owns its own screen and closes itself when
+//   the view exits, dropping back to the pi pane on its own.
+//
+// crtr ONLY runs inside tmux (see crouter/CLAUDE.md) — there is no non-tmux
+// fallback picker. Outside tmux the command notifies and no-ops.
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session, not a canvas node).
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles
+// inside crouter's own tsc build without a dep on the pi packages (mirrors
+// canvas-resume.ts / canvas-nav.ts / canvas-commands.ts).
+import { execFile } from 'node:child_process';
+/** Single-quote a string for safe interpolation into a `sh -c` command line —
+ *  tmux runs the display-popup trailing string through the shell, so a view
+ *  name with spaces or quotes must be escaped. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Register the /view command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export function registerCanvasView(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    if (typeof pi.registerCommand !== 'function')
+        return;
+    pi.registerCommand('view', {
+        description: 'Open a view in a popup — bare for the picker, or /view <name> to open that view directly',
+        handler: async (args, ctx) => {
+            // The popup is terminal-only — guard the run mode before opening it.
+            if (ctx.mode !== 'tui') {
+                try {
+                    ctx.ui.notify('/view needs the interactive TUI', 'warning');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            // crtr only runs in tmux: open the view (picker, or a named view) as a
+            // popup. It owns the screen and closes itself when the view exits,
+            // dropping back to THIS pi pane — no node-focus, no return-pane.
+            // Fire-and-forget: tmux runs the trailing string through sh -c.
+            if (process.env['TMUX'] !== undefined) {
+                const name = args.trim();
+                // bare /view → the picker; /view <name> → that view directly.
+                const cmd = name === '' ? 'crtr view pick' : `crtr view run ${shellQuote(name)}`;
+                try {
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            // Not in tmux → crtr is tmux-only, so there is nothing to fall back to.
+            try {
+                ctx.ui.notify('/view needs tmux', 'warning');
+            }
+            catch { /* best-effort */ }
+        },
+    });
+}
+export default registerCanvasView;

package/dist/prompts/skill.js

@@ -108,7 +108,7 @@ ${topicLine(topic)}
 - \`ls\` repo top level
 - check stack manifests
 - \`git log --oneline -15\` in this area
-- \`crtr skill find search "<topic>"\` / \`crtr skill find list\` — does a primer already exist?
+- \`crtr memory find "<topic>"\` / \`crtr memory list\` — does a primer already exist?
 
 If subsystem is small/self-evident, **stop**. Suggest a CLAUDE.md note. Primers
 are for large, complicated, or unintuitive systems only.
@@ -116,7 +116,7 @@ are for large, complicated, or unintuitive systems only.
 ## 2. Scope + name
 
 - **Scope**: \`project\` by default. \`user\` only if cross-repo.
-- **Name**: kebab-case. Confirm no collision: \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- **Name**: kebab-case. Confirm no collision: \`crtr memory read <name>\` (returns \`.path\`, \`.scope\`).
 
 ## 3. Parallel exploration
 
@@ -182,9 +182,8 @@ Domain terms, invariants, non-obvious constraints.
 Non-obvious coupling. Looks-broken-but-isn't. Past footguns.
 \`\`\`
 
-**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
-\`## Neighbors\` section on \`crtr skill read <name>\`. Add a manual \`## Related\`
-only for cross-plugin or distant refs.
+Add a \`## Related\` section only for genuinely related skills — cross-plugin
+or distant refs included; skip it when there is nothing worth pointing at.
 
 **Density rules:**
 - \`file:line\` over prose
@@ -200,9 +199,8 @@ only for cross-plugin or distant refs.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read <name> --no-body
-crtr skill read <name>
-crtr skill find search "<keyword>"    # confirm description triggers discovery
+crtr memory read <name>
+crtr memory find "<keyword>"    # confirm description triggers discovery
 \`\`\`
 
 Sharpen description if discovery misses. Cut body if bloated.
@@ -251,7 +249,7 @@ PR over many small ones for refactors here, because review churn dominates"*
 
 - **Scope**: \`user\` for cross-project methodology. \`project\` for repo-specific.
 - **Name**: kebab-case, verb-or-noun-phrase. Not "guide-to-X".
-- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr memory read <name>\` (returns \`.path\`, \`.scope\`).
 
 ## 3. Scaffold
 
@@ -301,9 +299,8 @@ to read the whole thing for value, you've buried the judgment.
 - **<name>**: what it looks like; how to avoid
 \`\`\`
 
-**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
-\`## Neighbors\` section on \`crtr skill read <name>\`. Add a manual \`## Related\`
-only for cross-plugin or distant refs.
+Add a \`## Related\` section only for genuinely related skills — cross-plugin
+or distant refs included; skip it when there is nothing worth pointing at.
 
 ## 6. Progressive disclosure
 
@@ -324,9 +321,8 @@ loads supporting files only when needed.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read <name> --no-body
-crtr skill read <name>
-crtr skill find search "<keyword>"
+crtr memory read <name>
+crtr memory find "<keyword>"
 \`\`\`
 
 ## Constraints
@@ -415,9 +411,8 @@ Or invent your own. Stay tight — no padding.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read <name> --no-body
-crtr skill read <name>
-crtr skill find search "<keyword>"
+crtr memory read <name>
+crtr memory find "<keyword>"
 \`\`\`
 
 ## Switch templates if needed
@@ -469,7 +464,7 @@ field/flag/code values** — pull verbatim from source.
 
 - **Scope**: \`user\` for cross-project facts. \`project\` for repo-specific.
 - **Name**: noun-phrase. \`http-status-codes\` not \`learn-http-status\`.
-- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr memory read <name>\` (returns \`.path\`, \`.scope\`).
 
 ## 3. Scaffold
 
@@ -530,9 +525,8 @@ SKILL.md links to siblings (\`see [full-table.md](full-table.md)\`).
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read <name> --no-body
-crtr skill read <name>
-crtr skill find search "<keyword>"
+crtr memory read <name>
+crtr memory find "<keyword>"
 \`\`\`
 
 Search must surface the skill on a typical lookup query. Sharpen the
@@ -582,7 +576,7 @@ push to \\\`main\\\`, wait for green CI, click promote"* is a runbook step.
 
 - **Scope**: \`project\` for repo-specific procedures. \`user\` for cross-project.
 - **Name**: verb-phrase. \`deploy-to-prod\` not \`production-deployment-guide\`.
-- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr memory read <name>\` (returns \`.path\`, \`.scope\`).
 
 ## 3. Scaffold
 
@@ -637,9 +631,8 @@ crtr skill author scaffold <name> --type runbook --scope <user|project> --descri
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read <name> --no-body
-crtr skill read <name>
-crtr skill find search "<keyword>"
+crtr memory read <name>
+crtr memory find "<keyword>"
 \`\`\`
 
 Walk through the runbook mentally. Each step verifiable? Each decision

package/dist/prompts/view.d.ts

@@ -0,0 +1,7 @@
+export interface ViewScaffoldVars {
+    id: string;
+    title: string;
+    description: string;
+}
+/** Build the `view.mjs` source for a freshly scaffolded view. */
+export declare function viewScaffold(v: ViewScaffoldVars): string;

package/dist/prompts/view.js

@@ -0,0 +1,101 @@
+// Scaffold stub for `crtr view new`. Returns the contents of a runnable
+// `view.mjs` — a minimal, self-contained ViewModule that runs as-is via
+// `crtr view run <name>` and prints a sane snapshot when piped (`| cat`).
+//
+// Authoring guidance lives INSIDE the stub (the comment block at the top of the
+// generated file), so a view author reads the contract right where they edit.
+/** Escape a value for embedding inside a single-quoted JS string literal. */
+function jsStr(s) {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/** Build the `view.mjs` source for a freshly scaffolded view. */
+export function viewScaffold(v) {
+    const id = jsStr(v.id);
+    const title = jsStr(v.title);
+    const description = jsStr(v.description);
+    return `// ${v.title} — a crtr view.
+//
+// A view is a self-contained ESM module the \`crtr view\` host loads and runs.
+//   Run it:   crtr view run ${v.id}          (interactive, inside tmux)
+//             crtr view run ${v.id} | cat    (static snapshot, exits 0)
+//
+// THE CONTRACT (the host injects everything — import NOTHING from crtr):
+//   manifest            { id, title, description, refreshMs?, keymap? }
+//                       id MUST equal this view's directory name.
+//   init(host)          build initial state — keep it CHEAP and sync-ish;
+//                       do NOT do slow fetches here (do them in refresh).
+//   refresh(state,host) async data load; the host runs it on launch, every
+//                       manifest.refreshMs (if set), and whenever a key handler
+//                       returns { type: 'refresh' }. Mutate state in place.
+//   render(state,draw,content)  paint into the \`content\` Rect via draw.* —
+//                       a pure read of state; NEVER write ANSI yourself.
+//   onKey(k,state,host) handle one keystroke; mutate state; return a ViewAction.
+//   dump(state)         plain text for the piped / non-TTY path (exit 0).
+//
+// draw API (all absolute cells inside \`content\`):
+//   draw.text(row,col,text,style?)            · draw.spans(row,col,spans,maxWidth?)
+//   draw.hline(row,fromCol?,toCol?)           · draw.box(rect,title?)
+//   draw.columns(rect,[1,2]) -> Rect[]        (proportional split)
+//   draw.list(rect,items,cursor,scroll) -> { scroll }   (windows + cursor row)
+//   style: { fg, bg, bold, dim, reverse }     (fg/bg honored only when color is on)
+// host API:
+//   host.options          CLI --flags, camelCased & stringified (e.g. options.port)
+//   host.setStatus(msg)   transient footer-left status; null clears it
+//   host.setError(msg)    sticky red banner above the footer; null clears it
+// ViewAction: { type: 'render' | 'refresh' | 'quit' | 'none' }
+
+/** @type {import('@crouton-kit/crouter/dist/core/tui/contract.js').ViewModule} */
+const view = {
+  manifest: {
+    id: '${id}',
+    title: '${title}',
+    description: '${description}',
+    // refreshMs: 30000,   // uncomment to auto-poll; omit ⇒ on-demand (g) only
+    keymap: [
+      { keys: 'g', label: 'refresh' },
+      { keys: 'q', label: 'quit' },
+    ],
+  },
+
+  init(host) {
+    // Cheap, synchronous setup. Stash CLI flags off host.options here.
+    return { count: 0, port: host.options.port ?? null };
+  },
+
+  async refresh(state, host) {
+    // Load your data here (shell out, fetch, read files). Mutate \`state\`.
+    state.count += 1;
+    host.setStatus(\`refreshed \${state.count}×\`);
+  },
+
+  render(state, draw, content) {
+    draw.text(content.row, content.col, '${title}', { bold: true });
+    draw.text(content.row + 2, content.col, \`refreshed \${state.count} time(s)\`);
+    draw.text(content.row + 3, content.col, \`port option: \${state.port ?? '(none)'}\`, { dim: true });
+    draw.text(
+      content.row + 5,
+      content.col,
+      'Edit view.mjs to build your view — g refreshes, q quits.',
+      { dim: true },
+    );
+  },
+
+  onKey(k, state, host) {
+    if (k.input === 'q') return { type: 'quit' };
+    if (k.input === 'g') return { type: 'refresh' };
+    return { type: 'none' };
+  },
+
+  dump(state) {
+    return [
+      '${title}',
+      '',
+      \`refreshed \${state.count} time(s)\`,
+      \`port option: \${state.port ?? '(none)'}\`,
+    ].join('\\n');
+  },
+};
+
+export default view;
+`;
+}

package/dist/types.d.ts

@@ -83,6 +83,10 @@ export interface ScopeConfig {
     auto_update: AutoUpdateConfig;
     max_panes_per_window: number;
     canvasNav: CanvasNavConfig;
+    /** Default to spawning nodes on the headless broker host instead of a tmux
+     *  pane. Off by default (tmux stays the default); `--headless` overrides it
+     *  per-spawn. Read at spawn via `readConfig('user').headless`. */
+    headless?: boolean;
 }
 export interface ScopeState {
     marketplaces: Record<string, {

package/dist/types.js

@@ -37,6 +37,7 @@ export function defaultScopeConfig() {
         auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
         max_panes_per_window: DEFAULT_MAX_PANES_PER_WINDOW,
         canvasNav: defaultCanvasNavConfig(),
+        headless: false,
     };
 }
 /** Built-in canvas-nav binds so an absent config still gives the intended UX.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
     "bin"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && cp -R src/builtin-skills dist/builtin-skills && cp -R src/builtin-personas dist/builtin-personas",
+    "build": "rm -rf dist && tsc && cp -R src/builtin-skills dist/builtin-skills && cp -R src/builtin-personas dist/builtin-personas && cp -R src/builtin-views dist/builtin-views && cp -R src/builtin-memory dist/builtin-memory",
     "dev": "tsx src/cli.ts",
     "link": "npm link",
     "prepublishOnly": "npm run build",
@@ -36,8 +36,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.15",
-    "commander": "^13.0.0"
+    "@crouton-kit/humanloop": "^0.3.16",
+    "@earendil-works/pi-ai": "^0.79.0",
+    "@earendil-works/pi-coding-agent": "^0.79.0",
+    "@earendil-works/pi-tui": "^0.79.0",
+    "commander": "^13.0.0",
+    "cron-parser": "5.5.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/commands/skill/find.d.ts

@@ -1,4 +0,0 @@
-export declare const findList: import("../../core/command.js").LeafDef;
-export declare const findSearch: import("../../core/command.js").LeafDef;
-export declare const findGrep: import("../../core/command.js").LeafDef;
-export declare const findBranch: import("../../core/command.js").BranchDef;