@crouton-kit/crouter 0.3.14 → 0.3.16

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,41 @@
 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 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
+ *  session — switch to it to browse the whole live graph, ignore it otherwise.
+ *  Pure policy (env only, no tmux call), so it lives in the node layer, not the
+ *  driver; the tmux driver imports it from here for installMenuBinding's use. */
+export declare function nodeSession(): 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 +53,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

@@ -18,6 +18,47 @@ import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js
 export function newNodeId() {
     return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
 }
+/** 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
+ *  session — switch to it to browse the whole live graph, ignore it otherwise.
+ *  Pure policy (env only, no tmux call), so it lives in the node layer, not the
+ *  driver; the tmux driver imports it from here for installMenuBinding's use. */
+export function nodeSession() {
+    const v = process.env['CRTR_NODE_SESSION'];
+    return v !== undefined && v !== '' ? v : 'crtr';
+}
+// ---------------------------------------------------------------------------
+// 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 +66,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 +103,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;

package/dist/core/runtime/persona.js

@@ -0,0 +1,139 @@
+// persona.ts — the CENTRALIZED persona-transition injector.
+//
+// A node has two orthogonal, independently switchable axes:
+//   • mode      — base (hands-on, finishes in one window) ↔ orchestrator
+//                 (delegates, holds a roadmap, survives refresh cycles + yields)
+//   • lifecycle — terminal (owes a final up the spine, reaps when done) ↔
+//                 resident (interactable, stays dormant, never forced to submit)
+//
+// Whenever EITHER axis changes from the value the node was last GIVEN guidance
+// for, the node must be prompt-injected with guidance for its new state —
+// automatically, here, not by each state-changing command. Commands just call
+// `updateNode({ mode|lifecycle })`; this module is the single source of the
+// transition prose, delivered from exactly two sites:
+//   • the stophook turn_end hook (self-changes this turn + external changes
+//     while the node is active), and
+//   • the revive kickoff (external changes made while the node was dormant).
+//
+// The `persona_ack` meta field records the last {mode,lifecycle} the node was
+// given guidance for (born equal to its initial persona at spawn, so a fresh
+// worker never gets spurious guidance). `personaDrift` compares live meta to it;
+// the caller delivers the guidance, then commits the ack.
+import { getNode, updateNode } from '../canvas/index.js';
+import { loadKernel, loadPersona, loadLifecycleFragment } from '../personas/index.js';
+import { resolveSkill } from '../resolver.js';
+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.
+// ---------------------------------------------------------------------------
+/** 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) {
+    try {
+        const skill = resolveSkill(name, {});
+        return parseFrontmatter(readText(skill.path)).body.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** 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) {
+    const kernel = loadKernel();
+    const orch = loadPersona(kind, 'orchestrator');
+    const roadmapSkill = typeof orch?.frontmatter?.['roadmapSkill'] === 'string'
+        ? orch.frontmatter['roadmapSkill']
+        : undefined;
+    const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
+    const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const rmPath = roadmapPath(nodeId);
+    const parts = [
+        `You are now a ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
+        'Your job is to manage context and delegate — not to do the goal yourself.',
+        '',
+        kernel,
+    ];
+    if (skillBody) {
+        parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
+    }
+    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 
+    // 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.');
+    return parts.join('\n');
+}
+// ---------------------------------------------------------------------------
+// The other three transitions — short, prescriptive, audience = the node's
+// agent (decision-first; one well-placed "don't").
+// ---------------------------------------------------------------------------
+/** orchestrator → base (demote): hands-on again, finish in-window. */
+function baseModeGuidance() {
+    return ('You are HANDS-ON again — base mode. Do the work yourself in THIS window and finish it here; ' +
+        'stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. ' +
+        'Spawn a child only for a cleanly separable unit, never as your first move.');
+}
+// The lifecycle transition prose is the SAME contract that's baked into the
+// static system prompt at birth — so both load from the one source
+// (`personas/lifecycle/{terminal,resident}.md`) and can never drift. The flip
+// only re-delivers that fragment as the node's new-state steer.
+/** terminal → resident: interactable, never forced to submit. */
+function residentLifecycleGuidance() {
+    return loadLifecycleFragment('resident');
+}
+/** resident → terminal: owes a final, reaps when done. */
+function terminalLifecycleGuidance() {
+    return loadLifecycleFragment('terminal');
+}
+/** 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 function transitionGuidance(nodeId, from, to) {
+    const sections = [];
+    if (from.mode !== to.mode) {
+        if (to.mode === 'orchestrator') {
+            const node = getNode(nodeId);
+            sections.push(orchestrationGuidance(nodeId, node?.kind ?? 'general', node?.cwd ?? process.cwd()));
+        }
+        else {
+            sections.push(baseModeGuidance());
+        }
+    }
+    if (from.lifecycle !== to.lifecycle) {
+        sections.push(to.lifecycle === 'resident' ? residentLifecycleGuidance() : terminalLifecycleGuidance());
+    }
+    return sections.join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// Detector + ack commit.
+// ---------------------------------------------------------------------------
+/** 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 function personaDrift(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return null;
+    const to = { mode: meta.mode, lifecycle: meta.lifecycle };
+    const from = meta.persona_ack ?? { mode: meta.mode, lifecycle: meta.lifecycle };
+    if (from.mode === to.mode && from.lifecycle === to.lifecycle)
+        return null;
+    return { from, to, guidance: transitionGuidance(nodeId, from, to) };
+}
+/** Commit the persona state the node has now been given guidance for. */
+export function commitPersonaAck(nodeId, to) {
+    updateNode(nodeId, { persona_ack: to });
+}