@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/__tests__/wake-origin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/wake-origin.test.js

@@ -0,0 +1,110 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/wake-origin.test.ts
+//
+// Wake-origin self-knowledge at the DAEMON FIRING seams (the other half of the
+// regression — wake-bearings.test.ts covers the pure block + the bare-revive
+// kickoff). The observed gap: a scheduled wake arrived indistinguishable from an
+// ordinary message/spawn (Invariant D). These lock the daemon's third pass:
+//   • noted  — the delivered inbox label carries the ⏰ scheduled-wake marker, so
+//     a timed note is distinguishable from a plain `node msg` (no tmux needed).
+//   • spawn  — a node BORN by a spawn wake gets the <crtr-wake> block prepended
+//     to its kickoff prompt (naming the armer + cadence); an ordinary `node new`
+//     spawn does NOT. The headline. (tmux-gated integration via the harness.)
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createNode } from '../canvas/canvas.js';
+import { armWake } from '../canvas/wakeups.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { superviseTick } from '../../daemon/crtrd.js';
+import { hasTmux, createHarness } from './helpers/harness.js';
+const CROUTER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent: null,
+    };
+}
+// --- noted seam (no tmux) ---------------------------------------------------
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-wake-origin-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('a noted scheduled wake delivers a ⏰-marked inbox label, distinct from a plain message', async () => {
+    const armer = createNode(node('armer'));
+    const target = createNode(node('tgt')); // no tmux placement → pass 1 skips it
+    armWake({
+        wakeup_id: 'wk-noted-1',
+        node_id: target.node_id,
+        owner_id: armer.node_id,
+        fire_at: new Date(Date.now() - 1000).toISOString(),
+        kind: 'noted',
+        recur: null,
+        payload: { body: 'CI should be green by now — check it', label: 'check CI' },
+    });
+    closeDb();
+    await superviseTick(Date.now());
+    closeDb();
+    const entries = readInboxSince(target.node_id);
+    assert.equal(entries.length, 1, 'the noted wake delivered exactly one inbox entry');
+    // Invariant D: the timer signal rides the VISIBLE label (digests never surface
+    // arbitrary data keys), so this is distinguishable from a plain `node msg`.
+    assert.equal(entries[0].label, '⏰ scheduled wake — check CI');
+    assert.notEqual(entries[0].label, 'check CI', 'a plain message would carry the bare label');
+});
+// --- spawn seam (the headline; tmux-gated integration) ----------------------
+test('a spawn scheduled wake births a node whose kickoff carries <crtr-wake>; node new does NOT', { skip: hasTmux() ? false : 'tmux unavailable' }, async () => {
+    const h = await createHarness();
+    try {
+        const armer = h.spawnRoot('armer');
+        // Contrast: an ordinary `node new` spawn — its kickoff has NO wake block.
+        const plainChild = await h.spawnChild(armer, 'plain task');
+        const plainBoot = await h.awaitBoot(plainChild);
+        assert.doesNotMatch(plainBoot.prompt ?? '', /<crtr-wake>/, 'node new carries no wake block');
+        // Arm a recurring spawn-cron (detached), fire one tick, inspect the BORN
+        // node's kickoff prompt (the message it actually wakes on).
+        const before = new Set(readdirSync(join(h.home, 'nodes')));
+        armWake({
+            wakeup_id: 'wk-spawn-1',
+            node_id: null, // canvas-detached deferred birth
+            owner_id: armer,
+            fire_at: new Date(Date.now() - 1000).toISOString(),
+            kind: 'spawn',
+            recur: JSON.stringify({ every: '6h' }),
+            payload: { kind: 'general', cwd: CROUTER, prompt: 'do the recurring job', parent: armer },
+        });
+        await h.tick(Date.now());
+        const born = readdirSync(join(h.home, 'nodes')).filter((d) => !before.has(d));
+        assert.equal(born.length, 1, 'exactly one node born from the spawn wake');
+        const bornBoot = await h.awaitBoot(born[0]);
+        const prompt = bornBoot.prompt ?? '';
+        assert.match(prompt, /<crtr-wake>/, 'the born node learns a timer birthed it');
+        assert.match(prompt, /recurring spawn-cron armed by node /, 'names the armer role-explicitly');
+        assert.match(prompt, /firing every 6h/, 'surfaces the cadence');
+        assert.match(prompt, new RegExp(armer), 'the still-alive armer is named');
+        assert.match(prompt, /do the recurring job/, 'the real task follows the block');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/bootstrap.js

@@ -30,7 +30,7 @@ const BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 function bootSkillBody() {
     return `---
 name: crtr-skills
-description: Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".
+description: 'Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".'
 argument-hint: [topic or verb]
 ---
 

package/dist/core/canvas/browse/__tests__/render.test.js

@@ -36,6 +36,7 @@ function state(over = {}) {
         cwdScope: null,
         sort: 'tree',
         preview: false,
+        residentsOnly: false,
         ...over,
     };
 }

package/dist/core/canvas/browse/app.js

@@ -11,7 +11,7 @@ import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAll, renderForest } from '../render.js';
 import { listNodes, subscriptionsOf } from '../canvas.js';
-import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from './terminal.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, TABS, SORTS } from './model.js';
 import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './render.js';
 /** Viewport (body) height = total rows minus the header renderFrame draws (see
@@ -52,6 +52,7 @@ export async function runBrowse(opts = {}) {
         cwdScope: launchCwd, // default: this dir
         sort: 'tree',
         preview: true, // default ON (decision)
+        residentsOnly: true, // default ON: hide one-shot workers (decision)
     };
     let visible = [];
     // Color capability is fixed for the session (it's a property of the tty/env).
@@ -89,6 +90,7 @@ export async function runBrowse(opts = {}) {
             tab: state.tab,
             query: state.query,
             cwdScope: state.cwdScope,
+            residentsOnly: state.residentsOnly,
             sort: state.sort,
         });
         if (keepId !== undefined) {
@@ -116,6 +118,7 @@ export async function runBrowse(opts = {}) {
             tree, visible, tab: state.tab, cursor: state.cursor, scrollOffset: state.scrollOffset,
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
+            residentsOnly: state.residentsOnly,
         }, size, caps);
         process.stdout.write(frame);
     };
@@ -146,6 +149,13 @@ export async function runBrowse(opts = {}) {
         state.cwdScope = state.cwdScope === null ? launchCwd : null;
         recompute(keep);
     };
+    // Toggle the resident-only lifecycle filter (hide/show one-shot worker nodes),
+    // keeping the selected node put when it survives the toggle.
+    const toggleResidents = () => {
+        const keep = curRow()?.id;
+        state.residentsOnly = !state.residentsOnly;
+        recompute(keep);
+    };
     const onKeySearch = (input, key) => {
         if (key.escape) {
             // Cancel the search: drop the query AND the relevance ranking it switched
@@ -284,7 +294,7 @@ export async function runBrowse(opts = {}) {
             flush();
             return;
         }
-        // Sort / scope / preview.
+        // Sort / scope / residents / preview.
         if (input === 's') {
             cycleSort();
             flush();
@@ -295,6 +305,11 @@ export async function runBrowse(opts = {}) {
             flush();
             return;
         }
+        if (input === 'r') {
+            toggleResidents();
+            flush();
+            return;
+        }
         if (input === 'p') {
             state.preview = !state.preview;
             flush();
@@ -322,6 +337,13 @@ export async function runBrowse(opts = {}) {
     // Boot. If the launch dir holds NO nodes, the default this-dir scope would show
     // a blank canvas — fall back to All dirs so browse is never empty on open.
     recompute();
+    // Relax the resident-only filter first (you're in this dir for a reason), then
+    // the cwd scope — so browse is never blank on open even if the launch dir holds
+    // only one-shot workers, or only nodes from other dirs.
+    if (visible.length === 0 && state.residentsOnly) {
+        state.residentsOnly = false;
+        recompute();
+    }
     if (visible.length === 0 && state.cwdScope !== null) {
         state.cwdScope = null;
         recompute();

package/dist/core/canvas/browse/model.d.ts

@@ -50,9 +50,36 @@ export declare function fuzzyMatch(query: string, text: string): boolean;
  *  the renderer can highlight them. Empty set when `query` is empty OR does not
  *  fully match (no partial highlights). */
 export declare function matchIndices(query: string, text: string): Set<number>;
+/** One word-wrapped preview line: its text + the column indices WITHIN that text
+ *  to highlight (the query match). */
+export interface SnippetLine {
+    text: string;
+    hi: Set<number>;
+}
+/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
+ *  when present (so "where does this text appear?" is answered exactly), else the
+ *  scattered subsequence indices, else empty (empty query). This is a different,
+ *  stricter model than the subsequence super-search on purpose — a contiguous span
+ *  is what reads as a highlight. */
+export declare function highlightIndices(query: string, text: string): Set<number>;
+/**
+ * Build the preview snippet for `text` under the live `query`: up to `maxLines`
+ * word-wrapped lines (each ≤ `width` cols), WINDOWED so the best match is visible
+ * (long conversations: the match can be thousands of chars in), with the matched
+ * columns flagged for highlight. Empty query (or empty text) → a plain wrap from
+ * the start with no highlight. The snippet string itself is what carries the
+ * highlight indices, so they never drift across the windowing.
+ */
+export declare function previewSnippet(query: string, text: string, width: number, maxLines: number): SnippetLine[];
+/** The searchable conversation text for a row: EVERY user prompt across the pi
+ *  session (`prompts`) when present, else the spawn prompt (`goal`) for a
+ *  never-revived node that has no session yet. Searched by super-search and
+ *  windowed in the preview, so search matches a prompt from ANYWHERE in the
+ *  conversation, not just the first one. */
+export declare function promptText(row: DashboardRow): string;
 /** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND the spawn prompt
- *  (`row.goal`). Empty query matches everything. */
+ *  folds in the pi-generated description), kind, short-id, AND every user prompt
+ *  in the conversation (`promptText`). Empty query matches everything. */
 export declare function queryMatch(query: string, row: DashboardRow): boolean;
 /** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
  *  exact > prefix > word-boundary substring > interior substring > subsequence.
@@ -76,12 +103,21 @@ export interface FlattenOpts {
      *  undefined = All dirs (no cwd filter). Like the tab predicate, it gates the
      *  matched set — ancestors from other dirs still render dimmed for tree context. */
     cwdScope?: string | null;
+    /** Lifecycle filter: when true, hide `terminal` (one-shot worker) nodes so only
+     *  the persistent `resident` agents you come back to show. The resume picker
+     *  defaults this ON. Undefined/false = every lifecycle. Gates the matched set
+     *  like the tab + cwd predicates (ancestors of a match still render for context). */
+    residentsOnly?: boolean;
     /** Ordering. `tree` keeps the spanning tree + ancestor context; `relevance` /
      *  `recency` produce a FLAT ranked list of directly-matched rows. */
     sort?: SortMode;
 }
 /** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
 export declare function cwdMatch(scope: string | null | undefined, row: DashboardRow): boolean;
+/** Is this row inside the active lifecycle filter? `residentsOnly` hides `terminal`
+ *  nodes; off (false/undefined) = every lifecycle. A row with an unknown lifecycle
+ *  (older snapshot field absent) is treated as resident so it is never hidden. */
+export declare function lifecycleMatch(residentsOnly: boolean | undefined, row: DashboardRow): boolean;
 /**
  * Flatten the tree to the ordered list of currently-visible rows.
  *

package/dist/core/canvas/browse/model.js

@@ -124,19 +124,133 @@ export function matchIndices(query, text) {
         out.clear(); // no full match → no highlight
     return out;
 }
+/** Chars of leading context kept before the match start when windowing. */
+const SNIPPET_LEAD = 12;
+/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
+ *  when present (so "where does this text appear?" is answered exactly), else the
+ *  scattered subsequence indices, else empty (empty query). This is a different,
+ *  stricter model than the subsequence super-search on purpose — a contiguous span
+ *  is what reads as a highlight. */
+export function highlightIndices(query, text) {
+    if (query === '')
+        return new Set();
+    const lower = text.toLowerCase();
+    const q = query.toLowerCase();
+    const sub = lower.indexOf(q);
+    if (sub >= 0) {
+        const out = new Set();
+        for (let i = sub; i < sub + q.length; i++)
+            out.add(i);
+        return out;
+    }
+    return matchIndices(query, text);
+}
+/** Greedy word-wrap of single-spaced `s` (caller normalizes whitespace) to `width`
+ *  cols × `maxLines` lines, returning each line's text AND its start offset in `s`.
+ *  Only the single space at each wrap break is dropped, so a highlight index maps
+ *  to a line column as `idx - line.start` with no drift across the wrap. */
+function wrapTracked(s, width, maxLines) {
+    const out = [];
+    if (width <= 0 || maxLines <= 0)
+        return out;
+    const n = s.length;
+    let i = 0;
+    while (i < n && out.length < maxLines) {
+        const lineStart = i;
+        let lineEnd = i; // exclusive end of committed words
+        let j = i;
+        while (j < n) {
+            let ws = j;
+            while (ws < n && s[ws] === ' ')
+                ws++;
+            let we = ws;
+            while (we < n && s[we] !== ' ')
+                we++;
+            if (ws === we)
+                break; // only trailing spaces remain
+            if (we - lineStart <= width || lineEnd === lineStart) {
+                lineEnd = we; // include this word (always take ≥1; a huge word is clipped below)
+                j = we;
+            }
+            else
+                break;
+        }
+        let text = s.slice(lineStart, lineEnd);
+        if (text.length > width)
+            text = text.slice(0, width);
+        out.push({ text, start: lineStart });
+        i = lineEnd;
+        if (i < n && s[i] === ' ')
+            i++; // drop the single break space
+    }
+    return out;
+}
+/**
+ * Build the preview snippet for `text` under the live `query`: up to `maxLines`
+ * word-wrapped lines (each ≤ `width` cols), WINDOWED so the best match is visible
+ * (long conversations: the match can be thousands of chars in), with the matched
+ * columns flagged for highlight. Empty query (or empty text) → a plain wrap from
+ * the start with no highlight. The snippet string itself is what carries the
+ * highlight indices, so they never drift across the windowing.
+ */
+export function previewSnippet(query, text, width, maxLines) {
+    const norm = text.replace(/\s+/g, ' ').trim();
+    if (norm === '' || width <= 0 || maxLines <= 0)
+        return [];
+    // 1. Locate the match in the normalized text + choose a window start that keeps
+    //    a little leading context, snapped to a word boundary.
+    let matchStart = -1;
+    if (query !== '') {
+        const sub = norm.toLowerCase().indexOf(query.toLowerCase());
+        if (sub >= 0)
+            matchStart = sub;
+        else {
+            const ix = matchIndices(query, norm);
+            if (ix.size > 0)
+                matchStart = Math.min(...ix);
+        }
+    }
+    let windowStart = 0;
+    if (matchStart > SNIPPET_LEAD) {
+        let s = matchStart - SNIPPET_LEAD;
+        while (s < matchStart && norm[s] !== ' ')
+            s++; // forward to the next word boundary
+        windowStart = s < matchStart ? s + 1 : matchStart;
+    }
+    const snippet = (windowStart > 0 ? '… ' : '') + norm.slice(windowStart);
+    // 2. Recompute highlight indices on the FINAL snippet string (no drift), then
+    //    word-wrap with offset tracking and split the highlight into per-line cols.
+    const hi = highlightIndices(query, snippet);
+    return wrapTracked(snippet, width, maxLines).map(({ text: lt, start }) => {
+        const lhi = new Set();
+        for (const idx of hi)
+            if (idx >= start && idx < start + lt.length)
+                lhi.add(idx - start);
+        return { text: lt, hi: lhi };
+    });
+}
 function shortId(id) {
     return id.slice(0, 8);
 }
+/** The searchable conversation text for a row: EVERY user prompt across the pi
+ *  session (`prompts`) when present, else the spawn prompt (`goal`) for a
+ *  never-revived node that has no session yet. Searched by super-search and
+ *  windowed in the preview, so search matches a prompt from ANYWHERE in the
+ *  conversation, not just the first one. */
+export function promptText(row) {
+    return row.prompts ?? row.goal ?? '';
+}
 /** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND the spawn prompt
- *  (`row.goal`). Empty query matches everything. */
+ *  folds in the pi-generated description), kind, short-id, AND every user prompt
+ *  in the conversation (`promptText`). Empty query matches everything. */
 export function queryMatch(query, row) {
     if (query === '')
         return true;
+    const prompt = promptText(row);
     return (fuzzyMatch(query, row.name) ||
         fuzzyMatch(query, row.kind) ||
         fuzzyMatch(query, shortId(row.node_id)) ||
-        (row.goal !== undefined && fuzzyMatch(query, row.goal)));
+        (prompt !== '' && fuzzyMatch(query, prompt)));
 }
 // ---------------------------------------------------------------------------
 // Relevance scoring (super-search)
@@ -159,23 +273,30 @@ export function fieldScore(query, text) {
     }
     return fuzzyMatch(q, t) ? 0.2 : 0; // scattered subsequence
 }
-/** Per-field weights — name (handle + description) dominates, the spawn prompt
- *  is the long-tail super-search field. */
-const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, goal: 1.5 };
+/** Per-field weights — name (handle + description) dominates, the conversation
+ *  prompts are the long-tail super-search field. */
+const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, prompt: 1.5 };
 /** Weighted relevance of a row to the query across all searched fields. 0 means
  *  no field matched (excluded from relevance results, same as `queryMatch`). */
 export function scoreRow(query, row) {
     if (query === '')
         return 0;
+    const prompt = promptText(row);
     return (FIELD_WEIGHTS.name * fieldScore(query, row.name) +
         FIELD_WEIGHTS.kind * fieldScore(query, row.kind) +
         FIELD_WEIGHTS.id * fieldScore(query, shortId(row.node_id)) +
-        FIELD_WEIGHTS.goal * (row.goal !== undefined ? fieldScore(query, row.goal) : 0));
+        FIELD_WEIGHTS.prompt * (prompt !== '' ? fieldScore(query, prompt) : 0));
 }
 /** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
 export function cwdMatch(scope, row) {
     return scope === null || scope === undefined || row.cwd === scope;
 }
+/** Is this row inside the active lifecycle filter? `residentsOnly` hides `terminal`
+ *  nodes; off (false/undefined) = every lifecycle. A row with an unknown lifecycle
+ *  (older snapshot field absent) is treated as resident so it is never hidden. */
+export function lifecycleMatch(residentsOnly, row) {
+    return residentsOnly !== true || row.lifecycle !== 'terminal';
+}
 /**
  * Flatten the tree to the ordered list of currently-visible rows.
  *
@@ -189,11 +310,14 @@ export function cwdMatch(scope, row) {
  * always reachable.
  */
 export function flatten(tree, opts) {
-    const { collapsed, tab, query, cwdScope, sort = 'tree' } = opts;
-    // 1. Directly-matched nodes: tab predicate AND cwd scope AND query.
+    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree' } = opts;
+    // 1. Directly-matched nodes: tab predicate AND cwd scope AND lifecycle AND query.
     const matched = new Set();
     for (const [id, node] of tree.nodes) {
-        if (tabPredicate(tab, node.row) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
+        if (tabPredicate(tab, node.row) &&
+            cwdMatch(cwdScope, node.row) &&
+            lifecycleMatch(residentsOnly, node.row) &&
+            queryMatch(query, node.row)) {
             matched.add(id);
         }
     }

package/dist/core/canvas/browse/render.d.ts

@@ -1,19 +1,10 @@
 import type { Tab, Tree, VisibleRow, SortMode } from './model.js';
+import { detectColorCaps, type ColorCaps } from '../../tui/draw.js';
+export { detectColorCaps };
+export type { ColorCaps };
 export declare const PREVIEW_BODY = 5;
 export declare const PREVIEW_HEIGHT: number;
 export declare function headerHeight(search: boolean): number;
-export interface ColorCaps {
-    /** Any hue (fg/bg color) allowed. */
-    color: boolean;
-    /** 256-color bg allowed — drives the subtle cursor-row background. */
-    color256: boolean;
-}
-/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
- *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
- *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
-export declare function detectColorCaps(stream?: {
-    isTTY?: boolean;
-}, env?: NodeJS.ProcessEnv): ColorCaps;
 export interface RenderState {
     tree: Tree;
     visible: VisibleRow[];
@@ -29,6 +20,9 @@ export interface RenderState {
     sort: SortMode;
     /** Whether the bottom preview panel is drawn. */
     preview: boolean;
+    /** Lifecycle filter: when true, `terminal` (one-shot worker) nodes are hidden
+     *  — surfaced as a status-line cue. */
+    residentsOnly: boolean;
 }
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints