@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/runtime/memory.js

@@ -0,0 +1,165 @@
+// MEMORY.md + memory/ — an orchestrator's persistent file-based memory.
+//
+// One layout, three scopes. Each store is a `memory/` directory of one-fact
+// files (each with typed frontmatter and [[wikilinks]]) indexed by a single
+// MEMORY.md that holds one pointer line per memory and NEVER any content — the
+// architecture in examples/memory-instructions.md. The pointer lines are the
+// load-bearing read: a node's <crtr-context> bearings block extracts every
+// applicable store's pointer lines each brand-new chat (see canvas-context-intro
+// + bearings), so the indexes must stay lean; the detail files load on demand
+// mid-session.
+//
+// The three scopes differ only in WHERE they live and HOW LONG they outlast a
+// node — the `type` taxonomy in each memory's frontmatter drives which store a
+// fact lands in (the mapping lives in the orchestration kernel's "Your long-term
+// memory"). ALL THREE live under the canvas home (crtrHome), all machine-local:
+//
+//   user-global  <crtrHome>/memory/                    — who the human is, how
+//     they like to work; loaded into EVERY orchestrator everywhere.
+//   project      <crtrHome>/projects/<key>/memory/      — facts bound to one
+//     repo; loaded into orchestrators whose cwd resolves to that project. <key>
+//     is the git-repo-root (walked up from the cwd), else the cwd, mangled.
+//   node-local   <crtrHome>/nodes/<id>/context/memory/  — facts specific to this
+//     node's goal; dies with the node.
+//
+// An ORCHESTRATOR-only artifact — the resident, multi-cycle nodes that survive
+// refreshes and accumulate durable lessons/preferences; terminal workers are
+// one-shot and get none. All three stores are seeded the moment a node becomes
+// an orchestrator (promotion, or born one — where the roadmap is seeded too),
+// guarded so a re-seed never clobbers an evolved memory.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { contextDir, crtrHome } from '../canvas/index.js';
+import { mangleCwd } from '../artifact.js';
+// ---------------------------------------------------------------------------
+// Index template + generic store ops (shared by all three scopes).
+// ---------------------------------------------------------------------------
+/** Build the seed contents of a fresh MEMORY.md index. Deliberately tiny: the
+ *  bearings block only ever extracts the pointer lines, so this prose never
+ *  rides into context — it's only for a human/agent opening the file directly,
+ *  and the how-to lives once in the orchestrator kernel ("Your long-term
+ *  memory"), not here. `holds` is a short scope hint so the empty index still
+ *  orients a fresh write. */
+function indexTemplate(holds) {
+    return ('# memory index — one pointer line per memory (`- [Title](slug.md) — hook`); ' +
+        `how-to in "Your long-term memory". Holds ${holds}.\n\n(no memories yet)\n`);
+}
+/** The node-local index template. Named export kept for callers/tests that
+ *  assert the seeded node store verbatim. */
+export const MEMORY_TEMPLATE = indexTemplate('your saved memories');
+/** The user-global index template — framed around the human, not a goal. */
+export const USER_MEMORY_TEMPLATE = indexTemplate('your saved memories about the human — who they are and how they like to work');
+/** The project index template — framed around the repo. */
+export const PROJECT_MEMORY_TEMPLATE = indexTemplate('your saved memories about this project');
+/** The MEMORY.md index path inside a memory `dir`. */
+function indexPathOf(dir) {
+    return join(dir, 'MEMORY.md');
+}
+/** Seed `dir` + its MEMORY.md index with `template` IFF the index is absent.
+ *  Idempotent and guarded so it never clobbers an evolved memory; creating the
+ *  dir up front lets the node write detail files into it directly (no mkdir).
+ *  Returns true when it seeded, false when an index already existed. */
+function seedStore(dir, template) {
+    const idx = indexPathOf(dir);
+    if (existsSync(idx))
+        return false;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(idx, template);
+    return true;
+}
+/** Read a store's MEMORY.md index, or null when it doesn't exist. */
+function readStore(dir) {
+    const idx = indexPathOf(dir);
+    return existsSync(idx) ? readFileSync(idx, 'utf8') : null;
+}
+// ---------------------------------------------------------------------------
+// node-local store — <crtrHome>/nodes/<id>/context/memory/ (facts for this goal)
+// ---------------------------------------------------------------------------
+/** 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 function memoryDir(nodeId) {
+    return join(contextDir(nodeId), 'memory');
+}
+/** The node-local MEMORY.md index path (inside the memory dir). */
+export function memoryPath(nodeId) {
+    return indexPathOf(memoryDir(nodeId));
+}
+/** 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 function hasMemory(nodeId) {
+    return existsSync(memoryPath(nodeId));
+}
+/** Read the node-local MEMORY.md index, or null when it doesn't exist. */
+export function readMemory(nodeId) {
+    return readStore(memoryDir(nodeId));
+}
+/** Seed the node-local memory dir + index IF the node has none yet. */
+export function seedMemory(nodeId) {
+    return seedStore(memoryDir(nodeId), MEMORY_TEMPLATE);
+}
+// ---------------------------------------------------------------------------
+// user-global store — <crtrHome>/memory/ (who the human is, how they work)
+// ---------------------------------------------------------------------------
+/** The user-global memory directory — one per machine, key-less, loaded into
+ *  every orchestrator everywhere. */
+export function userMemoryDir() {
+    return join(crtrHome(), 'memory');
+}
+/** The user-global MEMORY.md index path. */
+export function userMemoryPath() {
+    return indexPathOf(userMemoryDir());
+}
+export function hasUserMemory() {
+    return existsSync(userMemoryPath());
+}
+/** Read the user-global MEMORY.md index, or null when it doesn't exist. */
+export function readUserMemory() {
+    return readStore(userMemoryDir());
+}
+/** Seed the user-global memory dir + index IF absent. */
+export function seedUserMemory() {
+    return seedStore(userMemoryDir(), USER_MEMORY_TEMPLATE);
+}
+// ---------------------------------------------------------------------------
+// project store — <crtrHome>/projects/<key>/memory/ (facts bound to one repo)
+// ---------------------------------------------------------------------------
+/** The git repo root containing `cwd` — walk up for a `.git` entry — or null
+ *  when `cwd` is not inside a repo. `.git` may be a dir (normal) or a file
+ *  (worktree/submodule); existsSync catches both. */
+function gitRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // hit the filesystem root
+        dir = parent;
+    }
+}
+/** 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 function projectKey(cwd) {
+    return mangleCwd(gitRoot(cwd) ?? cwd);
+}
+/** The project memory directory for `cwd`. */
+export function projectMemoryDir(cwd) {
+    return join(crtrHome(), 'projects', projectKey(cwd), 'memory');
+}
+/** The project MEMORY.md index path for `cwd`. */
+export function projectMemoryPath(cwd) {
+    return indexPathOf(projectMemoryDir(cwd));
+}
+export function hasProjectMemory(cwd) {
+    return existsSync(projectMemoryPath(cwd));
+}
+/** Read the project MEMORY.md index for `cwd`, or null when it doesn't exist. */
+export function readProjectMemory(cwd) {
+    return readStore(projectMemoryDir(cwd));
+}
+/** Seed the project memory dir + index for `cwd` IF absent. */
+export function seedProjectMemory(cwd) {
+    return seedStore(projectMemoryDir(cwd), PROJECT_MEMORY_TEMPLATE);
+}

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

