@north-light/api 0.3.580 → 0.3.587

package/dist/core/runs/questions.d.ts

@@ -0,0 +1,80 @@
+import { type CanvasDb } from '../canvas/db.js';
+import { type HumanRequestRecord } from '../human/requests.js';
+import { type PreparedPage } from '../human/page-authoring.js';
+import { type PageManifest } from '../human/page-schema.js';
+/**
+ * A question is a settleable human page request. Most belong to a run; a
+ * provider approval can also belong to an app without a run. Its question id
+ * is the human request id in either case.
+ */
+interface AskingNode {
+    node_id: string;
+    run_id: string;
+    grantee: string;
+}
+export interface ProviderQuestion {
+    question_id: string;
+    grantee: string;
+    sub: string;
+    provider: string;
+    tool: string;
+    status: 'open' | 'answered' | 'consumed' | 'canceled';
+    option_id: string | null;
+}
+/** The provider's prompt is displayed by the same human page mechanism as run questions. */
+export declare function providerApprovalPage(question: {
+    title: string;
+    body: string;
+    options: Array<{
+        option_id: string;
+        label: string;
+    }>;
+}): PreparedPage;
+export declare function manifestOf(request: HumanRequestRecord): PageManifest;
+/** The question's run, asking node, and app, or null when the request is not a question. */
+export declare function questionRun(request: HumanRequestRecord, db?: CanvasDb): Promise<AskingNode | null>;
+export type QuestionKind = 'decision' | 'notice';
+/** A decision asks for a response; a notice takes none and is acknowledged with empty responses. */
+export declare function questionKind(request: HumanRequestRecord): QuestionKind;
+/** Called inside the page request's creating write: carries a new question on its run's stream. */
+export declare function appendWaitingOnUser(db: CanvasDb, request: HumanRequestRecord): Promise<void>;
+/** Called inside the settling write: an answered question emits `question.answered`. */
+export declare function appendQuestionAnswered(db: CanvasDb, request: HumanRequestRecord): Promise<void>;
+/** Open decisions raised by any node of the run, oldest first; a notice never counts. */
+export declare function openQuestionIds(runId: string, db?: CanvasDb): Promise<string[]>;
+/** Open notices raised by any node of the run, oldest first. */
+export declare function openNoticeIds(runId: string, db?: CanvasDb): Promise<string[]>;
+export type QuestionStatus = 'open' | 'answered' | 'canceled';
+export declare function questionStatus(request: HumanRequestRecord): QuestionStatus;
+/** The stored answer or cancellation of a settled question. */
+export declare function questionResult(request: HumanRequestRecord): unknown;
+/** The `question.get` shape. */
+export declare function questionObject(request: HumanRequestRecord, run: AskingNode | null, approval?: ProviderQuestion | null): Promise<Record<string, unknown>>;
+/** A question by id, with its run or an app-owned runless provider approval. */
+export declare function getQuestion(questionId: string): Promise<{
+    request: HumanRequestRecord;
+    run: AskingNode | null;
+    approval: ProviderQuestion | null;
+} | null>;
+/** Open question ids scoped to a run, one asking node, or every run of an app. */
+export declare function openQuestionIdsFor(target: {
+    run_id: string;
+} | {
+    node_id: string;
+} | {
+    grantee: string;
+}): Promise<string[]>;
+/**
+ * Cancel the open questions of a run, of one asking node, or of every run of an
+ * app, through the page mechanism's own cancel (`settleHumanRequest`, first
+ * writer wins): each becomes `canceled` and can never be answered afterwards.
+ * Answers how many this call canceled.
+ */
+export declare function cancelOpenQuestions(target: {
+    run_id: string;
+} | {
+    node_id: string;
+} | {
+    grantee: string;
+}, reason: string): Promise<number>;
+export {};

package/dist/core/runs/questions.js

@@ -0,0 +1,151 @@
+import { openDb } from '../canvas/db.js';
+import { askingNodeSql, getRequest } from '../human/requests.js';
+import { preparePageSource } from '../human/page-authoring.js';
+import { pageAwaitsResponse } from '../human/page-schema.js';
+import { appendRunEvent } from './events.js';
+async function providerQuestion(db, questionId) {
+    return await db.prepare('SELECT question_id, grantee, sub, provider, tool, status, option_id FROM provider_approvals WHERE question_id = ?').get(questionId) ?? null;
+}
+/** The provider's prompt is displayed by the same human page mechanism as run questions. */
+export function providerApprovalPage(question) {
+    if (!question.title.trim() || !question.body.trim() || !Array.isArray(question.options) || question.options.length === 0)
+        throw new Error('provider approval needs a title, body, and options');
+    const ids = new Set(['deny']);
+    for (const option of question.options) {
+        if (!option.option_id || !option.label || ids.has(option.option_id))
+            throw new Error('provider approval option ids must be nonempty, unique, and different from deny');
+        ids.add(option.option_id);
+    }
+    const options = [...question.options.map(({ option_id, label }) => ({ id: option_id, label })), { id: 'deny', label: "Don't do this" }];
+    const document = `export default function Approval() { return <Page title={${JSON.stringify(question.title)}}><UserQuestion id="options" label="Choose an option" body={${JSON.stringify(question.body)}} mode="single" required={true} allowFreetext={false} options={${JSON.stringify(options)}} /></Page>; }`;
+    return preparePageSource({ dialect: 'jsx', document, delivery: { placement: 'inline', inbox: false, reply: true } });
+}
+async function askingNode(db, nodeId) {
+    if (nodeId === null)
+        return null;
+    const row = await db.prepare('SELECT node_id, run_id, grantee FROM node_rows WHERE node_id = ? AND run_id IS NOT NULL').get(nodeId);
+    return row ?? null;
+}
+export function manifestOf(request) {
+    return JSON.parse(request.specification_json);
+}
+/** The question's run, asking node, and app, or null when the request is not a question. */
+export async function questionRun(request, db) {
+    db ??= await openDb();
+    if (request.kind !== 'page' || !request.settleable)
+        return null;
+    const manifest = manifestOf(request);
+    // Only a notice, which has no reply route, belongs to the node that sent it; a decision needs its requester.
+    return await askingNode(db, request.requester_node_id ?? (pageAwaitsResponse(manifest) ? null : manifest.source?.nodeId ?? null));
+}
+/** A decision asks for a response; a notice takes none and is acknowledged with empty responses. */
+export function questionKind(request) {
+    return pageAwaitsResponse(manifestOf(request)) ? 'decision' : 'notice';
+}
+/** The fields `waiting_on_user` and `question.get` share. */
+async function questionFields(request, grantee, db) {
+    db ??= await openDb();
+    const manifest = manifestOf(request);
+    const approval = await providerQuestion(db, request.request_id);
+    return {
+        question_id: request.request_id, initiating_app: grantee, title: request.title,
+        ...(request.subtitle ? { subtitle: request.subtitle } : {}),
+        ...(approval ? { provider: approval.provider, tool: approval.tool } : {}),
+        steps: manifest.steps,
+        slots: manifest.slots.map((slot) => ({ ...(slot.id === undefined ? {} : { id: slot.id }), kind: slot.kind, step: slot.step, config: slot.config })),
+    };
+}
+/** Called inside the page request's creating write: carries a new question on its run's stream. */
+export async function appendWaitingOnUser(db, request) {
+    const run = await questionRun(request, db);
+    if (run === null || request.state !== 'open' || questionKind(request) === 'notice')
+        return;
+    await appendRunEvent(db, run.run_id, run.node_id, 'waiting_on_user', await questionFields(request, run.grantee, db));
+}
+/** Called inside the settling write: an answered question emits `question.answered`. */
+export async function appendQuestionAnswered(db, request) {
+    const result = request.result_json === null ? null : JSON.parse(request.result_json);
+    const approval = await providerQuestion(db, request.request_id);
+    if (approval !== null) {
+        const optionId = result?.responses?.options?.selectedOptionIds?.[0];
+        if (request.outcome === 'answered' && (typeof optionId !== 'string' || !optionId))
+            throw new Error(`provider approval ${request.request_id} has no selected option`);
+        await db.prepare(`UPDATE provider_approvals SET status = ?, option_id = ? WHERE question_id = ? AND status = 'open'`)
+            .run(request.outcome === 'answered' ? 'answered' : 'canceled', request.outcome === 'answered' ? optionId : null, request.request_id);
+    }
+    if (request.outcome !== 'answered' || result === null)
+        return;
+    const run = await questionRun(request, db);
+    if (run === null)
+        return;
+    await appendRunEvent(db, run.run_id, run.node_id, 'question.answered', { question_id: request.request_id, answer: result.responses ?? {} });
+}
+/** Open questions of one kind raised by any node of the run, oldest first. */
+async function openIdsOfKind(runId, kind, db) {
+    return (await db.prepare(`SELECT h.request_id, h.specification_json FROM human_requests h JOIN node_rows n ON n.node_id = ${askingNodeSql('h')}
+    WHERE n.run_id = ? AND h.kind = 'page' AND h.state = 'open' AND h.settleable = 1
+    ORDER BY h.created_at, h.request_id`).all(runId))
+        .filter((row) => pageAwaitsResponse(JSON.parse(row.specification_json)) === (kind === 'decision'))
+        .map((row) => row.request_id);
+}
+/** Open decisions raised by any node of the run, oldest first; a notice never counts. */
+export async function openQuestionIds(runId, db) { db ??= await openDb(); return await openIdsOfKind(runId, 'decision', db); }
+/** Open notices raised by any node of the run, oldest first. */
+export async function openNoticeIds(runId, db) { db ??= await openDb(); return await openIdsOfKind(runId, 'notice', db); }
+export function questionStatus(request) {
+    if (request.state !== 'settled')
+        return 'open';
+    return request.outcome === 'answered' ? 'answered' : 'canceled';
+}
+/** The stored answer or cancellation of a settled question. */
+export function questionResult(request) {
+    if (request.result_json === null)
+        return null;
+    const result = JSON.parse(request.result_json);
+    return request.outcome === 'answered' ? result.responses ?? {} : result;
+}
+/** The `question.get` shape. */
+export async function questionObject(request, run, approval) {
+    const status = questionStatus(request);
+    return {
+        ...await questionFields(request, run?.grantee ?? approval.grantee), kind: questionKind(request),
+        ...(run === null ? {} : { run_id: run.run_id, node_id: run.node_id }), status,
+        ...(status === 'answered' ? { answer: questionResult(request) } : {}),
+    };
+}
+/** A question by id, with its run or an app-owned runless provider approval. */
+export async function getQuestion(questionId) {
+    const request = await getRequest(questionId);
+    if (request === null || request.kind !== 'page' || !request.settleable)
+        return null;
+    const db = await openDb();
+    const run = await questionRun(request, db);
+    const approval = await providerQuestion(db, questionId);
+    return run === null && approval === null ? null : { request, run, approval };
+}
+/** Open question ids scoped to a run, one asking node, or every run of an app. */
+export async function openQuestionIdsFor(target) {
+    const [where, value] = 'run_id' in target ? ['n.run_id = ?', target.run_id] : 'node_id' in target ? ['n.node_id = ?', target.node_id] : ['n.grantee = ?', target.grantee];
+    return (await (await openDb()).prepareUncached(`SELECT h.request_id FROM human_requests h JOIN node_rows n ON n.node_id = ${askingNodeSql('h')}
+    WHERE ${where} AND n.run_id IS NOT NULL AND h.kind = 'page' AND h.state = 'open' AND h.settleable = 1`).all(value)).map((row) => row.request_id);
+}
+/**
+ * Cancel the open questions of a run, of one asking node, or of every run of an
+ * app, through the page mechanism's own cancel (`settleHumanRequest`, first
+ * writer wins): each becomes `canceled` and can never be answered afterwards.
+ * Answers how many this call canceled.
+ */
+export async function cancelOpenQuestions(target, reason) {
+    const ids = await openQuestionIdsFor(target);
+    if (!ids.length)
+        return 0;
+    // Loaded lazily: the settle path imports the request store, which imports this module.
+    const { cancelHumanTicket } = await import('../../daemon/human/finish.js');
+    let canceled = 0;
+    for (const id of ids) {
+        const settled = await cancelHumanTicket(id, { reason, actor: 'crtrd' });
+        if (settled.outcome === 'settled')
+            canceled += 1;
+    }
+    return canceled;
+}

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

