@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/runtime/kickoff.js

@@ -6,18 +6,22 @@
 // conversation already holds the context).
 //
 // Layout (the framing a revived node sees):
-//   <goal file=…>…</goal>                  the mandate it was spawned with
-//   <roadmap file=…>…</roadmap>            its evolving plan
+//   <roadmap file=…>…</roadmap>            its evolving plan — the source of truth
 //   <context-dir path=…>…</context-dir>    what artifacts exist on disk
 //   <feed>Awaiting N nodes … digest</feed> who it waits on + unread reports
 //   <yield-message>…</yield-message>       the note its prior self left on yield
 //
-// The goal + yield-message are companion files in the node's context dir; the
+// The roadmap (NOT the original spawn prompt) carries the goal on a refresh: its
+// frozen core holds goal + exit criteria, its body the live plan. context/
+// initial-prompt.md is NEVER injected into a node's prompts — it lives on disk
+// purely as a log of the original mandate; by the time a node is running it is
+// usually stale, and the roadmap is the doc the node keeps current. The
 // yield-message is one-shot (consumed on the next revive).
 import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync, } from 'node:fs';
 import { join } from 'node:path';
-import { contextDir, getNode, subscriptionsOf, } from '../canvas/index.js';
+import { contextDir, getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
+import { personaDrift, commitPersonaAck } from './persona.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
 // ---------------------------------------------------------------------------
 // Companion context files: the goal (the spawning mandate) and the one-shot
@@ -41,6 +45,24 @@ export function writeGoal(nodeId, text) {
     mkdirSync(contextDir(nodeId), { recursive: true });
     writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
 }
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export function captureGoalIfAbsent(nodeId, text) {
+    const existing = readGoal(nodeId);
+    if (existing !== null && existing.trim() !== '')
+        return false;
+    const body = text.trim();
+    if (body === '')
+        return false;
+    writeGoal(nodeId, body);
+    return true;
+}
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export const REVIVE_KICKOFF_SENTINEL = 'You have been revived fresh after a context refresh';
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
 export function yieldMessagePath(nodeId) {
@@ -73,62 +95,114 @@ export function listContextDir(nodeId) {
         return [];
     return readdirSync(dir).sort();
 }
-// ---------------------------------------------------------------------------
-// Feed block — who the node is awaiting, plus a drained digest of unread
-// reports. Draining here advances the cursor: the revived node has now "read"
-// the feed, so a later `crtr feed read` shows only what arrives afterward.
-// ---------------------------------------------------------------------------
-function feedBlock(nodeId) {
+/** Drain the one-shot revive bearings for `meta`: consume the yield note, advance
+ *  the feed cursor past the unread reports, and capture+commit any external
+ *  persona drift. The CONSUMING step of a fresh revive — the revive paths call it
+ *  ONCE, then pass the result to buildReviveKickoff (which is then pure; building
+ *  twice eats nothing). Calling drainBearings a second time would drain an
+ *  already-empty note/feed, so ONLY the revive paths call it. */
+export function drainBearings(meta) {
+    const nodeId = meta.node_id;
+    // Consume the one-shot yield note (deleted on read) BEFORE the kickoff lists
+    // the context dir, so it never shows up there.
+    const yieldMsg = consumeYieldMessage(nodeId);
+    // Drain the feed: read unread since the cursor and advance it past them, so a
+    // later `crtr feed read` shows only what arrives afterward.
+    const cursor = readCursor(nodeId);
+    const entries = readInboxSince(nodeId, cursor);
+    let unreadDigest = null;
+    if (entries.length > 0) {
+        writeCursor(nodeId, entries[entries.length - 1].ts);
+        unreadDigest = coalesce(entries);
+    }
+    // Capture + commit any external persona drift (the second of the two delivery
+    // sites). Committing the ack here is the mutation; the guidance is surfaced by
+    // the pure builder from this captured value.
+    const drift = personaDrift(nodeId);
+    let driftGuidance = null;
+    if (drift !== null) {
+        driftGuidance = drift.guidance;
+        commitPersonaAck(nodeId, drift.to);
+    }
+    return { yieldMsg, unreadDigest, driftGuidance };
+}
+/** Render the <feed> block PURELY: the live "awaiting" roster (a read) plus the
+ *  already-drained unread digest (from drainBearings). No cursor write here. */
+function feedBlock(nodeId, unreadDigest) {
     // Awaiting = active subscriptions whose publisher is still live (active|idle).
     const awaiting = subscriptionsOf(nodeId)
         .filter((s) => s.active)
         .map((s) => getNode(s.node_id))
         .filter((m) => m !== null && (m.status === 'active' || m.status === 'idle'));
     const lines = [];
-    lines.push(`Awaiting ${awaiting.length} node${awaiting.length === 1 ? '' : 's'}.`);
-    for (const m of awaiting)
-        lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
-    const cursor = readCursor(nodeId);
-    const entries = readInboxSince(nodeId, cursor);
-    if (entries.length > 0) {
-        writeCursor(nodeId, entries[entries.length - 1].ts);
-        lines.push('', coalesce(entries));
+    if (awaiting.length > 0) {
+        const n = awaiting.length;
+        const subj = n === 1 ? 'it is' : 'they are';
+        const pron = n === 1 ? 'it' : 'they';
+        const verb = n === 1 ? 'pushes' : 'push';
+        // State aliveness + the automatic wake at the source. Bare status ("— active")
+        // left earlier revives unsure whether the worker was really live, so they
+        // burned a turn on `feed read`/`feed peek` to confirm. Asserting it here
+        // removes the reason to check.
+        lines.push(`Awaiting ${n} node${n === 1 ? '' : 's'} — ${subj} alive and running right now, and will wake you the moment ${pron} ${verb}. The wake is automatic; nothing to check, poll, or verify.`);
+        for (const m of awaiting)
+            lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
+        lines.push('', unreadDigest ??
+            '(no unread reports yet — expected while they run: a worker leaves no pointer until it pushes, so an empty feed means still working, not stalled)');
     }
     else {
-        lines.push('', '(no unread reports)');
+        lines.push('Awaiting 0 nodes.');
+        lines.push('', unreadDigest ?? '(no unread reports)');
     }
     return `<feed>\n${lines.join('\n')}\n</feed>`;
 }
 // ---------------------------------------------------------------------------
 // buildReviveKickoff — assemble the full fresh-revive first message.
 // ---------------------------------------------------------------------------
-/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
- *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
- *  disk and frames them so the revived node can rebuild its bearings in one
- *  turn. Side effects: consumes the yield message and advances the feed cursor
- *  (both are "read" by surfacing them here). */
-export function buildReviveKickoff(meta) {
+/** Assemble the auto-injected first message for a FRESH revive of `meta` from its
+ *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
+ *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
+ *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
+ *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
+export function buildReviveKickoff(meta, bearings) {
     const nodeId = meta.node_id;
-    // Consume the one-shot yield note first so it never shows in the dir listing.
-    const yieldMsg = consumeYieldMessage(nodeId);
     const parts = [
-        'You have been revived fresh after a context refresh — your previous in-memory ' +
+        `${REVIVE_KICKOFF_SENTINEL} — your previous in-memory ` +
             'context is gone, by design. Everything below was just read from disk; it is your ' +
             'full bearings. Rebuild from it and continue toward your goal.',
     ];
-    const goal = readGoal(nodeId);
-    if (goal !== null && goal.trim() !== '') {
-        parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
-    }
+    // The roadmap is the source of truth on a fresh revive: its frozen core holds
+    // the goal/exit criteria, its body the live plan the node kept current. The
+    // original spawn prompt (context/initial-prompt.md) is deliberately NOT injected
+    // — it lives on disk only as a log, and by now it is usually stale.
     const roadmap = readRoadmap(nodeId);
     parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${roadmap !== null && roadmap.trim() !== '' ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
     const files = listContextDir(nodeId);
     parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
-    parts.push(feedBlock(nodeId));
-    parts.push(yieldMsg !== null
-        ? `<yield-message>\n${yieldMsg.trim()}\n</yield-message>`
+    parts.push(feedBlock(nodeId, bearings.unreadDigest));
+    parts.push(bearings.yieldMsg !== null
+        ? `<yield-message>\n${bearings.yieldMsg.trim()}\n</yield-message>`
         : '<yield-message/>');
-    parts.push('If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
-        'if the goal is met, or end your turn to stay dormant awaiting your workers.');
+    // A node that reports UP the spine (has subscribers awaiting its result)
+    // finishes with `push final`. A human-attended node (no subscribers — a root
+    // conversation working directly with the user) has no result to submit and
+    // must not be told to finish: it stays resident and keeps working with the
+    // user.
+    const reportsUp = subscribersOf(nodeId).length > 0;
+    parts.push(reportsUp
+        ? 'If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
+            'if the goal is met, or end your turn to stay dormant awaiting your workers.'
+        : 'If there is work to do, perform it. Otherwise end your turn — you are working ' +
+            'directly with the user, so stay available and continue the conversation when they ' +
+            'write back.');
+    // Persona-transition catch-up. If the node's mode/lifecycle was changed
+    // EXTERNALLY while it was dormant (e.g. a human ran `crtr node lifecycle` /
+    // `node promote --node` on it), it never saw the turn_end injector. drainBearings
+    // captured the guidance for its new persona and committed the ack (the second
+    // and only other delivery site); we just surface it. A clean fresh revive has
+    // no drift, so this is empty unless a real external change happened.
+    if (bearings.driftGuidance !== null) {
+        parts.push(`<persona-transition>\nYour role was changed while you were away. ${bearings.driftGuidance}\n</persona-transition>`);
+    }
     return parts.join('\n\n');
 }

package/dist/core/runtime/launch.d.ts

@@ -1,17 +1,33 @@
-import type { NodeMeta, LaunchSpec, Mode } from '../canvas/index.js';
+import type { NodeMeta, LaunchSpec, Mode, Lifecycle } from '../canvas/index.js';
 export declare const CANVAS_STOPHOOK_PATH: string;
 export declare const CANVAS_INBOX_WATCHER_PATH: string;
 export declare const CANVAS_NAV_PATH: string;
+export declare const CANVAS_GOAL_CAPTURE_PATH: string;
+export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
+export declare const CANVAS_CONTEXT_INTRO_PATH: string;
+export declare const CANVAS_COMMANDS_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
- *  graph chrome). All self-gate on CRTR_NODE_ID. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  context-intro (inject the <crtr-context> bearings block as its own session
+ *  message, once per brand-new chat), commands (the /promote slash-command).
+ *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
+ *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
 export declare function normalizeModel(model: string): string;
-/** Compose a node's full pi launch recipe from its persona. The two canvas
- *  extensions are always first; persona-declared extensions follow. */
-export declare function buildLaunchSpec(kind: string, mode: Mode, opts?: {
+/** Compose a node's full pi launch recipe from its persona. The system prompt
+ *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
+ *  (terminal/resident — the finish contract) and spine position (hasManager —
+ *  whether the push-up family is taught at all). Callers pass the authoritative
+ *  lifecycle + hasManager (`parent !== null`) so a polymorph/flip rebuilds the
+ *  prompt faithfully. The two canvas extensions are always first; persona-
+ *  declared extensions follow. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
+    lifecycle: Lifecycle;
+    hasManager: boolean;
     extraEnv?: Record<string, string>;
 }): {
     launch: LaunchSpec;
@@ -26,9 +42,16 @@ export interface PiInvocation {
 }
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.
- *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - fork start: pass `forkFrom` (absolute .jsonl path or partial uuid) to `--fork`
+ *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
+ *    is delivered as the next message. One-shot at birth: the node thereafter
+ *    captures its OWN pi_session_file and revives by `--session` like any other.
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path, preferred)
+ *    or `resumeSessionId` (bare uuid fallback) to `--session` (keeps conversation).
  *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
 export declare function buildPiArgv(meta: NodeMeta, opts?: {
     prompt?: string;
     resumeSessionId?: string;
+    resumeSessionPath?: string;
+    forkFrom?: string;
 }): PiInvocation;

package/dist/core/runtime/launch.js

@@ -2,15 +2,17 @@
 //
 // pi-only. No claude branch — we are a super-opinionated system. A node's
 // LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
-// replays to revive it faithfully: `--resume` to wake a done/idle node (keeps
-// its conversation), or fresh (against the context dir) for a refresh-yield.
+// replays to revive it faithfully: `--session <id>` to wake a done/idle node
+// (keeps its conversation), or fresh (against the context dir) for a refresh-yield.
 // The spec is rewritten on every polymorph (base→orchestrator) so a node
 // always comes back as its *current* self.
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolve as resolvePersona } from '../personas/index.js';
 import { nodeEnv } from './nodes.js';
+import { editorLabel } from '../canvas/index.js';
+import { nodeDir } from '../canvas/paths.js';
 // ---------------------------------------------------------------------------
 // The two canvas pi-extensions every node loads. They self-gate on the live
 // {kind,mode} env, so the worker→orchestrator polymorph flips hook behavior
@@ -27,13 +29,26 @@ function resolveExtension(name) {
 export const CANVAS_STOPHOOK_PATH = resolveExtension('canvas-stophook');
 export const CANVAS_INBOX_WATCHER_PATH = resolveExtension('canvas-inbox-watcher');
 export const CANVAS_NAV_PATH = resolveExtension('canvas-nav');
+export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
+export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
+export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
+export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
- *  graph chrome). All self-gate on CRTR_NODE_ID. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  context-intro (inject the <crtr-context> bearings block as its own session
+ *  message, once per brand-new chat), commands (the /promote slash-command).
+ *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
+ *  reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
     CANVAS_STOPHOOK_PATH,
     CANVAS_INBOX_WATCHER_PATH,
     CANVAS_NAV_PATH,
+    CANVAS_GOAL_CAPTURE_PATH,
+    CANVAS_PASSIVE_CONTEXT_PATH,
+    CANVAS_CONTEXT_INTRO_PATH,
+    CANVAS_COMMANDS_PATH,
 ];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -46,10 +61,15 @@ export function normalizeModel(model) {
 // ---------------------------------------------------------------------------
 // Build the launch spec from {kind, mode}
 // ---------------------------------------------------------------------------
-/** Compose a node's full pi launch recipe from its persona. The two canvas
- *  extensions are always first; persona-declared extensions follow. */
-export function buildLaunchSpec(kind, mode, opts = {}) {
-    const p = resolvePersona(kind, mode);
+/** Compose a node's full pi launch recipe from its persona. The system prompt
+ *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
+ *  (terminal/resident — the finish contract) and spine position (hasManager —
+ *  whether the push-up family is taught at all). Callers pass the authoritative
+ *  lifecycle + hasManager (`parent !== null`) so a polymorph/flip rebuilds the
+ *  prompt faithfully. The two canvas extensions are always first; persona-
+ *  declared extensions follow. */
+export function buildLaunchSpec(kind, mode, opts) {
+    const p = resolvePersona(kind, mode, { lifecycle: opts.lifecycle, hasManager: opts.hasManager });
     const launch = {
         model: p.model !== undefined ? normalizeModel(p.model) : undefined,
         tools: p.tools,
@@ -59,9 +79,34 @@ export function buildLaunchSpec(kind, mode, opts = {}) {
     };
     return { launch, lifecycle: p.lifecycle, skills: p.skills };
 }
+// ---------------------------------------------------------------------------
+// Build the pi argv to launch / revive a node
+// ---------------------------------------------------------------------------
+/** Persist a node's (possibly large) system prompt to a file in its node dir and
+ *  return the absolute path, so callers can pass a short path to pi instead of
+ *  the inline text. Returns null if the write fails — the caller then falls back
+ *  to passing the prompt inline. Rewritten every launch so a polymorph's updated
+ *  prompt always lands. */
+function writeSystemPromptFile(nodeId, prompt) {
+    try {
+        const dir = nodeDir(nodeId);
+        mkdirSync(dir, { recursive: true });
+        const p = join(dir, 'system-prompt.md');
+        writeFileSync(p, prompt, 'utf8');
+        return p;
+    }
+    catch {
+        return null;
+    }
+}
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.
- *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - fork start: pass `forkFrom` (absolute .jsonl path or partial uuid) to `--fork`
+ *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
+ *    is delivered as the next message. One-shot at birth: the node thereafter
+ *    captures its OWN pi_session_file and revives by `--session` like any other.
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path, preferred)
+ *    or `resumeSessionId` (bare uuid fallback) to `--session` (keeps conversation).
  *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
 export function buildPiArgv(meta, opts = {}) {
     const spec = meta.launch;
@@ -69,15 +114,42 @@ export function buildPiArgv(meta, opts = {}) {
     for (const ext of spec?.extensions ?? CANVAS_EXTENSIONS) {
         argv.push('-e', ext);
     }
-    argv.push('-n', meta.name);
-    if (opts.resumeSessionId !== undefined)
-        argv.push('--resume', opts.resumeSessionId);
+    argv.push('-n', editorLabel(meta));
+    // pi's `--resume` is a bare toggle that opens the interactive picker; the
+    // flag that resumes a *specific* session is `--session <path|id>`. Prefer the
+    // absolute FILE path when present: pi resolves a bare id cwd-relative first
+    // and shows a cross-project "Fork? [y/N]" prompt when the revive cwd differs
+    // from the session's creation cwd, whereas a path (contains `/` or ends
+    // `.jsonl`) is opened directly — immune to any cwd discrepancy. The bare uuid
+    // is the fallback for older nodes booted before pi_session_file was captured.
+    // `--fork <path|id>` is the spawn-time branch: pi copies the source session
+    // into a fresh one for this node (the source is untouched), then delivers the
+    // kickoff prompt as the next message. Mutually exclusive with `--session`
+    // (resume) — fork wins when both are somehow set, but in practice a spawn
+    // never resumes and a revive never forks.
+    if (opts.forkFrom !== undefined && opts.forkFrom !== '') {
+        argv.push('--fork', opts.forkFrom);
+    }
+    else {
+        const resumeArg = opts.resumeSessionPath ?? opts.resumeSessionId;
+        if (resumeArg !== undefined)
+            argv.push('--session', resumeArg);
+    }
     if (spec?.model !== undefined)
         argv.push('--model', spec.model);
     if (spec?.tools !== undefined && spec.tools.length > 0)
         argv.push('--tools', spec.tools.join(','));
     if (spec?.systemPrompt !== undefined && spec.systemPrompt !== '') {
-        argv.push('--append-system-prompt', spec.systemPrompt);
+        // pi's --append-system-prompt reads a FILE when the arg is an existing path,
+        // else treats the arg as literal text. Pass the prompt as a file path, not
+        // inline: an orchestrator persona is ~17KB, and passed inline it inflates the
+        // `tmux new-window 'pi …'` command past tmux's command-length limit, so the
+        // spawn dies with "command too long" and the node is marked dead before pi
+        // ever starts (base workers fit, orchestrator children don't). Writing it to
+        // the node dir keeps the command tiny. Falls back to inline if the write
+        // fails (e.g. an ephemeral meta with no node dir).
+        const promptArg = writeSystemPromptFile(meta.node_id, spec.systemPrompt) ?? spec.systemPrompt;
+        argv.push('--append-system-prompt', promptArg);
     }
     if (opts.prompt !== undefined && opts.prompt !== '')
         argv.push(opts.prompt);

package/dist/core/runtime/lifecycle.d.ts

@@ -0,0 +1,13 @@
+import type { NodeMeta } from '../canvas/types.js';
+/** The lifecycle events — the only vocabulary for moving a node's status/intent.
+ *  Each maps (in the table below) to a target status and/or intent plus the set
+ *  of from-statuses it is legal from. */
+export type LifecycleEvent = 'finalize' | 'reap' | 'cancel' | 'crash' | 'yield' | 'release' | 'revive' | 'boot';
+/** Enact a lifecycle event on a node: validate the from-status against the
+ *  table, then write status+intent in ONE atomic statement (so they can never
+ *  disagree). Returns the hydrated node view after the write.
+ *
+ *  Throws on an unknown node, or on an ILLEGAL move (e.g. `finalize` on a `dead`
+ *  node) — illegal states are unrepresentable. The throw is a real signal:
+ *  callers that previously swallowed db-mutation errors now surface them. */
+export declare function transition(nodeId: string, event: LifecycleEvent): NodeMeta;

package/dist/core/runtime/lifecycle.js

@@ -0,0 +1,86 @@
+// lifecycle.ts — the node status×intent state machine.
+//
+// ONE place defines which (status, intent) moves are legal and enacts them.
+// Before this, ~a dozen scattered setStatus()/setIntent() pairs across
+// reset/close/revive/feed/daemon/stophook/queue/promote re-derived the lifecycle
+// by hand, with no shared definition of "what move is legal." Here the legal
+// transition TABLE is the definition, and `transition(id, event)` is the single
+// writer of status+intent: it validates the from-status, then writes both fields
+// in ONE atomic statement (built on Phase 2's WAL'd row setters) so the two can
+// never disagree.
+//
+// This mirrors persona.ts: persona.ts is the single source of transition PROSE;
+// lifecycle.ts is the single source of which status/intent move is LEGAL. Two
+// parallel, legible state machines instead of scattered enactment.
+//
+// Crash-safety invariant (was a comment repeated in reset/close/reapDescendants):
+// "flip status to a non-supervised value + clear intent BEFORE killing the
+// window" — the daemon only ever revives active|idle nodes, so a teardown must
+// leave the node done/canceled first to close the revive race. That invariant is
+// now the DEFINITION of the `reap`/`cancel` events: callers flip via transition()
+// and only THEN kill the window.
+//
+// Layering note: lifecycle.ts is runtime, but it is the canvas write surface's
+// `transition` verb (the only writer of status+intent), so it owns its atomic
+// row UPDATE directly via openDb — the one sanctioned exception to "only
+// canvas.ts touches the db" (see canvas/CLAUDE.md), exactly as db.ts's backfill
+// is the sanctioned exception for a data migration.
+import { openDb, getNode } from '../canvas/index.js';
+const ANY = '*';
+/** The supervised statuses — a live node the daemon watches. */
+const LIVE = ['active', 'idle'];
+/** The legal transition table — derived directly from the (status, intent) pairs
+ *  the runtime actually wrote at its audited call sites, so behavior is preserved
+ *  by construction. Each entry's comment names its writer(s). */
+const TRANSITIONS = {
+    // feed.push(final) · queue.cancelJob · markCleanExitDone (clean quit).
+    finalize: { status: 'done', intent: 'done', from: LIVE },
+    // reapDescendants · relaunchRoot park-old. Forced teardown → done, intent cleared.
+    reap: { status: 'done', intent: null, from: ANY },
+    // closeNode cascade. Forced teardown → canceled, intent cleared.
+    cancel: { status: 'canceled', intent: null, from: ANY },
+    // daemon superviseTick: window gone with no yield/release intent. Intent KEPT
+    // (the dead log line still reports it).
+    crash: { status: 'dead', from: LIVE },
+    // requestYield · relaunchRoot new-node safety net. Status KEPT (already active).
+    yield: { intent: 'refresh', from: LIVE },
+    // stophook idle-release: free the window, stay woken by the inbox.
+    release: { status: 'idle', intent: 'idle-release', from: LIVE },
+    // reviveNode · resetRoot · stophook boot-confirm (clear a pending refresh net).
+    revive: { status: 'active', intent: null, from: ANY },
+    // reviveInPlace: re-exec a fresh pi in the SAME pane. Status (re)affirmed
+    // active; intent KEPT so a pending refresh survives as proof-of-boot until the
+    // fresh pi's session_start clears it (a premature clear is how a failed
+    // respawn became a silent death — see revive.ts).
+    boot: { status: 'active', from: LIVE },
+};
+/** Enact a lifecycle event on a node: validate the from-status against the
+ *  table, then write status+intent in ONE atomic statement (so they can never
+ *  disagree). Returns the hydrated node view after the write.
+ *
+ *  Throws on an unknown node, or on an ILLEGAL move (e.g. `finalize` on a `dead`
+ *  node) — illegal states are unrepresentable. The throw is a real signal:
+ *  callers that previously swallowed db-mutation errors now surface them. */
+export function transition(nodeId, event) {
+    const spec = TRANSITIONS[event];
+    const cur = getNode(nodeId);
+    if (cur === null)
+        throw new Error(`transition: unknown node ${nodeId}`);
+    if (spec.from !== ANY && !spec.from.includes(cur.status)) {
+        throw new Error(`illegal lifecycle transition: '${event}' from status='${cur.status}' (node ${nodeId})`);
+    }
+    const writeStatus = Object.prototype.hasOwnProperty.call(spec, 'status');
+    const writeIntent = Object.prototype.hasOwnProperty.call(spec, 'intent');
+    const db = openDb();
+    if (writeStatus && writeIntent) {
+        db.prepare('UPDATE nodes SET status = ?, intent = ? WHERE node_id = ?')
+            .run(spec.status, spec.intent ?? null, nodeId);
+    }
+    else if (writeStatus) {
+        db.prepare('UPDATE nodes SET status = ? WHERE node_id = ?').run(spec.status, nodeId);
+    }
+    else if (writeIntent) {
+        db.prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(spec.intent ?? null, nodeId);
+    }
+    return getNode(nodeId);
+}

package/dist/core/runtime/memory.d.ts

@@ -0,0 +1,43 @@
+/** The node-local index template. Named export kept for callers/tests that
+ *  assert the seeded node store verbatim. */
+export declare const MEMORY_TEMPLATE: string;
+/** The user-global index template — framed around the human, not a goal. */
+export declare const USER_MEMORY_TEMPLATE: string;
+/** The project index template — framed around the repo. */
+export declare const PROJECT_MEMORY_TEMPLATE: string;
+/** The node-local memory directory in a node's context dir — holds MEMORY.md
+ *  (the index) and the one-fact detail files it points at. */
+export declare function memoryDir(nodeId: string): string;
+/** The node-local MEMORY.md index path (inside the memory dir). */
+export declare function memoryPath(nodeId: string): string;
+/** Whether the node has a node-local memory store. This is ALSO the
+ *  orchestrator gate: only orchestrators are ever seeded one, so a node with no
+ *  node-local store is a terminal worker (no memory framing at all). */
+export declare function hasMemory(nodeId: string): boolean;
+/** Read the node-local MEMORY.md index, or null when it doesn't exist. */
+export declare function readMemory(nodeId: string): string | null;
+/** Seed the node-local memory dir + index IF the node has none yet. */
+export declare function seedMemory(nodeId: string): boolean;
+/** The user-global memory directory — one per machine, key-less, loaded into
+ *  every orchestrator everywhere. */
+export declare function userMemoryDir(): string;
+/** The user-global MEMORY.md index path. */
+export declare function userMemoryPath(): string;
+export declare function hasUserMemory(): boolean;
+/** Read the user-global MEMORY.md index, or null when it doesn't exist. */
+export declare function readUserMemory(): string | null;
+/** Seed the user-global memory dir + index IF absent. */
+export declare function seedUserMemory(): boolean;
+/** The project key for `cwd`: its git-repo-root when inside a repo, else the
+ *  cwd itself, mangled into a flat directory name (reuses artifact mangleCwd).
+ *  This keys the per-project memory store under <crtrHome>/projects/. */
+export declare function projectKey(cwd: string): string;
+/** The project memory directory for `cwd`. */
+export declare function projectMemoryDir(cwd: string): string;
+/** The project MEMORY.md index path for `cwd`. */
+export declare function projectMemoryPath(cwd: string): string;
+export declare function hasProjectMemory(cwd: string): boolean;
+/** Read the project MEMORY.md index for `cwd`, or null when it doesn't exist. */
+export declare function readProjectMemory(cwd: string): string | null;
+/** Seed the project memory dir + index for `cwd` IF absent. */
+export declare function seedProjectMemory(cwd: string): boolean;