@crouton-kit/crouter 0.3.26 → 0.3.28

package/dist/core/spawn.js

@@ -3,13 +3,30 @@
 // A small set of tmux primitives used by the `human` command tree to put the
 // humanloop TUI in a detached pane: spawnAndDetach (open a pane running a given
 // command), countPanesInCurrentWindow (placement decision), plus shellQuote and
-// isInTmux. The canvas runtime has its own one-window-per-node machinery in
-// core/runtime/tmux.ts; this module is only the pane-split path the human TUI
-// needs.
+// tmuxServerReachable. The canvas runtime has its own one-window-per-node
+// machinery in core/runtime/tmux.ts; this module is only the pane-split path the
+// human TUI needs.
 import { spawnSync } from 'node:child_process';
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export function isInTmux() {
     return Boolean(process.env.TMUX);
 }
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export function tmuxServerReachable() {
+    const r = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' });
+    return r.status === 0;
+}
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
@@ -34,7 +51,7 @@ export function countPanesInCurrentWindow() {
  *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
  *  False outside tmux / on error. */
 export function paneAlive(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return false;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
         encoding: 'utf8',
@@ -46,7 +63,7 @@ export function paneAlive(pane) {
  *  specify pane here"); only split-window -t takes a pane. null outside tmux /
  *  on a bad pane id / on error / empty. */
 export function paneWindowTarget(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return null;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
     if (r.status !== 0)
@@ -59,8 +76,6 @@ export function paneWindowTarget(pane) {
  *  to surface a human prompt in the user's view when nothing in the asking
  *  node's graph is focused. null outside tmux / no client / on error. */
 export function attachedClientPane() {
-    if (!isInTmux())
-        return null;
     const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
         encoding: 'utf8',
     });
@@ -102,10 +117,15 @@ export function scheduleKillCurrentPane(delaySeconds) {
  * as soon as the new pane is up; does NOT wait for the command to finish.
  */
 export function spawnAndDetach(opts) {
-    if (!isInTmux()) {
+    // Gate on the CANVAS tmux server's reachability, NOT the caller's $TMUX. A
+    // headless-broker child strips its own $TMUX (broker.ts) but the canvas server
+    // is on the default socket, so `split-window -t <pane>` against a resolved
+    // target pane (resolveHumanTarget) works fine from it. Only a genuine
+    // no-server case degrades to the inbox-drain follow-up.
+    if (!tmuxServerReachable()) {
         return {
             status: 'not-in-tmux',
-            message: 'handoff requires tmux (TMUX env var not set)',
+            message: 'handoff requires a reachable tmux server',
         };
     }
     const splitArgs = [];

package/dist/core/substrate/index.d.ts

@@ -1,4 +1,4 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, KIND_DEFAULT_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';

package/dist/core/substrate/index.js

@@ -1,15 +1,15 @@
 // substrate/ — the unified document-substrate keystone: the frontmatter schema,
-// the 4-rung visibility ladder, the kind→default-rungs table, the node-config
-// subject assembly, and gate evaluation. Pure + well-typed; the shared base the
-// CLI verbs, boot render, on-read render, and migrator all build on. See
-// design-substrate.md §4/§9 + plan-substrate.md §2.
+// the 4-rung visibility ladder, the node-config subject assembly, and gate
+// evaluation. Pure + well-typed; the shared base the CLI verbs, boot render,
+// on-read render, and migrator all build on. See design-substrate.md §4 +
+// plan-substrate.md §2.
 export { 
 // kinds
 KINDS, isDocKind, 
 // ladder
 RUNGS, rungRank, rungAtLeast, 
-// defaults
-KIND_DEFAULT_RUNGS, 
+// fallback floor
+FALLBACK_RUNG, 
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';

package/dist/core/substrate/injected-store.d.ts

@@ -0,0 +1,10 @@
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export declare function loadInjectedDocs(nodeId: string): Set<string>;
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export declare function saveInjectedDocs(nodeId: string, seen: Set<string>): void;
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export declare function clearInjectedDocs(nodeId: string): void;

package/dist/core/substrate/injected-store.js

@@ -0,0 +1,55 @@
+// injected-store.ts — durable per-node dedup set for on-read doc injection.
+//
+// The on-read substrate hook (canvas-doc-substrate.ts → renderOnReadDocs) dedups
+// so a given doc surfaces at most once per conversation. That set USED to live
+// only in the pi process heap, cleared on session_start. But a node's logical
+// session — the .jsonl transcript — spans MULTIPLE pi processes: a dormancy →
+// revive(resume) cycle exits the old process and launches a fresh `pi --session`
+// that REUSES the same transcript. The fresh process started with an empty set,
+// so any doc already injected before dormancy got injected AGAIN on the next
+// read — the "fires a second time per session" bug.
+//
+// This module persists the set to `nodes/<id>/injected-docs.json` so the resumed
+// process rehydrates it and skips docs already present in the transcript. The
+// launch paths that begin a FRESH transcript (reviveNode resume=false,
+// reviveInPlace, relaunchRootInPane — all in runtime/revive.ts) call
+// clearInjectedDocs(), so a new conversation starts with an empty set.
+//
+// All ops are best-effort: a failed read/write degrades to a possible re-inject,
+// never a crash — a dedup miss must never break a read or a revive.
+import { readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { injectedDocsPath } from '../canvas/paths.js';
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export function loadInjectedDocs(nodeId) {
+    try {
+        const arr = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
+        if (!Array.isArray(arr))
+            return new Set();
+        return new Set(arr.filter((x) => typeof x === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export function saveInjectedDocs(nodeId, seen) {
+    try {
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...seen]));
+    }
+    catch {
+        // best-effort — a failed persist only risks a re-inject, never a crash
+    }
+}
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export function clearInjectedDocs(nodeId) {
+    try {
+        rmSync(injectedDocsPath(nodeId), { force: true });
+    }
+    catch {
+        // ignore — absence is the desired state anyway
+    }
+}

package/dist/core/substrate/schema.d.ts

@@ -11,10 +11,7 @@ export declare function rungRank(r: Rung): number;
 /** Does rung `r` disclose at least as much as `min`? — e.g.
  *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
-export declare const KIND_DEFAULT_RUNGS: Record<DocKind, {
-    systemPrompt: Rung;
-    fileRead: Rung;
-}>;
+export declare const FALLBACK_RUNG: Rung;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -63,10 +60,11 @@ export interface SubstrateDoc extends SubstrateSchema {
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
- *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
- *  falls back to the kind default), so a renderer mapping over many docs never
- *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
 export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
  *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc

package/dist/core/substrate/schema.js

@@ -1,9 +1,16 @@
 // schema.ts — the typed shape of a substrate document's frontmatter, the
-// visibility ladder, the kind→default-rungs table, and the parse/validate
-// function that turns a resolved MemoryDoc into a fully-typed SubstrateDoc with
-// defaults applied. This is the keystone every downstream track (CLI verbs,
-// boot render, on-read render, migrator) builds against — pure and side-effect
-// free. See design-substrate.md §4 (schema) + §9 (defaults).
+// visibility ladder, and the parse/validate function that turns a resolved
+// MemoryDoc into a fully-typed SubstrateDoc. This is the keystone every
+// downstream track (CLI verbs, boot render, on-read render, migrator) builds
+// against — pure and side-effect free. See design-substrate.md §4 (schema).
+//
+// There is NO kind-based default for visibility: the right rung is a
+// case-by-case authoring call, so both rungs are required at authoring time
+// (enforced by `crtr memory write` on create and by `crtr memory lint`). The
+// runtime parser is tolerant by contract (it maps over many docs and must
+// never throw), so a doc missing/with an invalid rung falls back to the neutral
+// floor `none` — a malformed doc renders invisible rather than crashing, and
+// lint flags it. Valid docs never hit the fallback.
 // ---------------------------------------------------------------------------
 // Kinds — the three semantic kinds (design §3). `kind` is data, not a fork.
 // ---------------------------------------------------------------------------
@@ -28,44 +35,35 @@ export function rungAtLeast(r, min) {
     return rungRank(r) >= rungRank(min);
 }
 // ---------------------------------------------------------------------------
-// The kind→default-rungs table (design §9). When an author omits a visibility
-// field, its default is a function of `kind` — chosen so the common case is
-// correct with no thought and the migration is behavior-preserving for skills
-// and preferences. One data row per kind, NOT a code fork.
-//
-//   kind         system-prompt-visibility   file-read-visibility
-//   skill        name                       none
-//   preference   preview                    none
-//   reference    none                       preview
+// The neutral fallback rung used only when a doc omits a visibility field or
+// carries an invalid one. NOT a default an author may lean on — authoring-time
+// enforcement requires explicit rungs; this is purely the runtime parser's
+// never-throw floor (a malformed doc renders invisible, and lint flags it).
 // ---------------------------------------------------------------------------
-export const KIND_DEFAULT_RUNGS = {
-    skill: { systemPrompt: 'name', fileRead: 'none' },
-    preference: { systemPrompt: 'preview', fileRead: 'none' },
-    reference: { systemPrompt: 'none', fileRead: 'preview' },
-};
+export const FALLBACK_RUNG = 'none';
 // ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
- *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
- *  falls back to the kind default), so a renderer mapping over many docs never
- *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
 export function parseSubstrateFrontmatter(fm) {
     if (fm === null)
         return null;
     if (!isDocKind(fm.kind))
         return null;
     const kind = fm.kind;
-    const defaults = KIND_DEFAULT_RUNGS[kind];
     return {
         kind,
         whenAndWhyToRead: strField(fm['when-and-why-to-read']),
         shortForm: strField(fm['short-form']),
-        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], defaults.systemPrompt),
-        fileReadVisibility: parseRung(fm['file-read-visibility'], defaults.fileRead),
+        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], FALLBACK_RUNG),
+        fileReadVisibility: parseRung(fm['file-read-visibility'], FALLBACK_RUNG),
         gate: parseGate(fm.gate),
         appliesTo: parseAppliesTo(fm['applies-to']),
     };
@@ -95,8 +93,8 @@ export function previewLine(doc) {
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }
-/** Resolve a visibility field to a ladder rung, falling back to the kind
- *  default when absent/invalid. */
+/** Resolve a visibility field to a ladder rung, falling back to the neutral
+ *  floor when absent/invalid. */
 function parseRung(v, fallback) {
     return typeof v === 'string' && RUNGS.includes(v)
         ? v

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -36,6 +36,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { renderMemoryGuidance, renderOnReadDocs, renderPreferencesSection, renderSkillsSection, } from '../core/substrate/index.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
+import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -55,14 +56,19 @@ export function registerCanvasDocSubstrate(pi) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node — inert
-    // Per-session set of injected doc realpaths → a doc surfaces at most once per
-    // session across repeated reads. Cleared on every session_start (so a resume
-    // starts fresh, matching the on-read precedent).
-    // Also clears the per-session substrate parse cache so the corpus is re-scanned
-    // fresh for each new session (avoids stale docs after a skill/memory write).
-    const injectedDocs = new Set();
+    // Per-TRANSCRIPT set of injected doc realpaths → a doc surfaces at most once
+    // across the node's conversation, EVEN across a dormancy → revive(resume)
+    // cycle. A resume reuses the same .jsonl transcript in a NEW pi process, so
+    // the set is REHYDRATED from disk at process start (not started empty) and is
+    // NOT cleared on session_start — a resume continues the transcript, so the
+    // dedup must carry forward. The launch paths that begin a FRESH transcript
+    // (revive resume=false, reviveInPlace, relaunchRootInPane) delete the file, so
+    // a new conversation rehydrates empty here. See core/substrate/injected-store.ts.
+    const injectedDocs = loadInjectedDocs(nodeId);
     pi.on('session_start', () => {
-        injectedDocs.clear();
+        // Only the per-session substrate PARSE cache resets each session (so the
+        // corpus is re-scanned, picking up skill/memory writes). injectedDocs is
+        // transcript-scoped, not session-scoped — deliberately NOT cleared here.
         clearSessionCache();
     });
     // 1. BOOT system-prompt half — splice `<skills>` + `<preferences>` +
@@ -109,6 +115,9 @@ export function registerCanvasDocSubstrate(pi) {
             const injected = renderOnReadDocs(nodeId, absFile, injectedDocs);
             if (injected === '')
                 return; // nothing surfaced — pass the read through unchanged
+            // A doc surfaced → renderOnReadDocs grew injectedDocs; persist the set so
+            // the dedup survives a later dormancy → revive(resume).
+            saveInjectedDocs(nodeId, injectedDocs);
             // Prepend the surfacing docs ahead of the file contents.
             return { content: [{ type: 'text', text: injected }, ...event.content] };
         }

package/dist/pi-extensions/canvas-goal-capture.js

@@ -3,13 +3,23 @@
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
 //
-// A node spawned with a prompt has its goal persisted at birth (writeGoal in
-// spawn.ts). A bare root (`crtr` with no prompt) starts goal-less — its mandate
-// only arrives when the human types their first message. This extension closes
-// that gap: on the FIRST interactive user message, if the node has no goal yet,
-// it persists that message as context/initial-prompt.md. Subsequent messages
-// never clobber it (captureGoalIfAbsent is guarded), and a fresh-revive kickoff
-// prompt is skipped via its sentinel so it can never be mistaken for a mandate.
+// Two first-message jobs, both keyed off the node's first real `input` event:
+//
+//   1. Goal capture (bare roots). A node spawned with a prompt has its goal
+//      persisted at birth (writeGoal in spawn.ts). A bare root (`crtr` with no
+//      prompt) starts goal-less — its mandate only arrives when the human types
+//      their first message; this persists that as context/initial-prompt.md.
+//      Guarded so later messages never clobber it.
+//
+//   2. Naming (every node). Naming is async + event-driven — it does NOT run on
+//      the spawn path (that blocking LLM call froze the caller's terminal for
+//      2-3s on every spawn). On the first real message, if the node has no name
+//      yet, ask pi headlessly (async, non-blocking) for a kebab-case name and
+//      live-update the editor label. The first message may be a human's line OR
+//      a delegated child's kickoff task — naming off the agent prompt is fine.
+//
+// Both skip extension-injected messages (inbox wakes, steering) and the
+// fresh-revive kickoff (its sentinel), so neither is mistaken for a first input.
 //
 // Pure observation — it writes the goal file as a side effect and always lets
 // the message through unchanged (returns nothing ⇒ continue). Registered before
@@ -20,7 +30,7 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
 import { generateAndPersistName } from '../core/runtime/naming.js';
-import { editorLabel } from '../core/canvas/index.js';
+import { editorLabel, getNode } from '../core/canvas/index.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -34,26 +44,32 @@ export function registerCanvasGoalCapture(pi) {
             const nodeId = process.env['CRTR_NODE_ID'];
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
-            // Only a genuine human-typed prompt seeds the mandate — never an RPC or an
-            // extension-injected message (inbox wakes, steering nudges, kickoffs).
-            if (event.source !== 'interactive')
-                return;
             const text = (event.text ?? '').trim();
             if (text === '')
                 return;
-            // A fresh-revive kickoff is delivered as the launch prompt; never let it
-            // masquerade as the user's first mandate.
+            // Never seed a mandate or a name from an extension-injected message (inbox
+            // wakes, steering nudges) or a fresh-revive kickoff (the node is already
+            // named). Both would otherwise masquerade as the node's first real input.
+            if (event.source === 'extension')
+                return;
             if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
                 return;
-            // First mandate for a bare root: persist it as the goal, and ask pi
-            // (async, non-blocking) to name the session from it. The name lands on
-            // meta.description; the onNamed callback pushes the new editor label into
-            // THIS live session via setSessionName, so it updates immediately instead
-            // of only on the next cycle.
-            if (captureGoalIfAbsent(nodeId, text)) {
-                generateAndPersistName(nodeId, text, (meta) => {
+            // Goal capture is bare-root only: a delegated child already had its goal
+            // persisted at birth (writeGoal), so only a genuine human-typed prompt
+            // seeds a mandate here.
+            if (event.source === 'interactive')
+                captureGoalIfAbsent(nodeId, text);
+            // Naming: name the node from its FIRST real message — a human's first line
+            // OR a delegated child's kickoff task (naming off the agent prompt is
+            // fine) — whenever it has no name yet. Async headless `pi -p` with no
+            // canvas extensions, so it never recurses into another spawn/name. The
+            // onNamed callback live-updates THIS session's label instead of waiting
+            // for the next cycle. The unnamed-guard keeps it to one call per node.
+            const meta = getNode(nodeId);
+            if (meta !== null && (meta.description ?? '').trim() === '') {
+                generateAndPersistName(nodeId, text, (named) => {
                     try {
-                        pi.setSessionName?.(editorLabel(meta));
+                        pi.setSessionName?.(editorLabel(named));
                     }
                     catch { /* best-effort */ }
                 });