@north-light/crouter 0.3.262 → 0.3.269

package/dist/core/canvas/node-recap.js

@@ -0,0 +1,67 @@
+// node-recap.ts — the node's last Goal/State briefing, persisted.
+//
+// The recap itself is generated in the broker (`pi-extensions/canvas-recap.ts`)
+// and painted above the editor as throwaway chrome. That widget lives in broker
+// memory, so the moment a node goes dormant its briefing is gone — which is
+// exactly when a developer scanning `crtr canvas browse` needs it most ("what was
+// this one for, and where did it stop?"). Persisting the two lines the viewer
+// already produced makes them readable without a broker and without a model call.
+//
+// Stored beside telemetry in `job/` because it is machine-generated runtime
+// state, not a document the node authored: safe to delete, rebuilt on the node's
+// next idle recap. `context/` stays the agent's own document space.
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { jobDir } from './paths.js';
+import { readJsonIfExists, atomicWriteJson } from '../fs-utils.js';
+function recapPath(nodeId) {
+    return join(jobDir(nodeId), 'recap.json');
+}
+/** Strip one leading `Goal:` / `State:` label from a briefing line. */
+function stripLabel(line) {
+    return line.replace(/^\s*(goal|state)\s*:\s*/i, '').trim();
+}
+/** Split the model's two-line briefing into its labelled halves. Returns null for
+ *  anything that doesn't yield at least one non-empty line — a garbled recap is
+ *  worse than none, so it is never stored. Missing labels fall back to line order
+ *  (the prompt asks for Goal first, State second). */
+export function parseRecapBriefing(briefing) {
+    const lines = briefing.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+    if (lines.length === 0)
+        return null;
+    const labelled = (prefix) => lines.find((l) => new RegExp(`^${prefix}\\s*:`, 'i').test(l));
+    const goalLine = labelled('goal') ?? lines[0];
+    const stateLine = labelled('state') ?? (lines[1] !== goalLine ? lines[1] : undefined);
+    const goal = goalLine === undefined ? '' : stripLabel(goalLine);
+    const state = stateLine === undefined ? '' : stripLabel(stateLine);
+    if (goal === '' && state === '')
+        return null;
+    return { goal, state };
+}
+/** Persist a freshly generated briefing. Best-effort — a write failure only costs
+ *  the browse preview one stale panel, so it must never disturb the broker. */
+export function writeNodeRecap(nodeId, briefing) {
+    const parsed = parseRecapBriefing(briefing);
+    if (parsed === null)
+        return;
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        atomicWriteJson(recapPath(nodeId), { ...parsed, at: new Date().toISOString() });
+    }
+    catch {
+        /* best-effort: the recap is regenerated on the node's next idle window */
+    }
+}
+/** The node's stored briefing, or undefined when it never generated one (a node
+ *  that finished before its first idle window, or one last run before this file
+ *  existed). Never throws. */
+export function readNodeRecap(nodeId) {
+    const raw = readJsonIfExists(recapPath(nodeId));
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const goal = typeof raw.goal === 'string' ? raw.goal : '';
+    const state = typeof raw.state === 'string' ? raw.state : '';
+    if (goal === '' && state === '')
+        return undefined;
+    return { goal, state, at: typeof raw.at === 'string' ? raw.at : '' };
+}

package/dist/core/canvas/render-source.d.ts

@@ -1,4 +1,5 @@
 import type { CanvasSource } from './source.js';
