@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/runtime/launch.js

@@ -32,15 +32,20 @@ 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_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
 export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
 export const CANVAS_RESUME_PATH = resolveExtension('canvas-resume');
+export const CANVAS_VIEW_PATH = resolveExtension('canvas-view');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  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),
- *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
+ *  message, once per brand-new chat), doc-substrate (the unified document
+ *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
+ *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
+ *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
@@ -50,12 +55,27 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_GOAL_CAPTURE_PATH,
     CANVAS_PASSIVE_CONTEXT_PATH,
     CANVAS_CONTEXT_INTRO_PATH,
+    CANVAS_DOC_SUBSTRATE_PATH,
     CANVAS_COMMANDS_PATH,
     CANVAS_RESUME_PATH,
+    CANVAS_VIEW_PATH,
 ];
-/** Bare model aliases resolve to the anthropic provider under pi (avoids the
- *  bedrock default). Anything with a `/` or an unknown name passes through. */
+/** The named capability tiers a caller picks with `--model`, in descending
+ *  strength. Each maps to a concrete pi model spec. `strong`/`medium`/`light`
+ *  resolve to the latest opus/sonnet/haiku; `ultra` to the frontier model. */
+export const MODEL_TIERS = {
+    ultra: 'anthropic/claude-fable-5',
+    strong: 'anthropic/opus',
+    medium: 'anthropic/sonnet',
+    light: 'anthropic/haiku',
+};
+/** Resolve a model token to the spec pi gets via `--model`. A named tier
+ *  (ultra/strong/medium/light) maps to its concrete spec; a bare alias
+ *  (sonnet/opus/haiku) resolves to the anthropic provider under pi (avoids the
+ *  bedrock default); anything with a `/` or an unknown name passes through. */
 export function normalizeModel(model) {
+    if (model in MODEL_TIERS)
+        return MODEL_TIERS[model];
     const bare = new Set(['sonnet', 'opus', 'haiku']);
     if (bare.has(model))
         return `anthropic/${model}`;
@@ -73,8 +93,12 @@ export function normalizeModel(model) {
  *  declared extensions follow. */
 export function buildLaunchSpec(kind, mode, opts) {
     const p = resolvePersona(kind, mode, { lifecycle: opts.lifecycle, hasManager: opts.hasManager });
+    // A caller-supplied override (durable on `meta.model_override`, re-passed on
+    // every polymorph) wins over the persona's declared default; absent both, the
+    // model is left unset and the node inherits pi's default.
+    const chosenModel = opts.model ?? p.model;
     const launch = {
-        model: p.model !== undefined ? normalizeModel(p.model) : undefined,
+        model: chosenModel !== undefined ? normalizeModel(chosenModel) : undefined,
         tools: p.tools,
         extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
         systemPrompt: p.systemPrompt,
@@ -158,3 +182,59 @@ export function buildPiArgv(meta, opts = {}) {
         argv.push(opts.prompt);
     return { argv, env: nodeEnv(meta) };
 }
+/** Translate a `PiInvocation` (the recipe `buildPiArgv` produced) into the SDK
+ *  config the broker hosts an engine with. This is the EXACT inverse of
+ *  `buildPiArgv` and must track its flag set 1:1 — co-located here so the two
+ *  never drift. Safe because `buildPiArgv` is the SOLE producer of these flags
+ *  (we own both ends). SIDE EFFECT: merges `inv.env` into `process.env` so the
+ *  in-process engine + the bound canvas extensions see the same env a forked pi
+ *  would (CRTR_NODE_ID, CRTR_ROOT_SESSION, CRTR_SUBTREE, …). */
+export function piInvocationToSdkConfig(inv) {
+    for (const [k, v] of Object.entries(inv.env))
+        process.env[k] = v;
+    const cfg = {
+        cwd: inv.env['CRTR_NODE_CWD'] ?? process.cwd(),
+        extensionPaths: [],
+    };
+    const argv = inv.argv;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        switch (tok) {
+            case '-e':
+                cfg.extensionPaths.push(argv[++i]);
+                break;
+            case '-n':
+                cfg.editorName = argv[++i];
+                break;
+            case '--fork':
+                cfg.forkFrom = argv[++i];
+                break;
+            case '--session': {
+                const v = argv[++i];
+                // A path (contains `/` or ends `.jsonl`) resumes via SessionManager.open;
+                // a bare uuid is the legacy fallback. Same classification buildPiArgv
+                // documents (path preferred, immune to cwd discrepancy).
+                if (v.includes('/') || v.endsWith('.jsonl'))
+                    cfg.resumeSessionPath = v;
+                else
+                    cfg.resumeSessionId = v;
+                break;
+            }
+            case '--model':
+                cfg.model = argv[++i];
+                break;
+            case '--tools':
+                cfg.tools = argv[++i].split(',').filter((t) => t !== '');
+                break;
+            case '--append-system-prompt':
+                cfg.appendSystemPromptPath = argv[++i];
+                break;
+            default:
+                // buildPiArgv consumes every flag's value via the cases above, so any
+                // token reaching here is the single trailing positional (the prompt).
+                cfg.firstPrompt = tok;
+                break;
+        }
+    }
+    return cfg;
+}

package/dist/core/runtime/lifecycle.js

@@ -15,10 +15,11 @@
 //
 // 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
+// host" (tmux pane or headless broker) — 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 `cancel` event: callers flip via transition()
-// and only THEN kill the window.
+// and only THEN tear the host down.
 //
 // Unification (A5, human-confirmed 2026-06-06): an externally-reaped node — torn
 // down because the user moved on (close cascade) OR because a root reset/relaunch
@@ -33,7 +34,7 @@
 // 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';
+import { openDb, getNode, cancelWakesFor, cancelSelfAlarms } from '../canvas/index.js';
 const ANY = '*';
 /** The supervised statuses — a live node the daemon watches. */
 const LIVE = ['active', 'idle'];
@@ -47,12 +48,12 @@ const TRANSITIONS = {
     // of a node that did NOT finish its own work → canceled, intent cleared. (A5:
     // done is reserved for finalize; every external reap unifies on canceled.)
     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).
+    // daemon superviseTick: engine container gone (tmux pane or broker process)
+    // 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.
+    // stophook idle-release: free the host, 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 },
@@ -90,5 +91,21 @@ export function transition(nodeId, event) {
     else if (writeIntent) {
         db.prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(spec.intent ?? null, nodeId);
     }
+    // Wakeups cleanup — writes a DIFFERENT table (wakeups) AFTER the atomic
+    // status/intent write above, so the single-(status,intent)-writer rule holds.
+    // Event-gated; exactly ONE delegated wakeups helper per event, never inline
+    // wakeups SQL here (design §6.7 / D2 / D6, Q1/Q2):
+    //   cancel   → cancelWakesFor: reap node-anchored AND owner-armed detached
+    //              wakes this node armed (ruling A) — covers all three cancel
+    //              sites uniformly (close cascade · reapDescendants · relaunch
+    //              park-old).
+    //   finalize → cancelSelfAlarms: clear this node's one-shot self-alarms only;
+    //              node-anchored declarative crons SURVIVE a finishing instance (Q1).
+    //   crash    → NOTHING. A fault is not a deliberate end-of-waiting; self-alarms
+    //              and crons MUST survive instance death (D2 / Invariant E / AC-R3).
+    if (event === 'cancel')
+        cancelWakesFor(nodeId);
+    else if (event === 'finalize')
+        cancelSelfAlarms(nodeId);
     return getNode(nodeId);
 }

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

@@ -1,43 +1,3 @@
-/** 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. */
+/** The node-local memory directory in a node's context dir — holds substrate
+ *  docs (.md files with kind/when/why frontmatter). */
 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;

package/dist/core/runtime/memory.js

@@ -1,165 +1,14 @@
-// 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. */
+// memory.ts — the node-local substrate document store.
+//
+// One scope lives here: node-local memory, a `memory/` directory of substrate
+// documents (.md files with typed frontmatter — kind, when, why,
+// system-prompt-visibility, gate) inside a node's context dir; it dies with the
+// node. User-global and project memory are scope-resolved stores — see
+// `scopeMemoryDir` in core/scope.ts.
+import { join } from 'node:path';
+import { contextDir } from '../canvas/index.js';
+/** The node-local memory directory in a node's context dir — holds substrate
+ *  docs (.md files with kind/when/why frontmatter). */
 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/nodes.d.ts

@@ -1,6 +1,12 @@
 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;
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export declare function rootOfSpine(nodeId: string): string;
 /** The single, shared tmux session that ALL canvas node windows live in.
  *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
  *  child opens a window here rather than cluttering the user's own working
@@ -34,6 +40,25 @@ export declare function resolveBirthSession(opts: {
  *  (`nodeSession()`). The defaulted read for the placement layer; a present
  *  `home_session` is always returned verbatim. */
 export declare function homeSessionOf(nodeId: string): string;
+/** The session a node's CHILDREN spawn into — the value its pi process exports
+ *  as CRTR_ROOT_SESSION (the subtree's backstage). NOT the same as where the
+ *  node's OWN pane lives.
+ *
+ *  For a managed CHILD this is its `home_session`: a child's home_session is
+ *  ALWAYS the backstage it was born into (focus may move its live pane into a
+ *  user session, but home_session stays the taint-immune backstage), so its
+ *  descendants correctly inherit that backstage.
+ *
+ *  For a ROOT (`parent === null`) `home_session` may be a USER session it
+ *  ADOPTED — the inline front door keeps the root's own pane where the user is
+ *  working (`home_session = cli`). Sourcing children's CRTR_ROOT_SESSION from
+ *  that would exile the root's entire subtree into the user's session. A root's
+ *  children must instead flow to the shared backstage `nodeSession()`, NEVER the
+ *  user's session — mirroring spawnRoot's birth-time split (root pane → user
+ *  session; children → nodeSession() via CRTR_ROOT_SESSION). The revive paths
+ *  MUST honor the same split, or a refreshed front-door root re-points its whole
+ *  subtree into the user's session on every yield (the bug this fixes). */
+export declare function childBackstageOf(nodeId: string): string;
 export interface NodeContext {
     nodeId: string | null;
     kind: string | null;
@@ -61,10 +86,22 @@ export interface SpawnNodeOpts {
      *  `parent` — e.g. an independent root (parent=null) still records its
      *  spawner. Defaults to `parent`. */
     spawnedBy?: string | null;
+    /** Fork provenance — the `--fork-from` reference this node was forked from (a
+     *  node id / session path / pi session uuid). Persisted to `meta.fork_from` so
+     *  the boot intro can re-assert this node's OWN identity over the source's
+     *  copied-in conversation. Omit for a fresh node. */
+    forkFrom?: string | null;
+    /** Which HOST launches + supervises this node: a tmux pane (default) or the
+     *  headless broker. Persisted to `meta.host_kind` (NULL/'tmux' ⇒ tmux). */
+    hostKind?: 'tmux' | 'broker';
     /** New subscriptions this node opens default to passive when true. */
     passiveDefault?: boolean;
     /** Resolved pi launch recipe (from resolve(kind,mode)). */
     launch?: LaunchSpec;
+    /** Caller-pinned model tier (ultra/strong/medium/light) that overrides the
+     *  persona default. Persisted to `meta.model_override` so polymorphs preserve
+     *  it. Omit to use the persona default. */
+    modelOverride?: string | null;
     /** Override the generated id (e.g. when a caller pre-allocates one). */
     nodeId?: string;
 }

package/dist/core/runtime/nodes.js

@@ -13,11 +13,31 @@
 //             graph to mirror the spawn structure. A `spawned_by` audit edge
 //             is also recorded.
 import { randomBytes } from 'node:crypto';
-import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js';
+import { mkdirSync } from 'node:fs';
+import { createNode, getNode, getRow, subscribe, recordSpawn, } from '../canvas/index.js';
+import { memoryDir } from './memory.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')}`;
 }
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export function rootOfSpine(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    for (;;) {
+        if (seen.has(cur))
+            return cur;
+        seen.add(cur);
+        const row = getRow(cur);
+        if (row === null || row.parent == null)
+            return cur;
+        cur = row.parent;
+    }
+}
 /** The single, shared tmux session that ALL canvas node windows live in.
  *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
  *  child opens a window here rather than cluttering the user's own working
@@ -59,6 +79,30 @@ export function homeSessionOf(nodeId) {
         return nodeSession();
     return meta.home_session ?? meta.tmux_session ?? nodeSession();
 }
+/** The session a node's CHILDREN spawn into — the value its pi process exports
+ *  as CRTR_ROOT_SESSION (the subtree's backstage). NOT the same as where the
+ *  node's OWN pane lives.
+ *
+ *  For a managed CHILD this is its `home_session`: a child's home_session is
+ *  ALWAYS the backstage it was born into (focus may move its live pane into a
+ *  user session, but home_session stays the taint-immune backstage), so its
+ *  descendants correctly inherit that backstage.
+ *
+ *  For a ROOT (`parent === null`) `home_session` may be a USER session it
+ *  ADOPTED — the inline front door keeps the root's own pane where the user is
+ *  working (`home_session = cli`). Sourcing children's CRTR_ROOT_SESSION from
+ *  that would exile the root's entire subtree into the user's session. A root's
+ *  children must instead flow to the shared backstage `nodeSession()`, NEVER the
+ *  user's session — mirroring spawnRoot's birth-time split (root pane → user
+ *  session; children → nodeSession() via CRTR_ROOT_SESSION). The revive paths
+ *  MUST honor the same split, or a refreshed front-door root re-points its whole
+ *  subtree into the user's session on every yield (the bug this fixes). */
+export function childBackstageOf(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta !== null && meta.parent === null)
+        return nodeSession();
+    return homeSessionOf(nodeId);
+}
 /** 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. */
@@ -92,6 +136,12 @@ export function nodeEnv(meta) {
     const rootSession = process.env['CRTR_ROOT_SESSION'];
     if (rootSession !== undefined && rootSession !== '')
         env['CRTR_ROOT_SESSION'] = rootSession;
+    // Propagate the subtree-root node id (additive in Phase 3; tmux still keys on
+    // CRTR_ROOT_SESSION). The broker uses it to group a subtree; each launch site
+    // also emits the authoritative rootOfSpine(nodeId) over this passthrough.
+    const subtree = process.env['CRTR_SUBTREE'];
+    if (subtree !== undefined && subtree !== '')
+        env['CRTR_SUBTREE'] = subtree;
     // Merge any launch-spec env last (it may override / extend).
     return { ...env, ...(meta.launch?.env ?? {}) };
 }
@@ -117,6 +167,7 @@ export function spawnNode(opts) {
         cycles: 0,
         created: new Date().toISOString(),
         cwd: opts.cwd,
+        host_kind: opts.hostKind ?? 'tmux',
         kind: opts.kind,
         mode,
         lifecycle,
@@ -127,6 +178,8 @@ export function spawnNode(opts) {
         status: 'active',
         parent,
         spawned_by: spawnedBy,
+        fork_from: opts.forkFrom,
+        model_override: opts.modelOverride ?? null,
         passive_default: opts.passiveDefault ?? false,
         intent: null,
         pi_session_id: null,
@@ -140,6 +193,12 @@ export function spawnNode(opts) {
         throw new Error(`cannot spawn under unknown parent node: ${parent}`);
     }
     createNode(meta);
+    // Create the node-local memory directory so substrate docs can be written
+    // directly into it without a separate mkdir. Skip for ephemeral human-bridge
+    // rows (kind 'human') — they are not agent nodes.
+    if (meta.kind !== 'human') {
+        mkdirSync(memoryDir(meta.node_id), { recursive: true });
+    }
     if (parent !== null) {
         // The load-bearing seed: parent subscribes (active) to child so it learns
         // when the work finishes. This mirrors spawn structure into the spine.

package/dist/core/runtime/persona.js

@@ -26,11 +26,22 @@ import { readText } from '../fs-utils.js';
 import { parseFrontmatter } from '../frontmatter.js';
 import { readRoadmap, roadmapPath } from './roadmap.js';
 import { orchestratorContextNote } from './bearings.js';
-import { memoryPath, memoryDir, userMemoryPath, userMemoryDir, projectMemoryPath, projectMemoryDir, } from './memory.js';
 // ---------------------------------------------------------------------------
 // base→orchestrator guidance (the roadmap-shaping dump) — MOVED here from
 // promote.ts so the injector is the one place that builds it.
 // ---------------------------------------------------------------------------
+/** Coerce a frontmatter scalar to its string form, matching the legacy
+ *  hand-rolled parser. Strings pass through; number/boolean coerce via
+ *  String(); null/undefined and non-scalars are dropped (→ null). Without this,
+ *  the `yaml` package's native scalar types would let a numeric/boolean
+ *  `roadmapSkill` be silently dropped by a `typeof === 'string'` guard. */
+function scalarToString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return null;
+}
 /** Load a skill's body text by name, or null if it can't be resolved. Used to
  *  inline a kind's roadmap-shaping skill into the orchestration guidance. */
 function loadSkillBody(name) {
@@ -44,16 +55,15 @@ function loadSkillBody(name) {
 }
 /** The base→orchestrator guidance dump, specialized to the node's kind: the
  *  shared kernel + that kind's roadmap-shaping skill + the roadmap scaffold the
- *  node must author + the orchestrator context-dir framing + the three memory
- *  stores. The node is now a delegator whose scarce resource is its own context
- *  window. (Lifecycle is left to its own section — promotion no longer forces
- *  resident, so this never asserts residency.) */
-function orchestrationGuidance(nodeId, kind, cwd) {
+ *  node must author + the orchestrator context-dir framing + a short pointer at
+ *  the substrate memory flow (promotion re-informs of nothing about the stores,
+ *  it only adds the across-cycles relevance). The node is now a delegator whose
+ *  scarce resource is its own context window. (Lifecycle is left to its own
+ *  section — promotion no longer forces resident, so this never asserts residency.) */
+function orchestrationGuidance(nodeId, kind) {
     const kernel = loadKernel();
     const orch = loadPersona(kind, 'orchestrator');
-    const roadmapSkill = typeof orch?.frontmatter?.['roadmapSkill'] === 'string'
-        ? orch.frontmatter['roadmapSkill']
-        : undefined;
+    const roadmapSkill = scalarToString(orch?.frontmatter?.['roadmapSkill']) ?? undefined;
     const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
     const rmPath = roadmapPath(nodeId);
@@ -70,7 +80,7 @@ function orchestrationGuidance(nodeId, kind, cwd) {
     // The orchestrator framing for the context dir — the missing guidance a
     // promoted node never got at spawn (it spawned as a base worker). Same note
     // a born-orchestrator gets in its <crtr-context> bearings block.
-    orchestratorContextNote(nodeId), '', 'Your long-term memory now exists across three seeded stores (write to them directly), each a different scope per "Your long-term memory" above:', `  • user-global \`${userMemoryDir()}\` (index \`${userMemoryPath()}\`) — who the human is, how they like to work; loaded into every orchestrator everywhere.`, `  • project \`${projectMemoryDir(cwd)}\` (index \`${projectMemoryPath(cwd)}\`) — facts bound to this repo; loaded into every orchestrator working here.`, `  • node-local \`${memoryDir(nodeId)}\` (index \`${memoryPath(nodeId)}\`) — facts specific to this goal; they die with this node.`, 'A memory\'s `type` decides which store it lands in (see "Your long-term memory"). These same paths ride into every future wake in your `<crtr-context>` block.', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your `<crtr-context>` block. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
     return parts.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -103,7 +113,7 @@ export function transitionGuidance(nodeId, from, to) {
     if (from.mode !== to.mode) {
         if (to.mode === 'orchestrator') {
             const node = getNode(nodeId);
-            sections.push(orchestrationGuidance(nodeId, node?.kind ?? 'general', node?.cwd ?? process.cwd()));
+            sections.push(orchestrationGuidance(nodeId, node?.kind ?? 'general'));
         }
         else {
             sections.push(baseModeGuidance());