@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,135 @@
+// 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'];
+/** Canonical user-facing grammar for a durable model override. Help and
+ *  recovery paths compose from this one phrase so accepted forms cannot drift. */
+export const MODEL_SPEC_FORMS = `an exact registered provider/id; provider/tier where provider is ${MODEL_PROVIDER_KEYS.join('|')} and tier is ${MODEL_STRENGTHS.join('|')}; ` +
+    `a bare tier (${MODEL_STRENGTHS.join('|')}); or a family alias (opus|sonnet|haiku)`;
+export const MODEL_SPEC_NEXT = `Pass ${MODEL_SPEC_FORMS}.`;
+/** 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 parseModelSpec(spec) {
+    const i = spec.lastIndexOf(':');
+    if (i <= 0)
+        return { modelSpec: spec };
+    const suffix = spec.slice(i + 1);
+    if (!THINKING_SUFFIXES.has(suffix))
+        return { modelSpec: spec };
+    return { modelSpec: spec.slice(0, i), thinkingLevel: suffix };
+}
+export function isUnknownModel(model) {
+    return model?.provider === 'unknown' && model.id === 'unknown' && model.api === 'unknown';
+}
+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,26 @@
+import { type NodeMeta } from '../canvas/index.js';
+import type { ModelIntent } from '../../types.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(node: Pick<NodeMeta, 'node_id' | 'pi_pid'>): boolean;
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  sends `set_model`, and resolves with the broker-resolved durable spec from its
+ *  `model_changed` frame. Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.
+ *  `intent` is the routing contract the CALLER derived from the RAW token
+ *  (`explicitModelIntent`); `spec` is already normalized, so its shape no longer
+ *  says whether the pick was portable. Undefined means an exact model. */
+export declare function setModelLive(nodeId: string, spec: string, intent: ModelIntent | undefined): Promise<string>;
+/** Write a model choice into a node's durable recipe: `model_override` (so
+ *  polymorphs preserve it via buildLaunchSpec) and `launch.model`. A
+ *  `userSelected` change also replaces the routing contract the next revive
+ *  replays: with an `intent`, `launch.modelIntent` + `CRTR_MODEL_INTENT` (the
+ *  route may rotate to another family at that strength); without one,
+ *  `launch.modelExact` (the model runs verbatim). `spec` must already be a
+ *  concrete `provider/id` (normalizeModel maps tiers/aliases; a bare substring
+ *  cannot resolve offline). */
+export declare function updateModelRecipe(meta: NodeMeta, spec: string, intent: ModelIntent | undefined, userSelected: boolean): Promise<NodeMeta>;
+/** Persist a user's model choice into a DORMANT node's durable recipe — the same
+ *  write the broker commits on a live switch. */
+export declare function persistDormantModel(nodeId: string, spec: string, intent: ModelIntent | undefined): Promise<void>;

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