@@ -0,0 +1,15 @@
+export interface BannerInfo {
+    /** crtr version, e.g. "0.3.78" → shown as "v0.3.78". */
+    version?: string;
+    /** Active profile name, e.g. "acme". */
+    profile?: string;
+    /** Launch directory (already home-abbreviated if desired). */
+    cwd?: string;
+    /** One dim line under the cube (e.g. the tmux survival hint). */
+    hint?: string;
+}
+/** The crouton banner as pre-colored terminal lines: the cube on the left with
+ *  name/version, tagline, profile, and launch path stacked beside rows 1–4.
+ *  Missing facts are simply omitted (their row shows just the cube). No
+ *  leading/trailing blank lines — the caller frames it. */
+export declare function croutonBannerLines(info?: BannerInfo): string[];

package/dist/core/runtime/banner.js

@@ -0,0 +1,53 @@
+// The crouton welcome banner — a little crouton rendered at the very top of a
+// node's transcript in the attach viewer (the way Claude Code opens with its
+// logo + session facts), with the launch facts stacked to its right: name +
+// version, tagline, profile, and the launch path. It scrolls up into history as
+// the conversation grows. Purely cosmetic.
+//
+// This lives in the VIEWER, not the front-door stdout: the attach TUI takes over
+// the whole terminal, so anything printed to stdout before it starts is wiped.
+// ChatView pins these lines as the first children of its chat container.
+// Clean line-art isometric cube in a single warm crust tone, with a few subtly
+// darker toast flecks. No background fills (they read as detached color slabs in
+// a dark terminal) and no inverted-brightness speckle.
+const RESET = '\u001b[0m';
+const CRUST = '\u001b[38;5;180m'; // warm tan — cube outline + accents
+const FLECK = '\u001b[38;5;137m'; // slightly darker toast dots
+const BOLD = '\u001b[1m';
+const DIM = '\u001b[2m';
+// Darker toast flecks on the cube faces; `.` glyphs recolor a touch darker.
+function crumb(text) {
+    return CRUST + text.replace(/\./g, `${FLECK}.${CRUST}`) + RESET;
+}
+// Rows 1–4 all share the same visible width (15 cells), so a fixed 3-space
+// gutter lands every info line in the same column — the stacked-facts layout.
+const CROUTON = [
+    crumb('      ________'),
+    crumb('     /       /|'),
+    crumb('    /  .  . / |'),
+    crumb('   /_______/  |'),
+    crumb('   |  .  . |  |'),
+    crumb('   | .   . | /'),
+    crumb('   |_______|/'),
+];
+/** The crouton banner as pre-colored terminal lines: the cube on the left with
+ *  name/version, tagline, profile, and launch path stacked beside rows 1–4.
+ *  Missing facts are simply omitted (their row shows just the cube). No
+ *  leading/trailing blank lines — the caller frames it. */
+export function croutonBannerLines(info = {}) {
+    const name = `${BOLD}${CRUST}crouter${RESET}${info.version ? `${DIM}  v${info.version}${RESET}` : ''}`;
+    const facts = [name, `${DIM}the agentic runtime${RESET}`];
+    if (info.profile)
+        facts.push(`${DIM}profile: ${RESET}${CRUST}${info.profile}${RESET}`);
+    if (info.cwd)
+        facts.push(`${DIM}${info.cwd}${RESET}`);
+    const out = [];
+    for (let i = 0; i < CROUTON.length; i++) {
+        // Facts sit beside rows 1..N (the top of the cube), one per row.
+        const fact = i >= 1 && i - 1 < facts.length ? `   ${facts[i - 1]}` : '';
+        out.push(CROUTON[i] + fact);
+    }
+    if (info.hint)
+        out.push('', `${DIM}${info.hint}${RESET}`);
+    return out;
+}

