@north-light/crouter 0.3.154

package/dist/core/runtime/managed-provider-cooling.js

@@ -0,0 +1,81 @@
+// managed-provider-cooling.ts — the typed carrier for "every managed provider
+// pool tried this turn is temporarily cooling down".
+//
+// runManagedProvider (provider-rotation.ts) raises this once every attempted
+// managed-pool credential is rate-limited with at least one finite future
+// deadline. The error converts to an AssistantMessageDiagnostic that survives
+// verbatim into the terminal error message and therefore into agent_end.messages
+// (pi-ai's AssistantMessageEventStream.result() returns the exact error message
+// object). The canvas-stophook reads the earliest deadline back off that message
+// and stamps it onto the pi→provider fault's retry.nextAt, so the broker's
+// existing auto-retry re-drives the pre-content turn exactly when the soonest
+// pool frees up — turning a transient pool cooldown into an auto (not fatal)
+// fault instead of a permanent one.
+/** Diagnostic `type` tag carrying the cooling deadline; also the wire contract the
+ *  stophook matches on. */
+export const MANAGED_PROVIDER_COOLING_DIAGNOSTIC = "crtr:managed-provider-cooling";
+/** Stable error code so a caller can recognize the typed error without message parsing. */
+export const MANAGED_PROVIDER_COOLING_CODE = "managed_provider_cooling";
+/**
+ * Broker-owned, live policy exposed to the jiti-loaded provider-rotation
+ * extension through its UI context. A callback (rather than a boot-time value)
+ * is required because an attached viewer can pin or unpin the running broker
+ * with `set_model`; the very next provider attempt must observe that decision.
+ */
+export const MANAGED_PROVIDER_ROTATION_POLICY_UI = Symbol.for("@crouton-kit/crtr:managed-provider-rotation-policy");
+/** Non-broker/test hosts retain the historical permissive fallback policy. */
+export function readManagedProviderRotationPolicy(ui) {
+    const control = ui?.[MANAGED_PROVIDER_ROTATION_POLICY_UI];
+    if (typeof control !== "function")
+        return { allowCrossProviderFallback: true };
+    try {
+        return control();
+    }
+    catch {
+        return { allowCrossProviderFallback: true };
+    }
+}
+/** Every managed provider pool tried this turn is cooling; `rateLimitedUntil` is
+ *  the earliest future deadline (epoch ms) across those pools. */
+export class ManagedProviderCoolingError extends Error {
+    code = MANAGED_PROVIDER_COOLING_CODE;
+    rateLimitedUntil;
+    constructor(message, rateLimitedUntil) {
+        super(message);
+        this.name = "ManagedProviderCoolingError";
+        this.rateLimitedUntil = rateLimitedUntil;
+    }
+    /** The diagnostic to attach to the terminal assistant error so the deadline
+     *  reaches the stophook without regex-parsing the message. Built inline (not via
+     *  pi-ai's `createAssistantMessageDiagnostic`) to keep this module's runtime
+     *  import graph pi-free — the shape matches `AssistantMessageDiagnostic`. */
+    toDiagnostic() {
+        return {
+            type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
+            timestamp: Date.now(),
+            details: { rateLimitedUntil: this.rateLimitedUntil },
+        };
+    }
+}
+/** Strictly read the managed-cooling deadline (epoch ms) off an assistant
+ *  message's diagnostics. Returns the finite, strictly-positive `rateLimitedUntil`
+ *  from the first cooling diagnostic, or undefined when the message carries none
+ *  (or a malformed one). */
+export function hasManagedProviderCoolingDiagnostic(message) {
+    const diagnostics = message?.diagnostics;
+    return Array.isArray(diagnostics) && diagnostics.some((diagnostic) => diagnostic?.type === MANAGED_PROVIDER_COOLING_DIAGNOSTIC);
+}
+export function extractCoolingDeadline(message) {
+    const diagnostics = message?.diagnostics;
+    if (!Array.isArray(diagnostics))
+        return undefined;
+    for (const diagnostic of diagnostics) {
+        if (diagnostic?.type !== MANAGED_PROVIDER_COOLING_DIAGNOSTIC)
+            continue;
+        const raw = diagnostic?.details?.rateLimitedUntil;
+        const value = typeof raw === "number" ? raw : Number(raw);
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,3 @@
+/** 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;

package/dist/core/runtime/memory.js

@@ -0,0 +1,18 @@
+// 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 the pure path helper from paths.ts directly, NOT the canvas/index.js
+// barrel: the barrel re-exports `openDb`/canvas.ts accessors, so pulling it here
+// would drag canvas.db into the runtime graph of every pure-client CLI leaf that
+// resolves memory docs (e.g. `memory origin`, `sys prompt-review`). Stage B-9.
+import { contextDir } from '../canvas/paths.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');
+}

package/dist/core/runtime/model-selection.d.ts

@@ -0,0 +1,41 @@
+import type { ModelProvider, ModelStrength, ScopeConfig } from '../../types.js';
+/** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
+ *  project-stack > profile > user > builtin precedence `resolveKindConfig`
+ *  already uses for `kinds` — so a project/profile override of `modelLadders`
+ *  is honored identically to a kind override, instead of this file reading
+ *  only user config. */
+export declare function modelLadders(): ScopeConfig['modelLadders'];
+/** Env var naming the DEFAULT provider for an UNqualified bare strength only.
+ *  `CRTR_MODEL_PROVIDER=openai` (case-insensitive) makes a bare `strong` resolve
+ *  on the OpenAI ladder; anything else defaults to Anthropic. A configured
+ *  defaultProvider in config.json wins over this env. */
+export declare const OPENAI_PROVIDER_ENV = "CRTR_MODEL_PROVIDER";
+export declare function defaultProvider(ladders?: ScopeConfig['modelLadders']): ModelProvider;
+/** Strength synonyms accepted from personas/callers. */
+export declare const STRENGTH_ALIASES: Record<string, ModelStrength>;
+export declare const MODEL_PROVIDER_KEYS: ModelProvider[];
+export declare const MODEL_STRENGTHS: ModelStrength[];
+/** The ladder providers a picker/cycle should OFFER: a provider column is kept
+ *  only when at least one of its ladder cells names a runtime provider the
+ *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or
+ *  `registry.getProviderAuthStatus(id).configured`). A user who never logged
+ *  into Codex sees no openai column in settings and no openai rungs on Alt+M.
+ *  When NO column qualifies (a fresh install before any login), every provider
+ *  is returned: the model surfaces must stay reachable so the user can still
+ *  inspect config and go sign in. Resolution (`normalizeModel` etc.) is
+ *  deliberately NOT gated — an explicit `openai/strong` request still resolves
+ *  and then fails/falls back through the normal auth-aware launch policy. */
+export declare function configuredLadderProviders(isConfigured: (runtimeProviderId: string) => boolean, ladders?: ScopeConfig['modelLadders']): ModelProvider[];
+export declare const THINKING_SUFFIXES: Set<string>;
+export declare function stripThinkingSuffix(spec: string): string;
+export interface PortableModelSelection {
+    provider: ModelProvider;
+    strength: ModelStrength;
+}
+/** Choose the provider×strength option an editor should highlight for an
+ * existing model value. Portable tokens follow the exact provider rules used
+ * by `normalizeModel`; concrete ladder refs map back to their configured cell,
+ * ignoring a thinking suffix only after an exact match. An off-ladder concrete
+ * ref retains a recognizable provider and starts at `ultra`; an unrecognized
+ * value starts at `ultra` on the effective default provider. */
+export declare function inferPortableModelSelection(model: string | undefined, ladders?: ScopeConfig['modelLadders']): PortableModelSelection;

package/dist/core/runtime/model-selection.js

@@ -0,0 +1,118 @@
+// Two-axis model-ladder resolution primitives — the PURE half of the launch
+// recipe's model logic (provider × strength → concrete `model:thinking`).
+//
+// Split out of `launch.ts` so the CLI-side model wizard (`sys setup`) and other
+// pure consumers can resolve/normalize a provider×strength selection WITHOUT
+// dragging in `launch.ts`'s full revive-recipe module graph, which reaches
+// `core/canvas/index.js` (→ `openDb`) via `editorLabel`/`nodeEnv`. Everything
+// here depends only on `readMergedLaunchConfig` (fs/config, openDb-free) and the
+// static `types.ts` shapes, so its transitive runtime import graph is
+// canvas-state-store-free (spec §10 / Stage-C import checker). `launch.ts`
+// imports these back for its own resolution/fallback/picker logic.
+import { readMergedLaunchConfig } from '../config.js';
+/** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
+ *  project-stack > profile > user > builtin precedence `resolveKindConfig`
+ *  already uses for `kinds` — so a project/profile override of `modelLadders`
+ *  is honored identically to a kind override, instead of this file reading
+ *  only user config. */
+export function modelLadders() {
+    return readMergedLaunchConfig().modelLadders;
+}
+/** Env var naming the DEFAULT provider for an UNqualified bare strength only.
+ *  `CRTR_MODEL_PROVIDER=openai` (case-insensitive) makes a bare `strong` resolve
+ *  on the OpenAI ladder; anything else defaults to Anthropic. A configured
+ *  defaultProvider in config.json wins over this env. */
+export const OPENAI_PROVIDER_ENV = 'CRTR_MODEL_PROVIDER';
+export function defaultProvider(ladders = modelLadders()) {
+    const cfgProvider = ladders.defaultProvider;
+    if (cfgProvider === 'anthropic' || cfgProvider === 'openai')
+        return cfgProvider;
+    return (process.env[OPENAI_PROVIDER_ENV] ?? '').toLowerCase() === 'openai' ? 'openai' : 'anthropic';
+}
+/** Strength synonyms accepted from personas/callers. */
+export const STRENGTH_ALIASES = {
+    ultra: 'ultra',
+    strong: 'strong',
+    medium: 'medium',
+    light: 'light',
+    normal: 'medium',
+    weak: 'light',
+};
+// Every ladder provider — walked for resolution, strength-matching, the model
+// picker, and the Alt+M cycle. Both participate in automatic turn-time fallback.
+export const MODEL_PROVIDER_KEYS = ['anthropic', 'openai'];
+export const MODEL_STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+/** The ladder providers a picker/cycle should OFFER: a provider column is kept
+ *  only when at least one of its ladder cells names a runtime provider the
+ *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or
+ *  `registry.getProviderAuthStatus(id).configured`). A user who never logged
+ *  into Codex sees no openai column in settings and no openai rungs on Alt+M.
+ *  When NO column qualifies (a fresh install before any login), every provider
+ *  is returned: the model surfaces must stay reachable so the user can still
+ *  inspect config and go sign in. Resolution (`normalizeModel` etc.) is
+ *  deliberately NOT gated — an explicit `openai/strong` request still resolves
+ *  and then fails/falls back through the normal auth-aware launch policy. */
+export function configuredLadderProviders(isConfigured, ladders = modelLadders()) {
+    const kept = MODEL_PROVIDER_KEYS.filter((provider) => MODEL_STRENGTHS.some((strength) => {
+        const cell = ladders[provider][strength];
+        const slash = cell.indexOf('/');
+        return slash > 0 && isConfigured(cell.slice(0, slash));
+    }));
+    return kept.length > 0 ? kept : [...MODEL_PROVIDER_KEYS];
+}
+export const THINKING_SUFFIXES = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+export function stripThinkingSuffix(spec) {
+    const i = spec.lastIndexOf(':');
+    if (i <= 0)
+        return spec;
+    return THINKING_SUFFIXES.has(spec.slice(i + 1)) ? spec.slice(0, i) : spec;
+}
+/** Choose the provider×strength option an editor should highlight for an
+ * existing model value. Portable tokens follow the exact provider rules used
+ * by `normalizeModel`; concrete ladder refs map back to their configured cell,
+ * ignoring a thinking suffix only after an exact match. An off-ladder concrete
+ * ref retains a recognizable provider and starts at `ultra`; an unrecognized
+ * value starts at `ultra` on the effective default provider. */
+export function inferPortableModelSelection(model, ladders = modelLadders()) {
+    const value = model?.trim() ?? '';
+    if (value !== '') {
+        const slash = value.indexOf('/');
+        if (slash > 0) {
+            const provider = value.slice(0, slash);
+            const strength = STRENGTH_ALIASES[value.slice(slash + 1)];
+            if ((provider === 'anthropic' || provider === 'openai') && strength !== undefined) {
+                return { provider, strength };
+            }
+        }
+        else {
+            const strength = STRENGTH_ALIASES[value];
+            if (strength !== undefined)
+                return { provider: defaultProvider(ladders), strength };
+            if (value === 'opus')
+                return { provider: 'anthropic', strength: 'strong' };
+            if (value === 'sonnet')
+                return { provider: 'anthropic', strength: 'medium' };
+            if (value === 'haiku')
+                return { provider: 'anthropic', strength: 'light' };
+        }
+        for (const provider of MODEL_PROVIDER_KEYS) {
+            for (const strength of MODEL_STRENGTHS) {
+                if (ladders[provider][strength] === value)
+                    return { provider, strength };
+            }
+        }
+        const comparable = stripThinkingSuffix(value);
+        for (const provider of MODEL_PROVIDER_KEYS) {
+            for (const strength of MODEL_STRENGTHS) {
+                if (stripThinkingSuffix(ladders[provider][strength]) === comparable)
+                    return { provider, strength };
+            }
+        }
+        const providerId = slash > 0 ? value.slice(0, slash) : '';
+        if (providerId === 'anthropic')
+            return { provider: 'anthropic', strength: 'ultra' };
+        if (providerId === 'openai' || providerId === 'openai-codex')
+            return { provider: 'openai', strength: 'ultra' };
+    }
+    return { provider: defaultProvider(ladders), strength: 'ultra' };
+}

package/dist/core/runtime/model-swap.d.ts

@@ -0,0 +1,27 @@
+import { type NodeMeta } from '../canvas/index.js';
+/** True when the node's broker engine is reachable: its recorded pid is alive
+ *  AND its view.sock exists. Both are required — a dead pid with a stale socket,
+ *  or a live pid mid-boot before it binds the socket, is NOT a live broker. */
+export declare function isBrokerLive(meta: NodeMeta): boolean;
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  sends `set_model`, and resolves with the broker-resolved `provider/id` on its ack —
+ *  read back from the row the broker just persisted (model_changed.model carries
+ *  only the bare id). Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.
+ *  `pinned` is the durable-pin decision for this change, made by the CALLER from
+ *  the RAW pre-normalize token (`spec` here is already normalizeModel-resolved,
+ *  so deriving the pin from `spec`'s shape would wrongly re-pin a deliberately
+ *  chosen bare tier that happens to byte-equal a ladder cell) — sent explicitly
+ *  on the frame so the broker persists that decision rather than re-inferring it
+ *  from the resolved spec. */
+export declare function setModelLive(nodeId: string, spec: string, pinned: boolean): Promise<string>;
+/** Persist a model choice into a DORMANT node's durable recipe — mirrors exactly
+ *  what the broker's persistModelChoice writes on a live switch: `model_override`
+ *  (so polymorphs preserve it via buildLaunchSpec) and `launch.model` (the recipe
+ *  buildPiArgv replays on revive). `spec` must already be a concrete `provider/id`
+ *  (normalizeModel maps tiers/aliases; a bare substring cannot resolve offline).
+ *  `pinned` is the durable-pin decision for this change — decided by the CALLER
+ *  from the RAW pre-normalize token, never re-derived here from `spec`'s shape
+ *  (a concrete `spec` always reads as "pinned", which would wrongly re-pin a
+ *  deliberately chosen bare tier that happens to byte-equal a ladder cell). */
+export declare function persistDormantModel(nodeId: string, spec: string, pinned: boolean): void;

package/dist/core/runtime/model-swap.js

@@ -0,0 +1,70 @@
+// model-swap.ts — the engine behind `crtr node config`: swap a node's model
+// (and thus its provider) WITHOUT attaching a viewer, persisting the choice so
+// it survives revives. Two paths, chosen on broker liveness:
+//
+//   LIVE   — the node's broker is up (recorded pi_pid alive AND view.sock
+//            present): connect to view.sock as a controller, send `set_model`,
+//            await the ack. The broker's broadcastModelChanged already persists
+//            the choice via persistModelChoice (model_override + launch.model), so
+//            this path NEVER writes the recipe itself — it reads back the resolved
+//            provider/id from the freshly-updated row.
+//   DORMANT — no live broker: write the durable recipe directly (mirroring exactly
+//            what persistModelChoice writes) so the next revive picks it up.
+//
+// This complements the in-viewer `/model` slash command for the headless case.
+import { existsSync } from 'node:fs';
+import { getNode, updateNode } from '../canvas/index.js';
+import { viewSocketPath } from '../canvas/paths.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { oneShotControllerRequest } from './broker-request.js';
+/** True when the node's broker engine is reachable: its recorded pid is alive
+ *  AND its view.sock exists. Both are required — a dead pid with a stale socket,
+ *  or a live pid mid-boot before it binds the socket, is NOT a live broker. */
+export function isBrokerLive(meta) {
+    return isPidAlive(meta.pi_pid) && existsSync(viewSocketPath(meta.node_id));
+}
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  sends `set_model`, and resolves with the broker-resolved `provider/id` on its ack —
+ *  read back from the row the broker just persisted (model_changed.model carries
+ *  only the bare id). Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.
+ *  `pinned` is the durable-pin decision for this change, made by the CALLER from
+ *  the RAW pre-normalize token (`spec` here is already normalizeModel-resolved,
+ *  so deriving the pin from `spec`'s shape would wrongly re-pin a deliberately
+ *  chosen bare tier that happens to byte-equal a ladder cell) — sent explicitly
+ *  on the frame so the broker persists that decision rather than re-inferring it
+ *  from the resolved spec. */
+export function setModelLive(nodeId, spec, pinned) {
+    // `set_model` carries no frame id, so the ack is matched on `for` alone.
+    let resolvedId;
+    return oneShotControllerRequest({
+        nodeId,
+        what: 'the model switch',
+        ackFor: 'set_model',
+        frame: () => ({ type: 'set_model', model: spec, pinned }),
+        observe: (frame) => {
+            if (frame.type === 'model_changed')
+                resolvedId = frame.model?.id;
+        },
+        // The broker persisted model_override (full provider/id) in
+        // broadcastModelChanged BEFORE flushing these frames, so the row is
+        // authoritative; fall back to the bare id, then the raw spec.
+        result: () => getNode(nodeId)?.model_override ?? resolvedId ?? spec,
+    });
+}
+/** Persist a model choice into a DORMANT node's durable recipe — mirrors exactly
+ *  what the broker's persistModelChoice writes on a live switch: `model_override`
+ *  (so polymorphs preserve it via buildLaunchSpec) and `launch.model` (the recipe
+ *  buildPiArgv replays on revive). `spec` must already be a concrete `provider/id`
+ *  (normalizeModel maps tiers/aliases; a bare substring cannot resolve offline).
+ *  `pinned` is the durable-pin decision for this change — decided by the CALLER
+ *  from the RAW pre-normalize token, never re-derived here from `spec`'s shape
+ *  (a concrete `spec` always reads as "pinned", which would wrongly re-pin a
+ *  deliberately chosen bare tier that happens to byte-equal a ladder cell). */
+export function persistDormantModel(nodeId, spec, pinned) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return;
+    const launch = meta.launch !== undefined ? { ...meta.launch, model: spec, modelProviderPinned: pinned } : undefined;
+    updateNode(nodeId, { model_override: spec, ...(launch !== undefined ? { launch } : {}) });
+}

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

@@ -0,0 +1,11 @@
+import type { NodeMeta } from '../canvas/index.js';
+/** 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 canvas-goal-capture naming hook passes a callback that calls
+ *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
+ *  same session, instead of waiting for the next revive/cycle. */
+export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;

package/dist/core/runtime/naming-persist.js

@@ -0,0 +1,41 @@
+// Session naming — canvas-coupled persistence seam.
+//
+// The pure naming machinery (headless pi call + slug fallbacks) lives in
+// naming.ts and stays canvas-free so CLI leaves can reach it without dragging
+// in canvas state. This one function is the only naming path that writes to a
+// node's meta, so it lives here — broker-side (canvas-goal-capture), never on a
+// CLI leaf's import graph.
+import { headlessName, sanitizeSessionName, slugFromPrompt } from './naming.js';
+import { getNode, updateNode } from '../canvas/index.js';
+/** 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 canvas-goal-capture naming hook 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
+        }
+    };
+    void headlessName(body).then((name) => {
+        persist(name !== '' ? name : slugFromPrompt(body));
+    });
+}

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

@@ -0,0 +1,26 @@
+/** Coerce arbitrary text into a 3-8 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 8 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;
+/** Ask pi headlessly for a kebab-case name for `body`, async. Resolves to the
+ *  sanitized name, or '' on any failure (non-zero exit, timeout, empty/garbled
+ *  output) so the caller can fall back to a local slug. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads
+ *  stdin, and execFile's default stdin is an OPEN pipe that never closes, so
+ *  without this pi blocks waiting for EOF and the call exits non-zero (the
+ *  regression that silently lost every LLM name to the slug fallback).
+ *
+ *  Exported (not just for tests): the canvas-coupled persistence wrapper
+ *  generateAndPersistName lives in naming-persist.ts to keep this module
+ *  canvas-free, and imports this pure helper. */
+export declare function headlessName(body: string): Promise<string>;
+/** A filesystem-safe slug for the `.todos/<slug>.md` fallback path: lowercase,
+ *  [a-z0-9] kept, everything else → single hyphen, clamped to 8 words. */
+export declare function titleSlug(title: string): string;
+/** Ask pi headlessly for a one-line issue title for `note`. Resolves to the
+ *  generated title, or a local first-line fallback on any failure (non-zero
+ *  exit, timeout, empty output). Async; never throws. */
+export declare function generateIssueTitle(note: string): Promise<string>;

package/dist/core/runtime/naming.js

@@ -0,0 +1,174 @@
+// Session naming — turn a node's first prompt into a short, human-readable
+// handle for the editor label.
+//
+// A node's editor label is `<mode-icon> <name> <kind>` (see editorLabel in
+// labels.ts). The `<name>` is a 3-8 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 updates the live session name.
+//
+// One entry point: generateAndPersistName — async (execFile, non-blocking).
+// Naming happens INSIDE the named node's own pi process, off the first real
+// message (the kickoff task or a human's first line), never on the spawn path:
+// blocking spawn on an LLM round-trip used to freeze the caller's terminal for
+// 2-3s on every `crtr node new`. The headless namer runs with --no-extensions,
+// so it loads no canvas hooks and can never recurse into another spawn/name.
+//
+// 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 { execFile } from 'node:child_process';
+import { bundledPiSubprocessEnv, resolveBundledPiCliPath } from './pi-cli.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-8 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-8 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 8 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, 8).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 piTextArgs(systemPrompt, userPrompt) {
+    const override = process.env['CRTR_NAME_MODEL'];
+    const model = override !== undefined && override.trim() !== '' ? override.trim() : DEFAULT_NAME_MODEL;
+    return [
+        '-p',
+        '--no-session',
+        '--no-context-files',
+        '--no-extensions',
+        '--no-skills',
+        '--no-prompt-templates',
+        '--no-themes',
+        '--no-tools',
+        '--mode', 'text',
+        // A trivial one-line classification — no thinking budget, ever.
+        '--thinking', 'off',
+        '--model', model,
+        '--system-prompt', systemPrompt,
+        userPrompt,
+    ];
+}
+function nameArgs(prompt) {
+    return piTextArgs(NAME_SYSTEM_PROMPT, nameUserPrompt(prompt));
+}
+/** Ask pi headlessly for a kebab-case name for `body`, async. Resolves to the
+ *  sanitized name, or '' on any failure (non-zero exit, timeout, empty/garbled
+ *  output) so the caller can fall back to a local slug. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads
+ *  stdin, and execFile's default stdin is an OPEN pipe that never closes, so
+ *  without this pi blocks waiting for EOF and the call exits non-zero (the
+ *  regression that silently lost every LLM name to the slug fallback).
+ *
+ *  Exported (not just for tests): the canvas-coupled persistence wrapper
+ *  generateAndPersistName lives in naming-persist.ts to keep this module
+ *  canvas-free, and imports this pure helper. */
+export function headlessName(body) {
+    return new Promise((resolve) => {
+        try {
+            const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...nameArgs(body)], { encoding: 'utf8', timeout: NAME_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve('');
+                resolve(sanitizeSessionName(stdout));
+            });
+            child.stdin?.end(); // immediate EOF — see the doc above
+        }
+        catch {
+            resolve('');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Issue titles — turn a free-text todo/idea/bug note into a short, human-readable
+// GitHub-issue title (sentence case, NOT kebab). Used by `crtr canvas issue new`.
+// ---------------------------------------------------------------------------
+const TITLE_SYSTEM_PROMPT = 'You write GitHub issue titles. Given a free-text note (a todo, idea, or bug ' +
+    'report), reply with ONLY a concise issue title: sentence case, 4-10 words, no ' +
+    'trailing period, no quotes, no prefix like "Bug:" or "Idea:", no markdown. ' +
+    'Capture the gist as an actionable title. Output JUST the title, nothing else.';
+function titleUserPrompt(note) {
+    return `<note>\n${note.slice(0, PROMPT_CAP)}\n</note>\n\nWrite a concise GitHub issue title for the note above. Output JUST the title, nothing else.`;
+}
+/** First non-empty line of `note`, trimmed and clamped to ~80 chars — the local
+ *  fallback title when the headless call fails. */
+function firstLineTitle(note) {
+    const line = (note ?? '').split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    const clamped = line.length > 80 ? `${line.slice(0, 77).trimEnd()}…` : line;
+    return clamped !== '' ? clamped : 'untitled';
+}
+/** A filesystem-safe slug for the `.todos/<slug>.md` fallback path: lowercase,
+ *  [a-z0-9] kept, everything else → single hyphen, clamped to 8 words. */
+export function titleSlug(title) {
+    const words = (title ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .split('-')
+        .filter((w) => w !== '');
+    return words.slice(0, 8).join('-') || 'untitled';
+}
+/** Ask pi headlessly for a one-line issue title for `note`. Resolves to the
+ *  generated title, or a local first-line fallback on any failure (non-zero
+ *  exit, timeout, empty output). Async; never throws. */
+export function generateIssueTitle(note) {
+    const body = (note ?? '').trim();
+    if (body === '')
+        return Promise.resolve('untitled');
+    return new Promise((resolve) => {
+        try {
+            const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...piTextArgs(TITLE_SYSTEM_PROMPT, titleUserPrompt(body))], { encoding: 'utf8', timeout: NAME_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve(firstLineTitle(body));
+                const t = stdout.trim().split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+                resolve(t !== '' ? t.replace(/^["']|["']$/g, '').replace(/\.$/, '') : firstLineTitle(body));
+            });
+            child.stdin?.end(); // immediate EOF — pi -p reads stdin (see headlessName)
+        }
+        catch {
+            resolve(firstLineTitle(body));
+        }
+    });
+}