@@ -0,0 +1,75 @@
+// 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 commits model_override + launch.model
+//            through crtrd before broadcasting the resolved durable spec, so this
+//            path never writes or rereads the canvas row itself.
+//   DORMANT — no live broker: write the durable recipe directly (mirroring exactly
+//            the canonical recipe update) 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(node) {
+    return isPidAlive(node.pi_pid) && existsSync(viewSocketPath(node.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 durable spec from its
+ *  `model_changed` frame. Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.
+ *  `intent` is the routing contract the CALLER derived from the RAW token
+ *  (`explicitModelIntent`); `spec` is already normalized, so its shape no longer
+ *  says whether the pick was portable. Undefined means an exact model. */
+export function setModelLive(nodeId, spec, intent) {
+    // `set_model` carries no frame id, so the ack is matched on `for` alone.
+    let resolvedSpec;
+    return oneShotControllerRequest({
+        nodeId,
+        what: 'the model switch',
+        ackFor: 'set_model',
+        frame: () => ({ type: 'set_model', model: spec, ...(intent !== undefined ? { intent } : {}) }),
+        observe: (frame) => {
+            if (frame.type === 'model_changed' && frame.spec !== null)
+                resolvedSpec = frame.spec;
+        },
+        result: () => resolvedSpec ?? spec,
+    });
+}
+/** Write a model choice into a node's durable recipe: `model_override` (so
+ *  polymorphs preserve it via buildLaunchSpec) and `launch.model`. A
+ *  `userSelected` change also replaces the routing contract the next revive
+ *  replays: with an `intent`, `launch.modelIntent` + `CRTR_MODEL_INTENT` (the
+ *  route may rotate to another family at that strength); without one,
+ *  `launch.modelExact` (the model runs verbatim). `spec` must already be a
+ *  concrete `provider/id` (normalizeModel maps tiers/aliases; a bare substring
+ *  cannot resolve offline). */
+export async function updateModelRecipe(meta, spec, intent, userSelected) {
+    const launch = meta.launch === undefined
+        ? undefined
+        : userSelected
+            ? (() => {
+                const { modelIntent: _modelIntent, modelExact: _modelExact, env, ...rest } = meta.launch;
+                const { CRTR_MODEL_INTENT: _intentEnv, ...remainingEnv } = env;
+                return intent !== undefined
+                    ? { ...rest, model: spec, modelIntent: intent, env: { ...remainingEnv, CRTR_MODEL_INTENT: `${intent.family}/${intent.strength}` } }
+                    : { ...rest, model: spec, modelExact: true, env: remainingEnv };
+            })()
+            : { ...meta.launch, model: spec };
+    return await updateNode(meta.node_id, { model_override: spec, ...(launch !== undefined ? { launch } : {}) });
+}
+/** Persist a user's model choice into a DORMANT node's durable recipe — the same
+ *  write the broker commits on a live switch. */
+export async function persistDormantModel(nodeId, spec, intent) {
+    const meta = await getNode(nodeId);
+    if (meta !== null)
+        await updateModelRecipe(meta, spec, intent, true);
+}

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

@@ -0,0 +1,69 @@
+/** 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;
+/** Coerce arbitrary text into a one-line prose title, or '' if nothing usable
+ *  survives. Takes the first non-empty line, collapses runs of whitespace, drops
+ *  wrapping quotes, clamps at a word boundary, and capitalizes the opening
+ *  letter. Punctuation INSIDE the line survives — carrying it is what `title`
+ *  is for. */
+export declare function sanitizeSessionTitle(raw: string): string;
+/** Local fallback: the opening of the prompt as a title (no pi call), with its
+ *  punctuation. Whitespace collapses first so a multi-line message contributes
+ *  its actual opening words rather than whatever its first line happened to be. */
+export declare function titleFromPrompt(prompt: string): string;
+/** Local fallback: derive a kebab handle straight from the prompt (no pi call),
+ *  from the same opening words the fallback title keeps. */
+export declare function slugFromPrompt(prompt: string): string;
+/** The namer's model: the `light` rung of the DEFAULT provider's ladder, with
+ *  any thinking suffix stripped because the one-shot session uses thinking off.
+ *  Reading the ladder rather than pinning a concrete model id keeps naming working for a
+ *  user who never configured Anthropic: an OpenAI default provider resolves to
+ *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
+export declare function lightModel(overrideEnv?: string): string;
+/** A generated session label: the kebab-case handle, the prose title, and the
+ *  Nerd Font glyph the namer chose. `title` is '' when the model gave nothing
+ *  usable, leaving the caller to fall back to the prompt's own opening words;
+ *  `icon` is '' on the same terms, and every surface renders the name alone in
+ *  that case. */
+export interface SessionName {
+    name: string;
+    title: string;
+    icon: string;
+}
+/** Normalize a model-supplied icon to a single renderable glyph, or '' when
+ *  nothing usable came back.
+ *
+ *  The model is asked for a `U+XXXX` codepoint rather than the literal
+ *  character: Nerd Font glyphs sit in the private-use areas, which models
+ *  reproduce unreliably as literal text (they tend to substitute an emoji), but
+ *  name accurately as codepoints. A literal glyph is still accepted — including
+ *  an emoji, which renders fine even if it is not the house style — so a model
+ *  that ignores the format still contributes. Rejects a spelled-out
+ *  `nf-fa-bug`, a bare ASCII letter, and anything multi-glyph, all of which
+ *  would render as noise or tofu in a label. */
+export declare function sanitizeIcon(raw: string): string;
+/** Ask Pi headlessly for a structured {name, title, icon} for `body`, async.
+ *  Resolves to a sanitized SessionName, or `{name:'',title:'',icon:''}` on
+ *  timeout, a missing tool call, or a malformed emission so the caller can fall
+ *  back to the prompt's own words.
+ *
+ *  Nothing FORCES the tool call — constrained sampling shapes the arguments once
+ *  the model decides to call it — so a model that answers in prose instead gets
+ *  one more attempt before the caller falls back.
+ *
+ *  This module stays canvas-free so CLI leaves can reach it. The canvas-coupled
+ *  commit path lives in pi-extensions/broker-local.ts, which imports this pure
+ *  helper and writes through crtrd's guarded generated-name operation. */
+export declare function headlessName(body: string, sourceCap?: number): Promise<SessionName>;
+/** Generate a name from a bounded conversation source rather than a single
+ *  kickoff message. The caller owns selecting representative conversation text;
+ *  this cap keeps the one-shot prompt compact. */
+export declare function headlessNameFromConversation(conversation: string): Promise<SessionName>;
+/** 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 timeout or empty output.
+ *  Async; never throws. */
+export declare function generateIssueTitle(note: string): Promise<string>;

package/dist/core/runtime/naming.js

@@ -0,0 +1,298 @@
+// Session naming — turn a node's first prompt into a short, human-readable
+// label.
+//
+// One call produces BOTH forms a surface needs, so no consumer has to un-mangle
+// the other's format: `name` is the 3-8 word kebab-case handle that sits in a
+// node's editor label (`<mode-icon> <name> <kind>`, see editorLabel in
+// labels.ts) and a tmux window name, `title` is the prose sentence a person
+// reads in a conversation list, punctuation intact.
+//
+// The namer returns a STRUCTURED result — {name, title, icon} — produced by
+// constrained sampling through the one-shot `name_session` tool, not by parsing
+// prose. The icon is a Nerd Font glyph the model picks freely
+// (guided by example blocks, not a closed enum) and is stored as its own meta
+// field, so each surface decides whether to render it.
+//
+// One entry point: generateAndPersistName — async and 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:
+// the one-shot runs asynchronously, so it delays only its eventual label. The
+// headless namer loads only provider rotation, so it carries no canvas hooks and
+// cannot recurse into 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 { headlessText, headlessToolCall } from './headless-pi.js';
+import { defaultProvider, modelLadders, stripThinkingSuffix } from './model-selection.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.
+ *  Generous because the structured path costs a tool round-trip on top of the
+ *  provider's own cold start; naming is async and off the spawn path, so a slow
+ *  call delays only the label, never the node. */
+const NAME_TIMEOUT_MS = 45_000;
+/** Nerd Font glyphs offered to the namer as a FALLBACK set for when a task has
+ *  no concrete subject — never a closed set, and deliberately introduced to the
+ *  model as the generic tier so it reaches for a real noun first. Measured
+ *  against 20 real prompts, an unqualified example list anchors the model onto
+ *  it almost totally; the two-step rule in the system prompt is what pulls picks
+ *  back out to the actual subject. */
+const ICON_EXAMPLES = [
+    'fixing/diagnosis: U+F188 bug, U+F0F1 stethoscope, U+F06D fire, U+F071 warning',
+    'building/changing code: U+F0AD wrench, U+F067 plus, U+F121 code, U+F085 cogs, U+F021 refresh',
+    'testing/verifying: U+F0C3 flask, U+F00C check, U+F24E balance',
+    'writing/docs/research: U+F02D book, U+F15C document, U+F002 magnifier, U+F0EB lightbulb',
+    'data/infra: U+F1C0 database, U+F0C2 cloud, U+F120 terminal, U+F013 gear, U+F1B3 packages',
+    'ship/perf/scale: U+F135 rocket, U+F0E7 bolt, U+F080 chart, U+F201 trend line',
+    'security/access: U+F132 shield, U+F023 lock, U+F084 key',
+    'interface/design: U+F1FC paintbrush, U+F03E image, U+F108 display',
+    'communication/coordination: U+F1D8 paper plane, U+F0E6 comments, U+F0E8 sitemap, U+F0C1 link',
+].join('\n');
+const NAME_SYSTEM_PROMPT = 'You label agent sessions. A session is whatever a person opened it for: a coding task, ' +
+    'a question, a piece of research, an idea they are turning over, or an ordinary ' +
+    'conversation. You are labelling that session, never taking part in it — do not answer ' +
+    'the message, do not do the work it asks for, do not comment on it. Every session gets a ' +
+    'label, however short, casual, misspelled, or open-ended its opening message is.\n\n' +
+    'Call the `name_session` tool exactly once with:\n' +
+    '- `title`: how a person would refer to this session in a list of their conversations — ' +
+    '2-8 words, sentence case, written naturally with its punctuation intact (e.g. ' +
+    "`What's your favorite color?`, `Payroll export mapping bug`, `Ideas for the launch " +
+    'email`). No quotes, no markdown, no trailing period.\n' +
+    '- `name`: the same subject as a concise 3-8 word kebab-case handle — lowercase words ' +
+    'joined by single hyphens (e.g. `favorite-color-question`, `refactor-auth-token-flow`). ' +
+    'No punctuation, quotes, or prose.\n' +
+    '- `icon`: ONE Nerd Font glyph, written as its codepoint in `U+XXXX` form (e.g. ' +
+    '`U+F188`). Emit a codepoint, not a name like `nf-fa-bug`, and not an emoji.\n\n' +
+    'Choosing the icon — work through it in this order:\n' +
+    '1. Name the concrete SUBJECT of the task: the thing being acted on. A font, a ' +
+    'trash can, an account, a browser tab, a clock, an invoice, a map, a robot, a specific ' +
+    "technology's logo. If a glyph depicts that thing, use it. This is almost always the " +
+    'better icon, because it is what distinguishes this session from every other one.\n' +
+    '2. Only when the task has no depictable subject, fall back to the ACTIVITY (fixing, ' +
+    'documenting, testing) using the generic set below.\n\n' +
+    'ANY Nerd Font codepoint is allowed and the set is enormous — the whole Font Awesome ' +
+    'range, Devicons and Seti technology logos, Octicons, Codicons, Weather, and the ' +
+    'thousands of Material Design nouns above U+F0001. Reach into it. The examples below ' +
+    'are the generic tier, NOT a menu: if your pick came from them and the task had a real ' +
+    'subject, you picked wrong. Never reuse a generic gear, wrench, or bug for a task that ' +
+    'is actually about something.\n\n' +
+    'Generic fallback set, by kind of work:\n' +
+    ICON_EXAMPLES;
+/** Put the source text FIRST in a delimited block, then the instruction, so the
+ *  model reads the work before being told what to do and never mistakes source
+ *  text for the instruction. The source is capped first, so the closing tag is
+ *  always present. */
+function nameUserPrompt(source, sourceCap = PROMPT_CAP) {
+    return `<source>\n${source.slice(0, sourceCap)}\n</source>\n\nLabel the session this text is from: call \`name_session\` once with a title, a name, and an icon depicting it, then stop. Do not answer it.`;
+}
+/** Cap on a generated title — room for a full sentence-case phrase, short
+ *  enough that a conversation list stays scannable. */
+const TITLE_CAP = 72;
+/** 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('-');
+}
+/** Coerce arbitrary text into a one-line prose title, or '' if nothing usable
+ *  survives. Takes the first non-empty line, collapses runs of whitespace, drops
+ *  wrapping quotes, clamps at a word boundary, and capitalizes the opening
+ *  letter. Punctuation INSIDE the line survives — carrying it is what `title`
+ *  is for. */
+export function sanitizeSessionTitle(raw) {
+    const line = (raw ?? '').split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    const collapsed = line.replace(/\s+/g, ' ').replace(/^["'`]+|["'`]+$/g, '').trim();
+    if (collapsed === '')
+        return '';
+    let clamped = collapsed;
+    if (collapsed.length > TITLE_CAP) {
+        const cut = collapsed.slice(0, TITLE_CAP);
+        const boundary = cut.lastIndexOf(' ');
+        clamped = `${(boundary > TITLE_CAP / 2 ? cut.slice(0, boundary) : cut).trimEnd()}\u2026`;
+    }
+    return clamped.charAt(0).toUpperCase() + clamped.slice(1);
+}
+/** Local fallback: the opening of the prompt as a title (no pi call), with its
+ *  punctuation. Whitespace collapses first so a multi-line message contributes
+ *  its actual opening words rather than whatever its first line happened to be. */
+export function titleFromPrompt(prompt) {
+    return sanitizeSessionTitle((prompt ?? '').replace(/\s+/g, ' '));
+}
+/** Local fallback: derive a kebab handle straight from the prompt (no pi call),
+ *  from the same opening words the fallback title keeps. */
+export function slugFromPrompt(prompt) {
+    return sanitizeSessionName(titleFromPrompt(prompt)) || 'session';
+}
+/** The namer's model: the `light` rung of the DEFAULT provider's ladder, with
+ *  any thinking suffix stripped because the one-shot session uses thinking off.
+ *  Reading the ladder rather than pinning a concrete model id keeps naming working for a
+ *  user who never configured Anthropic: an OpenAI default provider resolves to
+ *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
+export function lightModel(overrideEnv) {
+    const override = overrideEnv === undefined ? undefined : process.env[overrideEnv];
+    if (override !== undefined && override.trim() !== '')
+        return override.trim();
+    const ladders = modelLadders();
+    return stripThinkingSuffix(ladders[defaultProvider(ladders)].light);
+}
+function nameModelRequest() {
+    const override = process.env['CRTR_NAME_MODEL'];
+    if (override !== undefined && override.trim() !== '')
+        return { modelSpec: override.trim() };
+    const ladders = modelLadders();
+    const provider = defaultProvider(ladders);
+    return {
+        modelSpec: stripThinkingSuffix(ladders[provider].light),
+        modelIntent: `${provider}/light`,
+    };
+}
+const NAME_SESSION_SCHEMA = {
+    type: 'object',
+    properties: {
+        title: {
+            type: 'string',
+            description: 'A 2-8 word sentence-case title a person would recognize this session by in a list, with its punctuation intact, e.g. Payroll export mapping bug. No quotes, markdown, or trailing period.',
+        },
+        name: {
+            type: 'string',
+            description: 'A 3-8 word kebab-case session name: lowercase words joined by single hyphens, e.g. refactor-auth-token-flow. No punctuation, quotes, or prose.',
+        },
+        icon: {
+            type: 'string',
+            description: 'The Nerd Font glyph depicting this session, as a codepoint in U+XXXX form (e.g. U+F188).',
+        },
+    },
+    required: ['title', 'name', 'icon'],
+    additionalProperties: false,
+};
+/** Normalize a model-supplied icon to a single renderable glyph, or '' when
+ *  nothing usable came back.
+ *
+ *  The model is asked for a `U+XXXX` codepoint rather than the literal
+ *  character: Nerd Font glyphs sit in the private-use areas, which models
+ *  reproduce unreliably as literal text (they tend to substitute an emoji), but
+ *  name accurately as codepoints. A literal glyph is still accepted — including
+ *  an emoji, which renders fine even if it is not the house style — so a model
+ *  that ignores the format still contributes. Rejects a spelled-out
+ *  `nf-fa-bug`, a bare ASCII letter, and anything multi-glyph, all of which
+ *  would render as noise or tofu in a label. */
+export function sanitizeIcon(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed === '')
+        return '';
+    const codepoint = /^(?:u\+|0x|\\u\{?|&#x)?([0-9a-f]{4,6})\}?;?$/i.exec(trimmed);
+    if (codepoint !== null) {
+        const value = Number.parseInt(codepoint[1], 16);
+        // Anything below the symbol blocks is a letter/digit/control — not an icon.
+        if (value >= 0x2000 && value <= 0x10ffff) {
+            try {
+                return String.fromCodePoint(value);
+            }
+            catch {
+                return '';
+            }
+        }
+        return '';
+    }
+    const points = [...trimmed];
+    // A glyph, plus at most a variation selector.
+    if (points.length > 2)
+        return '';
+    return points[0].codePointAt(0) >= 0x2000 ? trimmed : '';
+}
+/** Ask Pi headlessly for a structured {name, title, icon} for `body`, async.
+ *  Resolves to a sanitized SessionName, or `{name:'',title:'',icon:''}` on
+ *  timeout, a missing tool call, or a malformed emission so the caller can fall
+ *  back to the prompt's own words.
+ *
+ *  Nothing FORCES the tool call — constrained sampling shapes the arguments once
+ *  the model decides to call it — so a model that answers in prose instead gets
+ *  one more attempt before the caller falls back.
+ *
+ *  This module stays canvas-free so CLI leaves can reach it. The canvas-coupled
+ *  commit path lives in pi-extensions/broker-local.ts, which imports this pure
+ *  helper and writes through crtrd's guarded generated-name operation. */
+export async function headlessName(body, sourceCap = PROMPT_CAP) {
+    const empty = { name: '', title: '', icon: '' };
+    const request = {
+        systemPrompt: NAME_SYSTEM_PROMPT,
+        userPrompt: nameUserPrompt(body, sourceCap),
+        ...nameModelRequest(),
+        timeoutMs: NAME_TIMEOUT_MS,
+        tool: {
+            name: 'name_session',
+            label: 'Name session',
+            description: 'Record the title, name, and icon for this session. Call exactly once, then stop.',
+            parameters: NAME_SESSION_SCHEMA,
+            constrainedSampling: { type: 'json_schema', strict: 'prefer' },
+        },
+    };
+    const emitted = await headlessToolCall(request) ?? await headlessToolCall(request);
+    if (emitted === null || typeof emitted !== 'object')
+        return empty;
+    const parsed = emitted;
+    const title = sanitizeSessionTitle(typeof parsed['title'] === 'string' ? parsed['title'] : '');
+    const name = sanitizeSessionName(typeof parsed['name'] === 'string' ? parsed['name'] : '')
+        || sanitizeSessionName(title);
+    const icon = sanitizeIcon(typeof parsed['icon'] === 'string' ? parsed['icon'] : '');
+    return name !== '' ? { name, title, icon } : empty;
+}
+/** Generate a name from a bounded conversation source rather than a single
+ *  kickoff message. The caller owns selecting representative conversation text;
+ *  this cap keeps the one-shot prompt compact. */
+export function headlessNameFromConversation(conversation) {
+    return headlessName(conversation, 30_000);
+}
+// 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 timeout or empty output.
+ *  Async; never throws. */
+export async function generateIssueTitle(note) {
+    const body = (note ?? '').trim();
+    if (body === '')
+        return 'untitled';
+    try {
+        const reply = await headlessText({
+            systemPrompt: TITLE_SYSTEM_PROMPT,
+            userPrompt: titleUserPrompt(body),
+            ...nameModelRequest(),
+            timeoutMs: NAME_TIMEOUT_MS,
+        });
+        const title = reply.split('\n').map((line) => line.trim()).find((line) => line !== '') ?? '';
+        return title !== '' ? title.replace(/^["']|["']$/g, '').replace(/\.$/, '') : firstLineTitle(body);
+    }
+    catch {
+        return firstLineTitle(body);
+    }
+}

package/dist/core/runtime/nerd-font.d.ts

@@ -0,0 +1,46 @@
+export interface NerdFontDetection {
+    /** A Nerd Font face is installed somewhere on this system. */
+    installed: boolean;
+    /** The family or filename that matched, for the doctor message. */
+    evidence: string | null;
+    /** How the match was found — fontconfig query, or a font-directory scan. */
+    source: 'fc-list' | 'font-dir' | null;
+}
+export declare function detectNerdFont(platform?: NodeJS.Platform, home?: string): NerdFontDetection;
+/** Download the upstream symbols-only patch into the user's font dir. Works on
+ *  every Linux regardless of package manager — Debian/Ubuntu and Fedora ship no
+ *  Nerd Font package, so there is nothing native to install there. Needs no
+ *  sudo: it writes to `~/.local/share/fonts`.
+ *
+ *  curl runs with its progress meter on (no `-s`) because this is the one
+ *  install step with a real download percentage: setup captures that stderr
+ *  and drives the step's progress bar from it (`parseCurlPercent`). */
+export declare const NERD_FONT_MANUAL_LINUX_COMMAND: string;
+/** Reads percent complete out of curl's default progress meter as its stderr
+ *  arrives. Rows are separated by `\r` and look like
+ *  `100  1234k  100  1234k    0     0   987k      0 --:--:-- …`; the leading
+ *  column is the percentage of the whole transfer, and the header rows
+ *  (`  % Total    % Received …`) start with `%` so they never match.
+ *
+ *  Stateful because curl's writes split rows anywhere: the tail of a chunk is
+ *  held back until its row is terminated. Reading a half-row instead lands on
+ *  a different column and reports a number that was never true — in practice
+ *  the completed download's own summary row parsed as 0%.
+ *
+ *  Returns the percentage of the last complete row in this chunk, or null when
+ *  the chunk completed no row. */
+export declare function createCurlPercentReader(): (chunk: string) => number | null;
+export interface NerdFontInstallCommand {
+    command: string | null;
+    hint: string;
+    autoInstall: boolean;
+}
+/** The install command for this platform/package manager. `packageManager`
+ *  matches setup's detection: only brew and pacman have a real Nerd Font
+ *  package, everything else on Linux gets the upstream download. A non-brew
+ *  package manager only ever exists on Linux, so it settles the platform on its
+ *  own and `platform` decides only the `manual` case. */
+export declare function nerdFontInstallCommand(packageManager: 'brew' | 'apt-get' | 'dnf' | 'pacman' | 'manual', platform?: NodeJS.Platform): NerdFontInstallCommand;
+/** Every install path ends the same way: the font is on disk but the terminal
+ *  emulator still has to be pointed at it, and crtr cannot do that. */
+export declare const NERD_FONT_SELECT_HINT = "then set your terminal profile's font to a Nerd Font (e.g. add \"Symbols Nerd Font Mono\" as the non-ASCII/fallback font) \u2014 installing it does not select it";