package/dist/core/runtime/bearings-render.d.ts

@@ -0,0 +1,62 @@
+import { type NamedNode } from '../canvas/labels.js';
+export declare function escapeAttribute(value: string): string;
+/** The `<project_context>` block — the `<environment>` snapshot only: a
+ *  host/runtime line (platform, hostname, node version, tmux-or-not — the
+ *  headless engine's own process env, which its bash tools inherit), the cwd
+ *  dir listing, and git status/worktrees. Project guidance lives in the
+ *  document substrate, so this wrapper stays environment-only. It always emits
+ *  because the environment snapshot is always present. */
+export declare function buildProjectContextBlock(cwd: string): string;
+/** The documents-and-context-directory note — says where documents written for
+ *  another reader live (canvas documents the node owns, pointed at by name) and
+ *  names the context directory path INLINE (no XML attribute, so it never scopes
+ *  a sibling block) as the place for files that are not documents. Present for
+ *  every node, rendered as the `## Your documents and context directory`
+ *  subsection of <crtr-bearings>. */
+export declare function contextDirNote(nodeId: string, grantee?: string): string;
+/** The profile-purview note — rendered ONLY when the profile resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws. This absolute-path
+ *  disclosure is intentional (spec-approved): the agent must know its full
+ *  purview, not a redacted count. */
+export declare function profileNote(cwd: string, profileId: string | null | undefined): string;
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so the documents it owns are also where a future cycle of itself resumes the
+ *  work. Used inside the bearings block (both lanes) AND in the promotion
+ *  guidance, so a promoted node gets the same note a born-orchestrator gets. */
+export declare function orchestratorContextNote(): string;
+/** The fork's context note: the fork's own context directory replaces the
+ *  source's for files, and the source's documents stay the source's — a bare
+ *  document name in the copied conversation now needs the source's prefix. */
+export declare function forkContextNote(nodeId: string, grantee: string | undefined, sourceId: string): string;
+export interface RelativeLabelNode extends NamedNode {
+    node_id: string;
+    kind: string;
+    status: string;
+    name: string;
+    description?: string;
+    icon?: string;
+}
+/** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
+ *  task description when it carries one (orientation: what that relative is for). */
+export declare function relativeLabel(node: RelativeLabelNode): string;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). */
+export declare function renderGraphMap(nodeId: string, kind: string, mode: string, trunk: readonly RelativeLabelNode[], children: readonly RelativeLabelNode[]): string;
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. The caller
+ *  resolves `sourceLabel`: the bare `forkFrom` id when the source lookup
+ *  fails/is unsafe, else `${forkFrom} ("${fullName(src)}")`. */
+export declare function buildIdentityAssertion(nodeId: string, kind: string, mode: string, forkFrom: string | null | undefined, sourceLabel: string): string;
+export interface ManagedWorktreeLike {
+    state: string;
+    path: string;
+    branch: string;
+    base_ref: string;
+    base_sha: string;
+}
+export declare function worktreeNote(worktree: ManagedWorktreeLike | null | undefined): string;