@@ -0,0 +1,22 @@
+import type { NodeMeta } from '../canvas/index.js';
+/** Coerce arbitrary text into a 3-5 word kebab-case name, or '' if nothing
+ *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
+ *  single hyphen, and clamps to the first 5 words. */
+export declare function sanitizeSessionName(raw: string): string;
+/** Local fallback: derive a name straight from the prompt (no pi call). Drops
+ *  stop-words, takes the first few content words. */
+export declare function slugFromPrompt(prompt: string): string;
+/** Synchronously ask pi for a 2-4 word kebab name for `prompt`. Blocks up to
+ *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
+ *  output) falls back to a local slug. Returns '' only for an empty prompt. */
+export declare function generateSessionName(prompt: string): string;
+/** Asynchronously generate a name for `prompt` and persist it to the node's
+ *  meta as `description` — only if the node has none yet (so a later message
+ *  never clobbers it). Non-blocking: safe to call from inside a live pi event
+ *  loop. Best-effort; swallows all errors.
+ *
+ *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
+ *  name lands — the bare-root path passes a callback that calls
+ *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
+ *  same session, instead of waiting for the next revive/cycle. */
+export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;

package/dist/core/runtime/naming.js

@@ -0,0 +1,166 @@
+// Session naming — turn a node's first prompt into a short, human-readable
+// handle for the editor label.
+//
+// A node's editor label is `<kind> (<mode>) <name> <cycle>` (see editorLabel in
+// launch.ts). The `<name>` is a 3-5 word kebab-case "description" derived from
+// the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
+// meta so it survives revives and shows in every cycle.
+//
+// Two entry points:
+//   • generateSessionName  — synchronous (spawnSync). For the CLI spawn paths
+//     (spawnChild / bootRoot) that run outside any pi event loop, where a brief
+//     block before launching the worker is fine and lets the FIRST pi session
+//     already carry the name.
+//   • generateAndPersistName — async (execFile, non-blocking). For the bare-root
+//     case where the prompt only arrives as the first interactive message inside
+//     a live pi process; it must never block the event loop. Persists the name
+//     to meta so the label picks it up on the next cycle.
+//
+// Both are best-effort: a failed/slow/garbled pi call falls back to a local slug
+// of the prompt, so a node always gets a sane name.
+import { spawnSync, execFile } from 'node:child_process';
+import { getNode, updateNode } from '../canvas/index.js';
+/** Cap on prompt text fed to the namer — a name needs only the gist. */
+const PROMPT_CAP = 2000;
+/** Wall-clock budget for the headless pi call before we fall back to a slug. */
+const NAME_TIMEOUT_MS = 20_000;
+const NAME_SYSTEM_PROMPT = 'You name coding-agent work sessions. This name is a label used to identify the ' +
+    'session at a glance among many other concurrent programming sessions, so it must ' +
+    'describe what the task is about. Reply with ONLY a concise 3-5 word name in ' +
+    'kebab-case: lowercase words joined by single hyphens (e.g. `refactor-auth-token-flow`, ' +
+    '`add-csv-export-endpoint`). No punctuation, quotes, prose, or trailing text. ' +
+    'Output JUST the name, nothing else.';
+/** Put the raw task text FIRST in a delimited block, then the instruction, so the
+ *  model reads the content before being told what to do and never mistakes the
+ *  prompt's own text for the instruction. The prompt is capped first, so the
+ *  closing tag is always present. */
+function nameUserPrompt(prompt) {
+    return `<prompt>\n${prompt.slice(0, PROMPT_CAP)}\n</prompt>\n\nName this session based on the task above. The name should describe what the task is about, so it can be identified among many other programming sessions. Output JUST the name, nothing else.`;
+}
+/** A short stop-word set so the local-slug fallback skips filler words. */
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'to', 'of', 'in', 'on', 'for', 'with',
+    'is', 'are', 'be', 'this', 'that', 'it', 'as', 'at', 'by', 'from', 'into',
+    'please', 'can', 'you', 'i', 'we', 'my', 'our', 'me', 'so', 'then',
+]);
+/** Coerce arbitrary text into a 3-5 word kebab-case name, or '' if nothing
+ *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
+ *  single hyphen, and clamps to the first 5 words. */
+export function sanitizeSessionName(raw) {
+    const firstLine = (raw ?? '').split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    const words = firstLine
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .split('-')
+        .filter((w) => w !== '');
+    return words.slice(0, 5).join('-');
+}
+/** Local fallback: derive a name straight from the prompt (no pi call). Drops
+ *  stop-words, takes the first few content words. */
+export function slugFromPrompt(prompt) {
+    const words = (prompt ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(' ')
+        .filter((w) => w !== '' && !STOPWORDS.has(w));
+    const picked = (words.length > 0 ? words : (prompt ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').split(' ').filter(Boolean))
+        .slice(0, 3);
+    return sanitizeSessionName(picked.join('-')) || 'session';
+}
+/** Default namer model — Anthropic's small/fast model. Naming is a one-line
+ *  classification, so we pin Haiku (cheap, quick) instead of inheriting the
+ *  node's heavyweight default. Override with CRTR_NAME_MODEL. */
+const DEFAULT_NAME_MODEL = 'anthropic/claude-haiku-4-5';
+/** The pi argv for a headless name request. Stripped down (no tools, session,
+ *  context files, extensions, skills, templates, themes) so it's fast and
+ *  side-effect free. Pinned to Haiku with thinking off — naming is a trivial
+ *  classification that never needs a reasoning budget. Override the model with
+ *  CRTR_NAME_MODEL. */
+function nameArgs(prompt) {
+    const override = process.env['CRTR_NAME_MODEL'];
+    const model = override !== undefined && override.trim() !== '' ? override.trim() : DEFAULT_NAME_MODEL;
+    const argv = [
+        '-p',
+        '--no-session',
+        '--no-context-files',
+        '--no-extensions',
+        '--no-skills',
+        '--no-prompt-templates',
+        '--no-themes',
+        '--no-tools',
+        '--mode', 'text',
+        // Naming is a trivial one-line classification — no thinking budget, ever.
+        '--thinking', 'off',
+        '--model', model,
+    ];
+    argv.push('--system-prompt', NAME_SYSTEM_PROMPT);
+    argv.push(nameUserPrompt(prompt));
+    return argv;
+}
+/** Synchronously ask pi for a 2-4 word kebab name for `prompt`. Blocks up to
+ *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
+ *  output) falls back to a local slug. Returns '' only for an empty prompt. */
+export function generateSessionName(prompt) {
+    const body = (prompt ?? '').trim();
+    if (body === '')
+        return '';
+    try {
+        const r = spawnSync('pi', nameArgs(body), {
+            encoding: 'utf8',
+            timeout: NAME_TIMEOUT_MS,
+            // Don't inherit a TUI; capture stdout only.
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (r.status === 0 && typeof r.stdout === 'string') {
+            const name = sanitizeSessionName(r.stdout);
+            if (name !== '')
+                return name;
+        }
+    }
+    catch {
+        // fall through to slug
+    }
+    return slugFromPrompt(body);
+}
+/** Asynchronously generate a name for `prompt` and persist it to the node's
+ *  meta as `description` — only if the node has none yet (so a later message
+ *  never clobbers it). Non-blocking: safe to call from inside a live pi event
+ *  loop. Best-effort; swallows all errors.
+ *
+ *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
+ *  name lands — the bare-root path passes a callback that calls
+ *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
+ *  same session, instead of waiting for the next revive/cycle. */
+export function generateAndPersistName(nodeId, prompt, onNamed) {
+    const body = (prompt ?? '').trim();
+    if (body === '')
+        return;
+    const persist = (name) => {
+        try {
+            const meta = getNode(nodeId);
+            if (meta === null)
+                return;
+            if ((meta.description ?? '').trim() !== '')
+                return; // already named
+            const clean = sanitizeSessionName(name);
+            const updated = updateNode(nodeId, { description: clean !== '' ? clean : slugFromPrompt(body) });
+            onNamed?.(updated);
+        }
+        catch {
+            // best-effort
+        }
+    };
+    try {
+        execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+            if (err || typeof stdout !== 'string') {
+                persist(slugFromPrompt(body));
+                return;
+            }
+            const name = sanitizeSessionName(stdout);
+            persist(name !== '' ? name : slugFromPrompt(body));
+        });
+    }
+    catch {
+        persist(slugFromPrompt(body));
+    }
+}

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

@@ -1,9 +1,34 @@
 import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export declare function newNodeId(): string;
+/** Resolve the tmux session a freshly-born node's window/pane opens into — and
+ *  thus its durable REVIVE-HOME (`home_session`). Pure so the birth decision is
+ *  unit-testable without a live tmux:
+ *    - managed background child  (`adoptCaller=false`) → the shared backstage:
+ *      the inherited `CRTR_ROOT_SESSION`, else `nodeSession()` (`crtr`).
+ *    - independent `--root` / inline front door (`adoptCaller=true`) → the
+ *      caller's CURRENT session when inside tmux (`here`), else the backstage.
+ *  This is exactly the session each birth site already places the node into;
+ *  centralizing it keeps `home_session` and the actual placement in lockstep. */
+export declare function resolveBirthSession(opts: {
+    /** True for an independent root or the inline front door (both adopt the
+     *  caller's session); false for a managed background child. */
+    adoptCaller: boolean;
+    /** The caller's current tmux location, or null when not inside tmux. */
+    here: {
+        session: string;
+    } | null;
+    /** The inherited CRTR_ROOT_SESSION (the backstage the subtree flows into). */
+    rootSession?: string | null;
+}): string;
+/** A node's durable REVIVE-HOME, with the legacy back-compat default. Nodes born
+ *  before `home_session` existed have no such field in meta — they fall back to
+ *  their last live LOCATION (`tmux_session`), then to the shared backstage
+ *  (`nodeSession()`). The defaulted read for the placement layer; a present
+ *  `home_session` is always returned verbatim. */
+export declare function homeSessionOf(nodeId: string): string;
 export interface NodeContext {
     nodeId: string | null;
-    parentNodeId: string | null;
     kind: string | null;
     mode: Mode | null;
 }
@@ -21,8 +46,14 @@ export interface SpawnNodeOpts {
     lifecycle?: Lifecycle;
     cwd: string;
     name?: string;
+    /** Editor-label handle (2-4 word kebab-case) for the node's first prompt. */
+    description?: string;
     /** Parent node id. Omit for a user-opened root. */
     parent?: string | null;
+    /** Who spawned me (the `spawned_by` provenance edge), when it differs from
+     *  `parent` — e.g. an independent root (parent=null) still records its
+     *  spawner. Defaults to `parent`. */
+    spawnedBy?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passiveDefault?: boolean;
     /** Resolved pi launch recipe (from resolve(kind,mode)). */

package/dist/core/runtime/nodes.js

@@ -14,10 +14,42 @@
 //             is also recorded.
 import { randomBytes } from 'node:crypto';
 import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js';
+import { nodeSession } from './tmux.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export function newNodeId() {
     return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
 }
+// ---------------------------------------------------------------------------
+// REVIVE-HOME (home_session) — the durable session a node is (re)opened into
+// ---------------------------------------------------------------------------
+/** Resolve the tmux session a freshly-born node's window/pane opens into — and
+ *  thus its durable REVIVE-HOME (`home_session`). Pure so the birth decision is
+ *  unit-testable without a live tmux:
+ *    - managed background child  (`adoptCaller=false`) → the shared backstage:
+ *      the inherited `CRTR_ROOT_SESSION`, else `nodeSession()` (`crtr`).
+ *    - independent `--root` / inline front door (`adoptCaller=true`) → the
+ *      caller's CURRENT session when inside tmux (`here`), else the backstage.
+ *  This is exactly the session each birth site already places the node into;
+ *  centralizing it keeps `home_session` and the actual placement in lockstep. */
+export function resolveBirthSession(opts) {
+    const backstage = opts.rootSession !== undefined && opts.rootSession !== null && opts.rootSession !== ''
+        ? opts.rootSession
+        : nodeSession();
+    if (opts.adoptCaller && opts.here !== null)
+        return opts.here.session;
+    return backstage;
+}
+/** A node's durable REVIVE-HOME, with the legacy back-compat default. Nodes born
+ *  before `home_session` existed have no such field in meta — they fall back to
+ *  their last live LOCATION (`tmux_session`), then to the shared backstage
+ *  (`nodeSession()`). The defaulted read for the placement layer; a present
+ *  `home_session` is always returned verbatim. */
+export function homeSessionOf(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return nodeSession();
+    return meta.home_session ?? meta.tmux_session ?? nodeSession();
+}
 /** Read the current node's identity from the environment. A spawned pi process
  *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
  *  it by reading CRTR_NODE_ID as the parent. */
@@ -25,7 +57,6 @@ export function currentNodeContext() {
     const env = process.env;
     return {
         nodeId: env['CRTR_NODE_ID'] ?? null,
-        parentNodeId: env['CRTR_NODE_ID'] ?? null, // a child's parent is the live node
         kind: env['CRTR_KIND'] ?? null,
         mode: env['CRTR_MODE'] ?? null,
     };
@@ -63,33 +94,52 @@ export function nodeEnv(meta) {
 export function spawnNode(opts) {
     const parent = opts.parent ?? null;
     const isRoot = parent === null;
+    // Provenance is independent of the spine: a root has no parent but still
+    // records who spawned it. A child's spawner is its parent unless overridden.
+    const spawnedBy = opts.spawnedBy ?? parent;
+    const mode = opts.mode ?? 'base';
+    // A user-opened root is resident (a conversation you live in); a spawned node
+    // is terminal until it must persist (promotion handles that later).
+    const lifecycle = opts.lifecycle ?? (isRoot ? 'resident' : 'terminal');
     const meta = {
         node_id: opts.nodeId ?? newNodeId(),
         name: opts.name ?? opts.kind,
+        description: opts.description,
+        cycles: 0,
         created: new Date().toISOString(),
         cwd: opts.cwd,
         kind: opts.kind,
-        mode: opts.mode ?? 'base',
-        // A user-opened root is resident (a conversation you live in); a spawned
-        // node is terminal until it must persist (promotion handles that later).
-        lifecycle: opts.lifecycle ?? (isRoot ? 'resident' : 'terminal'),
+        mode,
+        lifecycle,
+        // Born already acked to its initial persona: a fresh node has been "given
+        // guidance" for the state it starts in (its bearings carry it), so the
+        // persona injector sees no drift on its first turn boundary.
+        persona_ack: { mode, lifecycle },
         status: 'active',
         parent,
+        spawned_by: spawnedBy,
         passive_default: opts.passiveDefault ?? false,
         intent: null,
         pi_session_id: null,
+        pi_session_file: null,
         launch: opts.launch,
     };
+    // Validate BEFORE minting: a bad parent must leave no half-born orphan row or
+    // dirs behind, so the parent's existence is checked before createNode
+    // scaffolds anything on disk or in the db.
+    if (parent !== null && getNode(parent) === null) {
+        throw new Error(`cannot spawn under unknown parent node: ${parent}`);
+    }
     createNode(meta);
     if (parent !== null) {
-        if (getNode(parent) === null) {
-            throw new Error(`cannot spawn under unknown parent node: ${parent}`);
-        }
         // The load-bearing seed: parent subscribes (active) to child so it learns
         // when the work finishes. This mirrors spawn structure into the spine.
+        // A root (parent=null) gets NO subscription — nobody is woken by it.
         subscribe(parent, meta.node_id, true);
-        // Audit-only provenance.
-        recordSpawn(meta.node_id, parent);
+    }
+    // Audit-only provenance edge — recorded for a root too (from its spawner).
+    if (spawnedBy !== null && spawnedBy !== undefined && getNode(spawnedBy) !== null) {
+        recordSpawn(meta.node_id, spawnedBy);
     }
     return meta;
 }

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

@@ -0,0 +1,25 @@
+import { type Mode, type Lifecycle } from '../canvas/index.js';
+/** The two-axis persona state the injector keys on. */
+export interface Persona {
+    mode: Mode;
+    lifecycle: Lifecycle;
+}
+export interface PersonaDriftResult {
+    from: Persona;
+    to: Persona;
+    /** The built transition guidance to inject for `to`. */
+    guidance: string;
+}
+/** Build the injected transition prompt for a `from → to` persona change.
+ *  Concatenates the relevant section per changed axis (both when both changed).
+ *  Pure read of the node's roadmap/memory for the base→orchestrator case. */
+export declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): string;
+/** Compare a node's live {mode,lifecycle} against its `persona_ack` (the last
+ *  state it was given guidance for). Returns the transition + built guidance
+ *  when they differ, else null. Does NOT mutate — the caller delivers the
+ *  guidance, then `commitPersonaAck`s the new state. An unset `persona_ack`
+ *  (legacy node) defaults to the current persona, so it reads as no drift and
+ *  never fabricates spurious guidance. */
+export declare function personaDrift(nodeId: string): PersonaDriftResult | null;
+/** Commit the persona state the node has now been given guidance for. */
+export declare function commitPersonaAck(nodeId: string, to: Persona): void;