@crouton-kit/crouter 0.3.14 → 0.3.16

package/dist/core/runtime/launch.js

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

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

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

package/dist/core/runtime/lifecycle.js

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

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

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

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;