package/dist/core/runtime/bearings-render.js

@@ -0,0 +1,272 @@
+// bearings-render.ts — the pure rendering core shared by bearings.ts (canvas-
+// backed, warm-spare live-delivery + cron-wake lanes) and broker-extension-
+// render.ts (DTO-backed, broker-side cold-boot lane). Both lanes render
+// byte-identical bearings for a real node; this module holds every function
+// that does not need canvas.db to do it.
+//
+// No import of canvas.js/db.js/canvas/index.js — only canvas/paths.js and
+// canvas/labels.js (both already db.ts-free), substrate-free, plus node
+// builtins. This keeps broker-extension-canvas-db-boundary.test.ts's static
+// import walk green with no changes to that test.
+import { contextDir } from '../canvas/paths.js';
+import { fullName } from '../canvas/labels.js';
+import { tmuxSessionsReachable } from './tmux-driver.js';
+import { spawnSync } from 'node:child_process';
+import { readdirBeneath } from '../spaces/open-beneath.js';
+import { hostname } from 'node:os';
+import { loadProfileManifest } from '../profiles/manifest.js';
+export function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+/** A one-line snapshot of the host/runtime the node's engine is executing in —
+ *  platform, hostname, node version, and whether a tmux server is reachable.
+ *  The engine is headless, so this reflects the broker/daemon environment the
+ *  node's own bash tools inherit — NOT a viewer pane.
+ *
+ *  The tmux bit deliberately reports SERVER REACHABILITY, not "am I inside a
+ *  tmux pane" — the latter is a constant `no` for every node and so tells the
+ *  agent nothing: a broker is detached and paneless, and DELETES $TMUX /
+ *  $TMUX_PANE from its env on boot (broker.ts) so its children never act on the
+ *  launching parent's pane. The actionable question is whether this process's
+ *  bash tools can drive tmux at all, and `tmuxSessionsReachable()` exits 0 iff
+ *  a server is running with at least one session. The label says `tmux server`
+ *  so it cannot be misread as pane residency. */
+function runtimeLine() {
+    const tmuxServer = tmuxSessionsReachable();
+    const parts = [
+        `${process.platform} ${process.arch}`,
+        hostname(),
+        `node ${process.version}`,
+        `tmux server: ${tmuxServer ? 'reachable' : 'none'}`,
+    ];
+    return `Host: ${parts.join(' · ')}`;
+}
+/** The cwd can be app-writable, so on Linux it is listed only when no symlink
+ *  is on its path; otherwise the listing reads as unavailable. */
+function directoryListingLines(cwd) {
+    try {
+        const entries = readdirBeneath('/', cwd);
+        const sorted = entries.sort((a, b) => {
+            if (a.isDirectory() !== b.isDirectory())
+                return a.isDirectory() ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        const shown = sorted.slice(0, 50).map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
+        const hidden = sorted.length - shown.length;
+        return hidden > 0 ? [...shown, `[+${hidden} more]`] : shown;
+    }
+    catch {
+        return ['Directory listing: unavailable (cwd missing or unreadable).'];
+    }
+}
+function runCommand(cwd, cmd, args, env) {
+    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8', ...(env === undefined ? {} : { env }) });
+    if (result.error !== undefined) {
+        return { ok: false, stdout: '', stderr: result.error.message };
+    }
+    return {
+        ok: result.status === 0,
+        stdout: (result.stdout ?? '').trim(),
+        stderr: (result.stderr ?? '').trim(),
+    };
+}
+/** This snapshot renders on every node boot and every revive, which makes it the
+ *  most frequent git caller in the runtime — and boot is exactly when a process
+ *  gets killed. `git status` would take `.git/index.lock` to refresh the stat
+ *  cache; suppressing that optional lock keeps an interrupted render from
+ *  orphaning a lock that then blocks every writer in the user's checkout.
+ *  Only optional locks are affected, and the output is unchanged.
+ *
+ *  crtrd runs this git in a node's cwd, which an app can write, so a `.git`
+ *  planted there (core.fsmonitor, filter drivers) would run as crtrd. Git's
+ *  ownership check refuses a repository crtrd does not own; no system,
+ *  global, or env-carried `-c` config is read, so no `safe.directory` entry
+ *  can switch that check off. */
+function gitEnv() {
+    const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' };
+    delete env.GIT_CONFIG_PARAMETERS;
+    delete env.GIT_CONFIG_COUNT;
+    return env;
+}
+function runGit(cwd, args) {
+    const result = runCommand(cwd, 'git', args, gitEnv());
+    return result.ok ? result.stdout : '';
+}
+function parseWorktrees(lines) {
+    const worktrees = [];
+    let cur = {};
+    for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+            if (cur.path !== undefined) {
+                worktrees.push({ path: cur.path, branch: cur.branch ?? 'detached HEAD' });
+            }
+            cur = { path: line.slice('worktree '.length) };
+        }
+        else if (line.startsWith('branch ')) {
+            cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        }
+    }
+    if (cur.path !== undefined) {
+        worktrees.push({ path: cur.path, branch: cur.branch ?? 'detached HEAD' });
+    }
+    return worktrees;
+}
+/** The git status/worktree snapshot lines. The initial probe distinguishes a
+ *  genuine non-repo (`not a git repository` in stderr) from any other failure
+ *  (spawn error, permission, a hung/killed process) — collapsing both into
+ *  "not a git repository" would mislabel a real outage as a documented,
+ *  benign state. Every other probe here is genuinely optional and already
+ *  falls back to 'unknown'/'HEAD'/a zero count on failure, which stays as-is. */
+function gitSnapshotLines(cwd) {
+    const probe = runCommand(cwd, 'git', ['rev-parse', '--is-inside-work-tree'], gitEnv());
+    if (!probe.ok) {
+        if (/not a git repository/i.test(probe.stderr)) {
+            return ['Git: not a git repository.'];
+        }
+        return [`Git: unavailable (${probe.stderr || 'git command failed'}).`];
+    }
+    const branch = runGit(cwd, ['branch', '--show-current']) || runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']) || 'HEAD';
+    const sha = runGit(cwd, ['rev-parse', '--short', 'HEAD']) || 'unknown';
+    const statusCount = runGit(cwd, ['status', '--porcelain'])
+        .split('\n')
+        .filter((line) => line !== '').length;
+    const worktreeLines = runGit(cwd, ['worktree', 'list', '--porcelain']).split('\n');
+    const worktrees = parseWorktrees(worktreeLines);
+    const dirty = statusCount === 0 ? 'clean' : `${statusCount} uncommitted change${statusCount === 1 ? '' : 's'}`;
+    const summary = `Git: ${branch} @ ${sha}; ${dirty}; ${worktrees.length} worktree${worktrees.length === 1 ? '' : 's'}.`;
+    const worktreeSummary = worktrees.length === 0
+        ? 'Worktrees: none.'
+        : `Worktrees: ${worktrees.map((w) => `${w.path} (${w.branch})`).join(', ')}`;
+    return [summary, worktreeSummary];
+}
+/** The `<project_context>` block — the `<environment>` snapshot only: a
+ *  host/runtime line (platform, hostname, node version, tmux-or-not — the
+ *  headless engine's own process env, which its bash tools inherit), the cwd
+ *  dir listing, and git status/worktrees. Project guidance lives in the
+ *  document substrate, so this wrapper stays environment-only. It always emits
+ *  because the environment snapshot is always present. */
+export function buildProjectContextBlock(cwd) {
+    const envLines = directoryListingLines(cwd);
+    const gitLines = gitSnapshotLines(cwd);
+    let out = '<project_context>\n\n';
+    out += `<environment cwd="${escapeAttribute(cwd)}">\n`;
+    out += `${runtimeLine()}\n`;
+    out += `Directory:\n${envLines.map((line) => `  ${line}`).join('\n')}\n`;
+    out += `${gitLines.map((line) => `${line}`).join('\n')}\n`;
+    out += '</environment>\n</project_context>';
+    return out;
+}
+/** The documents-and-context-directory note — says where documents written for
+ *  another reader live (canvas documents the node owns, pointed at by name) and
+ *  names the context directory path INLINE (no XML attribute, so it never scopes
+ *  a sibling block) as the place for files that are not documents. Present for
+ *  every node, rendered as the `## Your documents and context directory`
+ *  subsection of <crtr-bearings>. */
+export function contextDirNote(nodeId, grantee) {
+    return ('Documents you write for another reader — specs, designs, findings, maps, plans — are canvas ' +
+        'documents you own: write one with `crtr doc write <name>` (see `crtr doc write -h`), and point at ' +
+        `it by the name it prints, \`[[${nodeId}/<name>]]\`, never by a file path; other nodes read it with ` +
+        '`crtr canvas read`, and inside this node the bare name resolves too. Your context directory ' +
+        `\`${contextDir(nodeId, grantee)}\` (also \`$CRTR_CONTEXT_DIR\`) holds only what is not a document: ` +
+        'scripts, data, logs and page modules. Your working dir is the project, NOT this directory, so a ' +
+        'bare relative `context/...` lands in the repo, not here.');
+}
+/** The profile-purview note — rendered ONLY when the profile resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws. This absolute-path
+ *  disclosure is intentional (spec-approved): the agent must know its full
+ *  purview, not a redacted count. */
+export function profileNote(cwd, profileId) {
+    if (profileId === undefined || profileId === null || profileId === '')
+        return '';
+    let entry;
+    try {
+        entry = loadProfileManifest(profileId);
+    }
+    catch {
+        return '';
+    }
+    const projects = entry.manifest.projects.map((project) => project.path);
+    if (projects.length === 0)
+        return '';
+    return (`Your working dir is \`${cwd}\`. Your profile **${entry.manifest.name}** also has purview ` +
+        `over: ${projects.join(', ')}.`);
+}
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so the documents it owns are also where a future cycle of itself resumes the
+ *  work. Used inside the bearings block (both lanes) AND in the promotion
+ *  guidance, so a promoted node gets the same note a born-orchestrator gets. */
+export function orchestratorContextNote() {
+    return ('Because you persist across refresh cycles, the documents you own are also where a future cycle ' +
+        'of you resumes the work: your document `roadmap` loads at every new session, and it points at ' +
+        'the documents holding the decisions and findings a refreshed you would need, alongside the ones ' +
+        'you share with the nodes you spawn.');
+}
+/** The fork's context note: the fork's own context directory replaces the
+ *  source's for files, and the source's documents stay the source's — a bare
+ *  document name in the copied conversation now needs the source's prefix. */
+export function forkContextNote(nodeId, grantee, sourceId) {
+    return (`Context directory: \`${contextDir(nodeId, grantee)}\` (\`$CRTR_CONTEXT_DIR\`), for files only; use it ` +
+        'in place of every source-node context path above. Documents you write are yours. The source ' +
+        `node's documents stay the source's: read them as \`[[${sourceId}/<name>]]\`, and a bare document ` +
+        'name in the copied conversation that meant one of them now needs that prefix.');
+}
+/** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
+ *  task description when it carries one (orientation: what that relative is for). */
+export function relativeLabel(node) {
+    const desc = fullName(node);
+    const descPart = desc !== '' && desc !== node.kind && desc !== node.name ? ` — ${desc}` : '';
+    return `${node.node_id} (${node.kind} · ${node.status})${descPart}`;
+}
+/** Most children listed in the mini-map before the rest collapse to `+N more`. */
+const MAX_CHILDREN_SHOWN = 5;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). */
+export function renderGraphMap(nodeId, kind, mode, trunk, children) {
+    if (trunk.length === 0 && children.length === 0)
+        return '';
+    const indent = (depth) => '  '.repeat(depth);
+    const lines = [
+        'Your place in the canvas graph (ancestry above you, your direct children below):',
+    ];
+    trunk.forEach((m, i) => {
+        lines.push(`${indent(i)}${i === 0 ? '' : '└ '}${relativeLabel(m)}`);
+    });
+    const selfDepth = trunk.length;
+    lines.push(`${indent(selfDepth)}${selfDepth === 0 ? '' : '└ '}● you: ${nodeId} (${kind}, ${mode})`);
+    // Cap the child list so a wide fan-out can't flood the boot context. Children
+    // are sorted live-first, so the shown slice favors active nodes; the rest
+    // collapse to a `+N more` tail (active-first ordering means anything elided is
+    // the most-finished work).
+    const shown = children.slice(0, MAX_CHILDREN_SHOWN);
+    const hidden = children.length - shown.length;
+    shown.forEach((m, i) => {
+        const last = i === shown.length - 1 && hidden === 0;
+        lines.push(`${indent(selfDepth + 1)}${last ? '└ ' : '├ '}${relativeLabel(m)}`);
+    });
+    if (hidden > 0) {
+        lines.push(`${indent(selfDepth + 1)}└ +${hidden} more`);
+    }
+    return lines.join('\n');
+}
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. The caller
+ *  resolves `sourceLabel`: the bare `forkFrom` id when the source lookup
+ *  fails/is unsafe, else `${forkFrom} ("${fullName(src)}")`. */
+export function buildIdentityAssertion(nodeId, kind, mode, forkFrom, sourceLabel) {
+    const lines = [`You are node ${nodeId} — kind ${kind}, mode ${mode}.`];
+    if (forkFrom !== undefined && forkFrom !== null && forkFrom !== '') {
+        lines.push('', `You are a new FORK of ${sourceLabel}, not ${sourceLabel}. Pi copied the earlier conversation ` +
+            `into this session. Treat that first-person history as reference material, not your own past.`);
+    }
+    return lines.join('\n');
+}
+export function worktreeNote(worktree) {
+    if (worktree?.state !== 'open')
+        return '';
+    return `Branch: \`${worktree.branch}\`\nWorktree: \`${worktree.path}\`\nBase: \`${worktree.base_ref}\` @ \`${worktree.base_sha}\`\nCommit work here. Before finishing, land it with \`crtr node worktree close\` or keep the checkout and branch when the worktree is clean and its exact tip exists on any branch on origin. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); otherwise, unlanded commits or uncommitted changes block finalization.`;
+}