@crouton-kit/crouter 0.3.21 → 0.3.23

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

@@ -1,27 +1,40 @@
 // 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.)
+// HEADLESS RETARGET (foundation-spec §C.16 + §E). Wake-origin self-knowledge at
+// the DAEMON FIRING seams (the other half of the regression — wake-bearings.test.ts
+// covers the pure block in isolation). The observed gap: a scheduled wake arrived
+// indistinguishable from an ordinary message/spawn (Invariant D). Both seams are
+// now driven model-only — ZERO tmux, ZERO boot:
+//
+// (1) BUG LOCKED — a node woken or BORN by a TIMER must, by construction, learn a
+//     CLOCK (not an event) caused it: a noted wake rides a ⏰-marked inbox label
+//     (distinct from a plain `node msg`), and a spawn wake prepends the
+//     <crtr-wake> birth block (armer + cadence) to the newborn's kickoff while an
+//     ordinary `node new` carries none.
+//
+// (2) WHY MODEL-LEVEL, NOT TMUX CHROME — the noted seam is pure data layer
+//     (superviseTick's third pass → appendInbox; readInboxSince reads it back).
+//     The spawn-birth seam (spawn.ts) assembles the kickoff as
+//     `${buildWakeBearings(wakeOrigin)}\n\n${idBlock}${prompt}` ONLY when a
+//     wakeOrigin is present; `node new` passes none → no block. The load-bearing
+//     fact is the PURE rendering of buildWakeBearings for a spawn origin (and its
+//     absence without one) — reading it off a real booted pi's prompt was pure
+//     tmux/SDK overhead for a string a pure call already returns.
+//
+// (3) HOW THE DRIVE STILL FAILS IF THE BUG REGRESSES — drop the ⏰ label marker
+//     and the noted assert goes RED; drop the spawn-kind <crtr-wake> rendering
+//     and the spawn assert goes RED (the block / armer / cadence vanish).
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 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)), '..', '..', '..');
+import { buildWakeBearings } from '../runtime/bearings.js';
 function node(id) {
     return {
         node_id: id,
@@ -35,7 +48,6 @@ function node(id) {
         parent: null,
     };
 }
-// --- noted seam (no tmux) ---------------------------------------------------
 let home;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-wake-origin-'));
@@ -50,6 +62,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
+// --- noted seam (the daemon's third pass → inbox) ---------------------------
 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
@@ -72,39 +85,30 @@ test('a noted scheduled wake delivers a ⏰-marked inbox label, distinct from a
     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();
-    }
+// --- spawn-birth seam (the headline; spawn.ts kickoff assembly) -------------
+test('a spawn scheduled wake renders a <crtr-wake> birth block (armer + cadence); a plain node new renders none', async () => {
+    const armer = createNode(node('armer'));
+    // The spawn-birth seam (spawn.ts): the newborn's pi kickoff is
+    //   `${buildWakeBearings(wakeOrigin)}\n\n${idBlock}${prompt}`
+    // when a wakeOrigin is present, and just `${idBlock}${prompt}` (no block)
+    // when it is not. The daemon's third pass builds the WakeOrigin from the fired
+    // recurring `spawn` row via wakeOriginFrom; here we assert the block it yields.
+    const origin = {
+        kind: 'spawn',
+        ownerId: armer.node_id,
+        ownerName: 'armer',
+        armedAt: new Date(Date.now() - 1000).toISOString(),
+        recur: JSON.stringify({ every: '6h' }),
+    };
+    const block = buildWakeBearings(origin);
+    assert.match(block, /<crtr-wake>/, 'the born node learns a timer birthed it');
+    assert.match(block, /recurring spawn-cron armed by node /, 'names the armer role-explicitly');
+    assert.match(block, /firing every 6h/, 'surfaces the cadence');
+    assert.match(block, new RegExp(armer.node_id), 'the still-alive armer is named');
+    // CONTRAST: an ordinary `node new` passes NO wakeOrigin, so the conditional
+    // spawn.ts uses (`opts.wakeOrigin !== undefined ? buildWakeBearings(...) : ''`)
+    // prepends nothing — no <crtr-wake> in the newborn's kickoff.
+    const wakeBlock = (o) => (o !== undefined ? `${buildWakeBearings(o)}\n\n` : '');
+    assert.equal(wakeBlock(undefined), '', 'node new (no wakeOrigin) prepends no wake block');
+    assert.match(wakeBlock(origin), /<crtr-wake>/, 'a spawn wake prepends the block');
 });

package/dist/core/bridge-map.d.ts

@@ -0,0 +1,19 @@
+export interface BridgeSkillInput {
+    /** Source skill `name` frontmatter (identity only; not emitted as a field). */
+    name: string;
+    /** Source skill `description` frontmatter — the text we reshape + carry. */
+    description: string;
+    /** The skill body, copied verbatim below the generated frontmatter. */
+    body: string;
+}
+/** Reshape a Claude `description` into a read-routing sentence per
+ *  taste/why-field-means-why-to-read: "When <situation>, this skill should be
+ *  read [because <gist>]." Claude descriptions are typically
+ *  "<gist>. Use when <situation>." — we lift the use-when clause into the
+ *  situation and the preceding text into the payoff. With no explicit clause,
+ *  the whole description becomes the situation. */
+export declare function reshapeWhenAndWhy(description: string): string;
+/** Map a parsed Claude SKILL.md to a crouter substrate-doc string: full
+ *  frontmatter (kind/when-and-why/short-form/visibility/generator) + the copied
+ *  body. Deterministic and pure. */
+export declare function buildBridgeDoc(input: BridgeSkillInput): string;

package/dist/core/bridge-map.js

@@ -0,0 +1,73 @@
+// Claude SKILL.md → crouter substrate-doc mapping (design §2.3).
+// Pure, unit-testable. The bridge command (`crtr pkg bridge sync`) runs this
+// unattended every session, so the description→read-routing reshape is a
+// deterministic, conservative string rewrite — NOT a content paraphrase. An
+// author who wants durable tuning uses an INDEX (which the bridge never
+// touches), because a generator-stamped leaf is overwritten on the next sync.
+// "Use when …" / "Use this when …" / "This skill should be used when …" / "Used when …"
+const USE_WHEN_RE = /\b(?:use\s+this\s+skill\s+when|use\s+this\s+when|this\s+skill\s+should\s+be\s+used\s+when|used\s+when|use\s+when)\b\s*/i;
+/** Collapse whitespace, strip surrounding connective punctuation, and lowercase
+ *  a leading Capitalized word (but never an ACRONYM) so the clause reads inline
+ *  after "When " / "because ". */
+function cleanClause(s) {
+    let c = s.replace(/\s+/g, ' ').trim();
+    c = c.replace(/^[,;:.\s]+/, '').replace(/[,;:.\s]+$/, '');
+    if (/^[A-Z][a-z]/.test(c))
+        c = c.charAt(0).toLowerCase() + c.slice(1);
+    return c;
+}
+/** Reshape a Claude `description` into a read-routing sentence per
+ *  taste/why-field-means-why-to-read: "When <situation>, this skill should be
+ *  read [because <gist>]." Claude descriptions are typically
+ *  "<gist>. Use when <situation>." — we lift the use-when clause into the
+ *  situation and the preceding text into the payoff. With no explicit clause,
+ *  the whole description becomes the situation. */
+export function reshapeWhenAndWhy(description) {
+    const desc = description.replace(/\s+/g, ' ').trim();
+    if (desc === '')
+        return 'When this skill applies, this skill should be read.';
+    const m = desc.match(USE_WHEN_RE);
+    if (m && m.index !== undefined) {
+        const gist = cleanClause(desc.slice(0, m.index));
+        const situation = cleanClause(desc.slice(m.index + m[0].length));
+        if (situation !== '') {
+            let out = `When ${situation}, this skill should be read`;
+            if (gist !== '')
+                out += ` because ${gist}`;
+            return out + '.';
+        }
+    }
+    return `When ${cleanClause(desc)}, this skill should be read.`;
+}
+/** One-line short-form for the human inventory (never loaded into agent
+ *  context): the source description collapsed to a single line. */
+function toShortForm(description) {
+    return description.replace(/\s+/g, ' ').trim();
+}
+/** Always-double-quote a YAML scalar, escaping backslashes and quotes. The two
+ *  generated fields are single-line, so this is safe regardless of colons,
+ *  commas, or other YAML-significant characters. */
+function yamlQuote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Map a parsed Claude SKILL.md to a crouter substrate-doc string: full
+ *  frontmatter (kind/when-and-why/short-form/visibility/generator) + the copied
+ *  body. Deterministic and pure. */
+export function buildBridgeDoc(input) {
+    const whenAndWhy = reshapeWhenAndWhy(input.description);
+    const shortForm = toShortForm(input.description);
+    const fm = [
+        '---',
+        'kind: skill',
+        `when-and-why-to-read: ${yamlQuote(whenAndWhy)}`,
+        `short-form: ${yamlQuote(shortForm)}`,
+        'system-prompt-visibility: name',
+        'file-read-visibility: none',
+        'generator: claude-bridge',
+        '---',
+        '',
+    ].join('\n');
+    const body = input.body.replace(/^\n+/, '');
+    const trailing = body.endsWith('\n') ? '' : '\n';
+    return fm + '\n' + body + trailing;
+}

package/dist/core/canvas/history.d.ts

@@ -0,0 +1,91 @@
+import type { NodeStatus } from './types.js';
+export type HistorySource = 'report' | 'doc' | 'roadmap' | 'meta';
+/** One searchable unit of the episodic record: a report, a context doc, a
+ *  node's roadmap, or a node's meta (name/description/kind). */
+export interface HistoryArtifact {
+    /** Stable handle passed verbatim to `history read` — `<node-id>:<relpath>`. */
+    ref: string;
+    nodeId: string;
+    /** Path under the node dir (`reports/x.md`, `context/design.md`) or `meta`. */
+    relpath: string;
+    source: HistorySource;
+    /** final | update | urgent — reports only. */
+    reportKind?: string;
+    /** ISO 8601 artifact timestamp. */
+    ts: string;
+    /** Sort key: epoch ms of ts. */
+    tsMs: number;
+    /** Report title / doc first heading / node name. */
+    title: string;
+    nodeName: string;
+    nodeKind: string;
+    nodeStatus: NodeStatus;
+    nodeCwd: string;
+    nodeDesc: string;
+    /** Absolute file path; null for the synthetic `meta` artifact. */
+    path: string | null;
+    /** Frontmatter-stripped body, loaded once and cached. Empty on read error. */
+    loadBody: () => string;
+}
+export interface ScopeFilter {
+    /** A specific cwd. Default (all flags absent) = the caller's cwd. */
+    cwd?: string;
+    /** Every cwd on the canvas. */
+    allCwds?: boolean;
+    /** A node and its subscription descendants (one initiative / sub-DAG). */
+    under?: string;
+    /** Explicit node ids. */
+    nodes?: string[];
+}
+export interface CorpusFilter {
+    types?: HistorySource[];
+    /** Narrow reports to one report-kind (final | update). Implies type report. */
+    reportKind?: string;
+    /** Node kinds (developer, spec, …). */
+    kinds?: string[];
+    /** Node lifecycle statuses. */
+    statuses?: NodeStatus[];
+    /** Inclusive lower / upper bound on artifact ts, epoch ms. */
+    sinceMs?: number;
+    untilMs?: number;
+}
+/** The cwd the caller means by default: the calling node's cwd (resolved from
+ *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
+ *  when not run as a node. */
+export declare function callerCwd(): string;
+/** Build the searchable artifact set for a scope + corpus filter. Node facets
+ *  are applied against the db rows first (cheap); only surviving nodes' files
+ *  are read. */
+export declare function buildCorpus(scope: ScopeFilter, corpus: CorpusFilter): HistoryArtifact[];
+export interface ResolvedRef {
+    nodeId: string;
+    relpath: string;
+    source: HistorySource;
+    reportKind?: string;
+    ts: string;
+    nodeName: string;
+    /** Frontmatter-stripped body. */
+    body: string;
+    /** Raw file content (frontmatter included); null for meta. */
+    raw: string | null;
+    path: string | null;
+}
+/** Resolve a `<node-id>:<relpath>` handle to its content. Returns null when the
+ *  node is unknown or the artifact does not exist. Throws on path traversal. */
+export declare function resolveRef(ref: string): ResolvedRef | null;
+/** Enumerate one node's artifacts (for `history show`). */
+export declare function nodeArtifacts(nodeId: string, types?: HistorySource[]): HistoryArtifact[];
+export interface CorpusStats {
+    cwd: string;
+    nodes: number;
+    reports: number;
+    docs: number;
+    /** ISO date min → max across all artifacts, or null when empty. */
+    span: {
+        from: string;
+        to: string;
+    } | null;
+}
+/** Bounded per-cwd aggregate for the branch `-h` `<corpus>` block. Counts files
+ *  on disk without reading bodies. */
+export declare function corpusStats(cwd: string): CorpusStats;