+import { type NodeRecap } from './node-recap.js';
 import { type Fault } from '../runtime/fault.js';
 import type { NodeStatus, Lifecycle, NodeMeta, NodeRow, TerminalReason } from './types.js';
 export declare function activeFaultForDisplay<T extends {
@@ -69,6 +70,15 @@ export interface DashboardRow {
      *  by loadPreview (same single session read as `prompts`); undefined for a node whose
      *  session has no assistant reply yet. Shown in the preview's reply block. */
     lastAssistant?: string;
+    /** The node's last persisted Goal/State briefing (`job/recap.json`, written by the
+     *  broker's recap extension). Populated LAZILY by loadPreview; undefined for a node
+     *  that never generated one. The preview's fastest "what is this / where is it" line. */
+    recap?: NodeRecap;
+    /** The newest report the node pushed (`reports/<ts>-<id>-<kind>.md`). Populated
+     *  LAZILY by loadPreview; undefined when the node has pushed nothing. Residents push
+     *  updates as they work, so this is the last thing the node deliberately DELIVERED —
+     *  usually crisper than its last assistant message. */
+    report?: NodeReportPreview;
     /** True when the node is GENUINELY mid-turn right now — its `busy` marker exists
      *  AND its broker pid is alive (not merely an `active`, between-turns node). The
      *  live "is it generating?" cue. Computed on the cheap boot path for LIVE nodes
@@ -93,8 +103,30 @@ export interface DashboardRow {
     /** Lazy-enrichment guard (internal): true once loadPreview has read goal + the
      *  session (prompts + lastAssistant). Idempotency marker for the selected row. */
     previewLoaded?: boolean;
+    /** The source `NodeRow` this row was built from (dashboardRowFromNodeRow only).
+     *  Carries every column listNodes already fetched — the runtime fields
+     *  (host_kind/parent/waiting_for/final_report/finalized_at/pi_pid) plus the
+     *  mirrored identity fields (description/cycles) — so the snapshot handler
+     *  reads them here instead of opening meta.json.
+     *  Undefined for rows built by other paths (dashboardRowsFromSource). */
+    srcRow?: NodeRow;
 }
 export declare function readGoalText(nodeId: string): string | undefined;
+/** The newest pushed report, reduced to what a preview panel can use. */
+export interface NodeReportPreview {
+    /** final | update | urgent (frontmatter, else the filename suffix). */
+    kind: string;
+    /** ISO 8601 push time (frontmatter, else the filename stamp). */
+    ts: string;
+    /** The report's first markdown heading, or its first non-empty line. */
+    heading: string;
+    /** The body after that heading, whitespace-normalized + capped. */
+    body: string;
+}
+/** The node's newest report, read straight off disk. Report filenames lead with a
+ *  compact timestamp, so the lexicographic maximum is the latest one — no stat of
+ *  the whole directory. Never throws; undefined when the node pushed nothing. */
+export declare function readNewestReport(nodeId: string): NodeReportPreview | undefined;
 interface SessionParts {
     prompts?: string;
     lastAssistant?: string;
@@ -137,8 +169,8 @@ export declare function dashboardRowsFromSource(source: CanvasSource, rootId: st
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
  *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
-export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>): Promise<DashboardRow[]>;
-export declare function enrichRowsFromSource(source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
+export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean): Promise<DashboardRow[]>;
+export declare function enrichRowsFromSource(_source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
 /** goal (initial-prompt.md) and session parts are local disk reads — suppressed
  *  to undefined for a remote source. */
 export declare function loadPreviewFromSource(source: CanvasSource, row: DashboardRow): Promise<DashboardRow>;

package/dist/core/canvas/render-source.js

@@ -9,14 +9,16 @@
 // migrated onto these `*FromSource` variants directly.
 //
 // ALLOWED imports (verified openDb-free): node:fs/path, ./pid.js, ./labels.js,
-// ./status-glyph.js, ../runtime/fault.js, ./paths.js, ./remote-canvas-source.js,
-// and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
+// ./status-glyph.js, ./node-recap.js, ../runtime/fault.js, ../frontmatter.js,
+// ./paths.js, ./remote-canvas-source.js, and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
 // ./focuses.js, or ./db.js here — that is the whole point of the split.
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
-import { jobDir, contextDir } from './paths.js';
+import { jobDir, contextDir, reportsDir } from './paths.js';
+import { readNodeRecap } from './node-recap.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { isPidAlive } from './pid.js';
 import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
@@ -168,6 +170,63 @@ export function readGoalText(nodeId) {
         return undefined;
     }
 }
+const REPORT_BODY_CAP = 1024;
+/** Compact report stamp `20260810T190533286` → an ISO 8601 instant. */
+function reportStampToIso(stamp) {
+    const m = stamp.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})?$/);
+    if (m === null)
+        return undefined;
+    return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.${m[7] ?? '000'}Z`;
+}
+/** The node's newest report, read straight off disk. Report filenames lead with a
+ *  compact timestamp, so the lexicographic maximum is the latest one — no stat of
+ *  the whole directory. Never throws; undefined when the node pushed nothing. */
+export function readNewestReport(nodeId) {
+    let newest;
+    try {
+        for (const f of readdirSync(reportsDir(nodeId))) {
+            if (!f.endsWith('.md'))
+                continue;
+            if (newest === undefined || f > newest)
+                newest = f;
+        }
+    }
+    catch {
+        return undefined; // no reports dir
+    }
+    if (newest === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(join(reportsDir(nodeId), newest), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const { data, body } = parseFrontmatterGeneric(raw);
+    const name = newest.replace(/\.md$/, '');
+    const kind = typeof data?.['kind'] === 'string'
+        ? data['kind']
+        : (name.split('-').pop() ?? 'report');
+    const ts = typeof data?.['ts'] === 'string'
+        ? data['ts']
+        : (reportStampToIso(name.split('-')[0] ?? '') ?? '');
+    // The heading is the report's own headline; everything after it is the detail the
+    // preview shows next, so a panel never repeats the heading twice.
+    const lines = body.split('\n');
+    let heading = '';
+    let rest = body;
+    for (let i = 0; i < lines.length; i++) {
+        const t = (lines[i] ?? '').trim();
+        if (t === '')
+            continue;
+        heading = t.startsWith('#') ? t.replace(/^#+\s*/, '').trim() : t;
+        rest = lines.slice(i + 1).join('\n');
+        break;
+    }
+    const text = rest.replace(/\s+/g, ' ').trim();
+    return { kind, ts, heading, body: text.length > REPORT_BODY_CAP ? text.slice(0, REPORT_BODY_CAP) : text };
+}
 /** The node's session-derived preview text in ONE file read (today's two reads,
  *  folded): EVERY user prompt across the pi session (`prompts` — the whole
  *  conversation, not just the spawn prompt) AND the LAST assistant message text
@@ -385,8 +444,9 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
     return {
         node_id: row.node_id,
-        name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        name: fullName(row), // description is a row column (v38) — no meta read needed
         handle: row.name,
+        description: row.description,
         status: row.status,
         frozen_at: row.frozen_at ?? null,
         terminal_reason: row.terminal_reason ?? null,
@@ -403,6 +463,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,
         viewed: remote ? false : focusedNodeIds.has(row.node_id) || hasLiveBrokerViewer(row),
+        srcRow: row,
     };
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root), read
@@ -443,33 +504,29 @@ export async function dashboardRowsFromSource(source, rootId) {
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
  *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
-export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set()) {
+export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set(), liveOnly = false) {
     const remote = source instanceof RemoteCanvasSource;
     const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;
-    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
+    const rows = await source.listNodes(liveOnly ? { status: ['active', 'idle'] } : undefined);
+    return rows.map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
-// Lazy enrichment (source-driven) — fold expensive per-node reads into rows on
-// demand. Ask counts are supplied by the caller (`asks` — a pre-fetched
-// `ticketCountsForView` map merged across the visible roots), NOT scanned here
-// (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) + goal/session
-// are LOCAL disk reads, suppressed for a `RemoteCanvasSource`.
-export async function enrichRowsFromSource(source, rows, asks) {
+// Lazy enrichment (source-driven) — fold the per-node reads the cheap boot skips
+// into rows on demand. Ask counts are supplied by the caller (`asks` — a
+// pre-fetched `ticketCountsForView` map merged across the visible roots), NOT
+// scanned here (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) is
+// a LOCAL disk read, suppressed for a `RemoteCanvasSource`.
+//
+// This does NO source read. The label fields it used to re-fetch per node
+// (name/handle/description) are set by the row builders: `description` became a
+// nodes-table column in v38, so both builders already hold the full label and a
+// per-node getNode here would re-read what the caller's single listNodes returned.
+export async function enrichRowsFromSource(_source, rows, asks) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)
         return;
-    const remote = source instanceof RemoteCanvasSource;
+    const remote = _source instanceof RemoteCanvasSource;
     const askMap = asks ?? {};
-    // A full dashboard may contain thousands of rows. Keep source reads serial:
-    // ApiCanvasSource turns each into a unix-socket request, and an unbounded
-    // Promise.all can overflow crtrd's accept backlog then spuriously trigger
-    // the client's cold-daemon path even though the daemon is still running.
     for (const row of todo) {
-        const meta = await source.getNode(row.node_id);
-        if (meta !== null) {
-            row.name = fullName(meta);
-            row.handle = meta.name;
-            row.description = meta.description;
-        }
         row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = askMap[row.node_id] ?? 0;
         row.enriched = true;
@@ -487,6 +544,8 @@ export async function loadPreviewFromSource(source, row) {
         const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
         row.prompts = prompts;
         row.lastAssistant = lastAssistant;
+        row.recap = readNodeRecap(row.node_id);
+        row.report = readNewestReport(row.node_id);
     }
     row.previewLoaded = true;
     return row;

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

@@ -292,6 +292,15 @@ export type NodeMeta = NodeIdentity & NodeRuntime;
 export interface NodeRow {
     node_id: string;
     name: string;
+    /** The pi-generated first-task description; see NodeIdentity.description.
+     *  Durable IDENTITY mirrored to the row (like `cwd`/`host_kind`) so a roster
+     *  read can build the full display label without opening meta.json. Absent for
+     *  a node not yet named — the column's NULL is mapped to undefined at `rowFrom`
+     *  so identity, row, and DTO all spell "unnamed" the same way. */
+    description?: string;
+    /** Relaunch count; see NodeIdentity.cycles. Mirrored to the row for the same
+     *  reason as `description`; absent on a row written before this column. */
+    cycles?: number;
     kind: string;
     mode: Mode;
     lifecycle: Lifecycle;

package/dist/core/config.d.ts

@@ -2,12 +2,12 @@ import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanAc
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
-export declare function readConfig(scope: Scope): ScopeConfig;
+export declare function readConfig(scope: Scope): ResolvedScopeConfig;
 /** Read the config that lives at an EXACT scope-root dir, rather than the
  *  resolved nearest root for a scope. Lets a caller iterate each visible
  *  project root's own config when several are in scope (nested `.crouter` dirs
  *  or a profile-widened stack), instead of collapsing them onto the nearest. */
-export declare function readConfigAtRoot(root: string): ScopeConfig;
+export declare function readConfigAtRoot(root: string): ResolvedScopeConfig;
 export declare function readState(scope: Scope): ScopeState;
 type RawConfig = Record<string, unknown>;
 export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): RawConfig;
@@ -26,6 +26,14 @@ export declare function ensureScopeInitialized(scope: Scope, root: string): void
 /** Normalize the user-owned list of attach actions allowed to bridge through an
  * occupied tmux root binding. Unknown and non-attach ids have no effect. */
 export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+type LegacyModelRouteConfig = Omit<ModelRouteConfig, 'models'> & {
+    models: Partial<Record<ModelStrength, string>>;
+};
+/** Read configuration exposes legacy sparse routes separately during the
+ * one-release cutover; launch code only treats `modelRoutes` as complete. */
+export type ResolvedScopeConfig = ScopeConfig & {
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
+};
 /** One malformed `bin` declaration. The read path retains these as doctor
  *  findings rather than letting malformed config break a node launch. */
 export interface BinDeclarationIssue {
@@ -103,7 +111,11 @@ export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> |
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
+    /** Complete declared routes. Every route here has all four strengths. */
     modelRoutes?: Record<string, ModelRouteConfig>;
+    /** Read-only compatibility view for sparse routes written before complete
+     * routes were required. New route persistence never produces this shape. */
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
     modelRouting?: ModelRoutingConfig;
     /** The merged `spawnEnv.allow` set (project stack > profile > user >
      *  builtin, additive) — read by `buildOperationalEnvBase`
@@ -185,6 +197,11 @@ export declare function persistModelLadders(root: string, patch: {
     anthropic?: Partial<Record<ModelStrength, string>>;
     openai?: Partial<Record<ModelStrength, string>>;
 }): void;
+/** Persist one complete route at one exact config root. The route is the only
+ * raw route entry touched; unrelated routes and local ladder defaults remain
+ * absent. Pass `undefined` to remove this scope's entry, which resumes lower
+ * scope inheritance rather than introducing a tombstone. */
+export declare function persistModelRoute(root: string, routeId: string, route: ModelRouteConfig | undefined): void;
 /** Mutate one exact config root. Setup uses this for profile and explicit
  * project targets that cannot be represented by the user/project Scope enum. */
 export declare function updateConfigAtRoot(root: string, mutate: (cfg: ScopeConfig) => void): ScopeConfig;