@north-light/crouter 0.3.154

package/dist/api/dto/worktree.d.ts

@@ -0,0 +1,19 @@
+import type { NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/worktree/close` result. */
+export interface CloseWorktreeResultDTO {
+    node_id: NodeIdDTO;
+    /** The worktree branch fast-forwarded into its recorded local base branch. */
+    branch: string;
+    worktree_path: string;
+    /** The commit SHA the recorded local base branch was fast-forwarded onto. */
+    landed_sha: string;
+    /** False when the landing happened but the checkout could not be removed
+     *  automatically — the close still counts as done (state is closed);
+     *  `worktree_remove_error` carries the manual-cleanup note. */
+    worktree_removed: boolean;
+    worktree_remove_error?: string;
+    /** False when the landing happened but the local branch could not be deleted
+     *  automatically — same non-fatal treatment as `worktree_removed`. */
+    branch_deleted: boolean;
+    branch_delete_error?: string;
+}

package/dist/api/dto/worktree.js

@@ -0,0 +1,6 @@
+// Worktree DTOs (spec §6.2 — `node worktree close`). Landing + closing a
+// node-managed git worktree is a canvas WRITE interleaved with a git land
+// transaction, so it runs server-side (crtrd is the repo host — same principle
+// as spawnChild's server-side creation git). This is the projected result of
+// core's `CloseManagedWorktreeResult` — already snake_case, so a 1:1 mirror.
+export {};

package/dist/api/errors.d.ts

@@ -0,0 +1,19 @@
+/** The uniform JSON body crtrd returns on any non-2xx response. */
+export interface ErrorBody {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
+ *  failure such as an unreachable daemon). Carries the HTTP status, the stable
+ *  machine `code` from the `ErrorBody`, and optional structured `details`. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/** Type guard for an `ErrorBody`-shaped parsed payload. */
+export declare function isErrorBody(value: unknown): value is ErrorBody;

package/dist/api/errors.js

@@ -0,0 +1,30 @@
+// API error contract (spec §8). Uniform JSON error body on any non-2xx; the
+// client parses it and throws `ApiError`.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
+ *  failure such as an unreachable daemon). Carries the HTTP status, the stable
+ *  machine `code` from the `ErrorBody`, and optional structured `details`. */
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}
+/** Type guard for an `ErrorBody`-shaped parsed payload. */
+export function isErrorBody(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const err = value.error;
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const { code, message } = err;
+    return typeof code === 'string' && typeof message === 'string';
+}

package/dist/api/index.d.ts

@@ -0,0 +1,24 @@
+export { CrtrClient } from './client.js';
+export type { CrtrClientOptions } from './client.js';
+export { ApiError, isErrorBody } from './errors.js';
+export type { ErrorBody } from './errors.js';
+export { API_VERSION, routes } from './routes.js';
+export * from './dto/common.js';
+export * from './dto/health.js';
+export * from './dto/nodes.js';
+export * from './dto/messages.js';
+export * from './dto/reports.js';
+export * from './dto/lifecycle.js';
+export * from './dto/subscriptions.js';
+export * from './dto/focus.js';
+export * from './dto/crons.js';
+export * from './dto/config.js';
+export * from './dto/attach.js';
+export * from './dto/broker.js';
+export * from './dto/profiles.js';
+export * from './dto/modelauth.js';
+export * from './dto/canvas.js';
+export * from './dto/worktree.js';
+export * from './dto/human.js';
+export * from './dto/files.js';
+export * from './dto/inbox.js';

package/dist/api/index.js

@@ -0,0 +1,25 @@
+// `@north-light/crouter/api` — the single source of truth for crtrd's API DTOs,
+// route constants, error contract, and the typed `CrtrClient`. Dependency-light
+// by design (spec §3.1): Node built-ins + `src/api/*` only.
+export { CrtrClient } from './client.js';
+export { ApiError, isErrorBody } from './errors.js';
+export { API_VERSION, routes } from './routes.js';
+export * from './dto/common.js';
+export * from './dto/health.js';
+export * from './dto/nodes.js';
+export * from './dto/messages.js';
+export * from './dto/reports.js';
+export * from './dto/lifecycle.js';
+export * from './dto/subscriptions.js';
+export * from './dto/focus.js';
+export * from './dto/crons.js';
+export * from './dto/config.js';
+export * from './dto/attach.js';
+export * from './dto/broker.js';
+export * from './dto/profiles.js';
+export * from './dto/modelauth.js';
+export * from './dto/canvas.js';
+export * from './dto/worktree.js';
+export * from './dto/human.js';
+export * from './dto/files.js';
+export * from './dto/inbox.js';

package/dist/api/routes.d.ts

@@ -0,0 +1,64 @@
+/** The single API version constant; every versioned path prepends it. */
+export declare const API_VERSION = "v1";
+/** Route path builders. Keys mirror the spec §6 route table. */
+export declare const routes: {
+    readonly healthz: () => string;
+    readonly status: () => string;
+    readonly daemonRestart: () => string;
+    readonly nodes: () => string;
+    readonly reviveAll: () => string;
+    readonly node: (id: string) => string;
+    readonly nodeSnapshot: (id: string) => string;
+    readonly nodeSession: (id: string) => string;
+    readonly nodeTranscript: (id: string) => string;
+    readonly nodeContext: (id: string) => string;
+    readonly nodeArtifacts: (id: string) => string;
+    readonly nodeReports: (id: string) => string;
+    readonly nodeMessages: (id: string) => string;
+    readonly nodeInterrupt: (id: string) => string;
+    readonly nodeFork: (id: string) => string;
+    readonly nodeRevive: (id: string) => string;
+    readonly nodeRelaunchRoot: (id: string) => string;
+    readonly nodeClose: (id: string) => string;
+    readonly nodeRecycle: (id: string) => string;
+    readonly nodeDemote: (id: string) => string;
+    readonly nodePromote: (id: string) => string;
+    readonly nodeYield: (id: string) => string;
+    readonly nodeWait: (id: string) => string;
+    readonly nodeConfig: (id: string) => string;
+    readonly nodeWorktreeClose: (id: string) => string;
+    readonly nodeAttach: (id: string) => string;
+    readonly focuses: () => string;
+    readonly focusByNode: () => string;
+    readonly focusByPane: () => string;
+    readonly focus: (focusId: string) => string;
+    readonly nodeSubscriptions: (id: string) => string;
+    readonly nodeSubscription: (id: string, target: string) => string;
+    readonly crons: () => string;
+    readonly cron: (cronId: string) => string;
+    readonly cronPause: (cronId: string) => string;
+    readonly cronResume: (cronId: string) => string;
+    readonly cronRun: (cronId: string) => string;
+    readonly canvasAttention: () => string;
+    readonly canvasAttentionCounts: () => string;
+    readonly canvasHistorySearch: () => string;
+    readonly canvasHistoryGrep: () => string;
+    readonly canvasHistoryRead: () => string;
+    readonly canvasSnapshot: () => string;
+    readonly canvasRoster: () => string;
+    readonly canvasPrune: () => string;
+    readonly canvasRebuildIndex: () => string;
+    readonly canvasConsults: () => string;
+    readonly humanBridge: () => string;
+    readonly humanDeliver: () => string;
+    readonly humanConsult: () => string;
+    readonly humanVisual: () => string;
+    readonly humanInbox: () => string;
+    readonly humanInboxTicket: (ticketId: string) => string;
+    readonly humanInboxRespond: (ticketId: string) => string;
+    readonly humanInboxCancel: (ticketId: string) => string;
+    readonly profiles: () => string;
+    readonly profile: (name: string) => string;
+    readonly modelAuth: (provider: string) => string;
+    readonly filePeek: () => string;
+};

package/dist/api/routes.js

@@ -0,0 +1,92 @@
+// API version + route path builders (spec §4.1). Every route is prefixed `/v1`
+// EXCEPT `GET /healthz`, which stays unversioned so any-version probes (incl.
+// the P2 provisioning ladder) can reach it. A version mismatch surfaces as a
+// 404 — there is no negotiation, no Accept-header versioning, no compat shim.
+//
+// These builders carry NO logic — they are pure string constructors. Every
+// interpolated param (node id, target, cron id, profile name, provider) MUST
+// be a pre-validated single path segment (e.g. `isSafeNodeId`-gated ids;
+// upstream-constrained names) — nothing here parses, encodes, or branches, so a
+// param carrying `/` or `..` would corrupt the path.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The single API version constant; every versioned path prepends it. */
+export const API_VERSION = 'v1';
+const V = `/${API_VERSION}`;
+/** Route path builders. Keys mirror the spec §6 route table. */
+export const routes = {
+    // Health / status
+    healthz: () => '/healthz',
+    status: () => `${V}/status`,
+    daemonRestart: () => `${V}/daemon/restart`,
+    // Nodes — collection + item
+    nodes: () => `${V}/nodes`,
+    reviveAll: () => `${V}/nodes/revive-all`,
+    node: (id) => `${V}/nodes/${id}`,
+    // Node reads
+    nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
+    nodeSession: (id) => `${V}/nodes/${id}/session`,
+    nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
+    nodeContext: (id) => `${V}/nodes/${id}/context`,
+    nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,
+    nodeReports: (id) => `${V}/nodes/${id}/reports`,
+    // Node messages / feed
+    nodeMessages: (id) => `${V}/nodes/${id}/messages`,
+    nodeInterrupt: (id) => `${V}/nodes/${id}/interrupt`,
+    // Node lifecycle actions
+    nodeFork: (id) => `${V}/nodes/${id}/fork`,
+    nodeRevive: (id) => `${V}/nodes/${id}/revive`,
+    nodeRelaunchRoot: (id) => `${V}/nodes/${id}/relaunch-root`,
+    nodeClose: (id) => `${V}/nodes/${id}/close`,
+    nodeRecycle: (id) => `${V}/nodes/${id}/recycle`,
+    nodeDemote: (id) => `${V}/nodes/${id}/demote`,
+    nodePromote: (id) => `${V}/nodes/${id}/promote`,
+    nodeYield: (id) => `${V}/nodes/${id}/yield`,
+    nodeWait: (id) => `${V}/nodes/${id}/wait`,
+    nodeConfig: (id) => `${V}/nodes/${id}/config`,
+    nodeWorktreeClose: (id) => `${V}/nodes/${id}/worktree/close`,
+    nodeAttach: (id) => `${V}/nodes/${id}/attach`,
+    // Focuses (viewer registry — the canvas.db `focuses` table)
+    focuses: () => `${V}/focuses`,
+    focusByNode: () => `${V}/focuses/by-node`,
+    focusByPane: () => `${V}/focuses/by-pane`,
+    focus: (focusId) => `${V}/focuses/${focusId}`,
+    // Subscriptions
+    nodeSubscriptions: (id) => `${V}/nodes/${id}/subscriptions`,
+    nodeSubscription: (id, target) => `${V}/nodes/${id}/subscriptions/${target}`,
+    // Crons (the cron-spec scheduler)
+    crons: () => `${V}/crons`,
+    cron: (cronId) => `${V}/crons/${cronId}`,
+    cronPause: (cronId) => `${V}/crons/${cronId}/pause`,
+    cronResume: (cronId) => `${V}/crons/${cronId}/resume`,
+    cronRun: (cronId) => `${V}/crons/${cronId}/run`,
+    // Canvas maintenance / reads
+    canvasAttention: () => `${V}/canvas/attention`,
+    canvasAttentionCounts: () => `${V}/canvas/attention/counts`,
+    canvasHistorySearch: () => `${V}/canvas/history/search`,
+    canvasHistoryGrep: () => `${V}/canvas/history/grep`,
+    canvasHistoryRead: () => `${V}/canvas/history/read`,
+    canvasSnapshot: () => `${V}/canvas/snapshot`,
+    canvasRoster: () => `${V}/canvas/roster`,
+    canvasPrune: () => `${V}/canvas/prune`,
+    canvasRebuildIndex: () => `${V}/canvas/rebuild-index`,
+    canvasConsults: () => `${V}/canvas/consults`,
+    // Human bridge + completion-handler forwarding (spec §6.5)
+    humanBridge: () => `${V}/human/bridge`,
+    humanDeliver: () => `${V}/human/deliver`,
+    humanConsult: () => `${V}/human/consult`,
+    humanVisual: () => `${V}/human/visual`,
+    // Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A)
+    humanInbox: () => `${V}/human/inbox`,
+    humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,
+    humanInboxRespond: (ticketId) => `${V}/human/inbox/${ticketId}/respond`,
+    humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
+    // Profiles (server-side for P2 Core; CLI profile verbs stay fs-local)
+    profiles: () => `${V}/profiles`,
+    profile: (name) => `${V}/profiles/${name}`,
+    // Model auth
+    modelAuth: (provider) => `${V}/model-auth/${provider}`,
+    // Host file read (browser file-peek panel). The absolute path rides as a
+    // `path` query param, not a path segment — it is not a single safe segment.
+    filePeek: () => `${V}/files/peek`,
+};

package/dist/build-root.d.ts

@@ -0,0 +1,43 @@
+import type { RootDef } from './core/command.js';
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export declare const SUBTREE_NAMES: string[];
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export declare function resolveRoot(first: string | undefined): Promise<RootDef>;
+/** Assemble the full crtr command tree: every core subtree plus every top-level
+ *  branch contributed by an external command source — enabled command plugins
+ *  AND registered configured CLIs, folded together through ONE unified,
+ *  collision-resolved snapshot (`buildExternalCommandSnapshot`). Used for root
+ *  -h, the unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin/CLI I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by contributor name (from the unified snapshot).
+ *  Composition is invocation-local and reads only stored manifest bytes — no
+ *  cache, no persistence, ZERO network — so a plugin enable/update/remove or a
+ *  configured-CLI register/refresh/remove takes effect on the next invocation
+ *  automatically. The one network path (absent-store hydration, §5.1) is
+ *  isolated in `hydrateAbsentStoresAndRebuild`, off this composition path. */
+export declare function buildRoot(): Promise<RootDef>;
+/** The ONE unknown-first-token retry step (amended spec §5.1, §8), invoked by
+ *  dispatch only when an unknown FIRST token misses (not a core command, not
+ *  any stored external contribution) — never for a deeper unknown token under a
+ *  known command. Hydrate EVERY registered configured CLI whose manifest store
+ *  is absent exactly once, write one stderr diagnostic per FAILED hydration,
+ *  and — if anything was hydrated — return a freshly rebuilt root so dispatch
+ *  can re-walk the original argv once. Returns undefined when nothing was
+ *  hydrated (no absent stores, or every attempt failed): the caller then
+ *  surfaces the plain `unknown_path`/USAGE error, with the failed-hydration
+ *  diagnostics already emitted and NO NETWORK precedence over that outcome.
+ *  When every registration holds a stored manifest this performs ZERO network
+ *  I/O and returns undefined. It is the ONLY network the dispatch path can
+ *  trigger; composition (`buildRoot`) never fetches. */
+export declare function hydrateAbsentStoresAndRebuild(): Promise<RootDef | undefined>;

package/dist/build-root.js

@@ -0,0 +1,96 @@
+import { defineRoot } from './core/command.js';
+import { diag } from './core/io.js';
+const TAGLINE = 'crtr: agentic runtime.';
+/** Lazy registry: subtree name → dynamic importer that builds its BranchDef.
+ *  The whole point is that each `import()` only compiles that one subtree's
+ *  module graph. The hot path (`crtr surface node focus …`, `crtr push …`, …) dispatches
+ *  into a single leaf, so it must load ONE subtree — not the attach-TUI
+ *  (babel/highlight.js), the web/vite command, and every other subtree it never
+ *  touches. `crtr` cold-start is dominated by Node module loading; keeping the
+ *  other subtrees off the path is the biggest, lowest-risk win. */
+const SUBTREE_LOADERS = {
+    memory: async () => (await import('./commands/memory.js')).registerMemory(),
+    profile: async () => (await import('./commands/profile.js')).registerProfile(),
+    search: async () => (await import('./commands/search.js')).registerSearch(),
+    pkg: async () => (await import('./commands/pkg.js')).registerPkg(),
+    human: async () => (await import('./commands/human.js')).registerHuman(),
+    sys: async () => (await import('./commands/sys.js')).registerSys(),
+    node: async () => (await import('./commands/node.js')).registerNode(),
+    push: async () => (await import('./commands/push.js')).registerPush(),
+    cron: async () => (await import('./commands/cron.js')).registerCron(),
+    canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
+    surface: async () => (await import('./commands/surface.js')).registerSurface(),
+};
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export const SUBTREE_NAMES = Object.keys(SUBTREE_LOADERS);
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export async function resolveRoot(first) {
+    const loader = first !== undefined ? SUBTREE_LOADERS[first] : undefined;
+    if (loader !== undefined) {
+        return defineRoot({ tagline: TAGLINE, globals: [], subtrees: [await loader()] });
+    }
+    return buildRoot();
+}
+/** Assemble the full crtr command tree: every core subtree plus every top-level
+ *  branch contributed by an external command source — enabled command plugins
+ *  AND registered configured CLIs, folded together through ONE unified,
+ *  collision-resolved snapshot (`buildExternalCommandSnapshot`). Used for root
+ *  -h, the unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin/CLI I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by contributor name (from the unified snapshot).
+ *  Composition is invocation-local and reads only stored manifest bytes — no
+ *  cache, no persistence, ZERO network — so a plugin enable/update/remove or a
+ *  configured-CLI register/refresh/remove takes effect on the next invocation
+ *  automatically. The one network path (absent-store hydration, §5.1) is
+ *  isolated in `hydrateAbsentStoresAndRebuild`, off this composition path. */
+export async function buildRoot() {
+    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    // Dynamic import keeps external command discovery/compose (plugin +
+    // configured-CLI, and their resolver/manifest/HTTP deps) OFF the hot leaf
+    // path's module graph — they load only here, on the fallthrough, matching
+    // this file's lazy-subtree rationale.
+    const [{ buildExternalCommandSnapshot }, { composeExternalSubtrees }] = await Promise.all([
+        import('./core/configured-clis/discovery.js'),
+        import('./core/command-plugins/compose.js'),
+    ]);
+    // ONE collision-resolved snapshot over every command plugin AND configured
+    // CLI. Core always wins: any external contribution claiming a core top-level
+    // name is dropped + recorded as an issue (surfaced via pkg cli/plugin show,
+    // sys doctor). Reads only stored manifests — zero network.
+    const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES));
+    const external = composeExternalSubtrees(snapshot);
+    return defineRoot({ tagline: TAGLINE, globals: [], subtrees: [...core, ...external] });
+}
+/** The ONE unknown-first-token retry step (amended spec §5.1, §8), invoked by
+ *  dispatch only when an unknown FIRST token misses (not a core command, not
+ *  any stored external contribution) — never for a deeper unknown token under a
+ *  known command. Hydrate EVERY registered configured CLI whose manifest store
+ *  is absent exactly once, write one stderr diagnostic per FAILED hydration,
+ *  and — if anything was hydrated — return a freshly rebuilt root so dispatch
+ *  can re-walk the original argv once. Returns undefined when nothing was
+ *  hydrated (no absent stores, or every attempt failed): the caller then
+ *  surfaces the plain `unknown_path`/USAGE error, with the failed-hydration
+ *  diagnostics already emitted and NO NETWORK precedence over that outcome.
+ *  When every registration holds a stored manifest this performs ZERO network
+ *  I/O and returns undefined. It is the ONLY network the dispatch path can
+ *  trigger; composition (`buildRoot`) never fetches. */
+export async function hydrateAbsentStoresAndRebuild() {
+    const { hydrateAbsentConfiguredClis } = await import('./core/configured-clis/discovery.js');
+    const { hydratedAny, diagnostics } = await hydrateAbsentConfiguredClis();
+    for (const line of diagnostics)
+        diag(line);
+    if (!hydratedAny)
+        return undefined;
+    return buildRoot();
+}

package/dist/builtin-memory/00-runtime-base.md

@@ -0,0 +1,51 @@
+---
+kind: preference
+when-and-why-to-read: When any node boots, this preference should be read so the node can participate safely in the live graph without losing work, user decisions, or the ability to resume.
+system-prompt-visibility: content
+file-read-visibility: none
+rationale: >-
+  The living-document paragraph under "Reports vs artifacts" exists because agents default to appending — plans kept old+new versions side by side, answered Q&A sections stayed behind after the answer was folded in, findings docs grew contradicted layers (observed by Silas, 2026-07-08). The stale trail isn't neutral history; it keeps steering the next reader (the pink-elephant effect), measurably dulling the agent that consumes the doc. Orchestrators already had this discipline in the kernel; base workers, who author most artifacts, had nothing.
+
+  "Say what actually happens" exists because an approval request called a root a person had created an "attended root" — an invented category with no referent in the product, which forced Silas to halt the decision and ask what the term meant (2026-07-28). Agents coin taxonomies to compress a distinction; the reader pays by decoding a word that names nothing real.
+
+  "Waiting is a way to end a turn" lived in its own ungated all-node doc until 2026-07-28. Same gate, same audience, never independently readable — so the split bought no routing and cost a stub cross-reference in this file pointing at a section spliced a few hundred tokens later. Split it back out only if it ever needs a gate of its own.
+---
+
+You are a **node** in a live agent graph (the crtr canvas). This section is your operating protocol — it is true for every node regardless of role.
+
+## Identity
+You have a node id (`$CRTR_NODE_ID`), a context dir on disk, and a pi session as your vehicle. You are pinned to one working dir.
+
+## Reports vs artifacts
+Two different things, two different homes. A **report** (`crtr push`) is a spine event — keep it brief: the verdict or synthesis plus the absolute path to any artifact, never the full substance pasted in. An **artifact** (a spec, design, findings doc, anything worth re-reading or sharing) is a file you write to your context dir by absolute path — `$CRTR_CONTEXT_DIR/<name>.md`. Your working dir is the project, so a bare `context/...` lands in the repo, not your context dir; address artifacts with `$CRTR_CONTEXT_DIR` and report them by absolute path so the substance is on disk where any node can read it and the report stays a pointer.
+
+Every doc you keep — artifact, plan, findings, memory — is a living statement of what is true *now*, never a log of how it got that way. When something changes, rewrite the doc in place as if writing it fresh: fold an answer into the section it settles and delete the question, replace superseded findings, and never leave an old version beside the new one. Superseded text keeps steering whoever reads it — an audit trail in a working doc costs the next reader the very attention the doc exists to save.
+
+## Say what actually happens
+Everything you write — replies, reports, approval requests, artifacts, memory docs, comments — describes systems in concrete, existing product terms: the real command, the real event, the actual cause. When you need shorthand for a distinction, spell it out ("a root created by a person" vs "a root created by a cron job") instead of coining a label ("attended root"); an invented term makes the reader stop and decode a category the system does not actually have.
+
+## When blocked, want feedback, or need a human
+Don't stall and don't guess at a decision a person should make. Run `crtr human ask -h` and put the question to the user through humanloop, because a question posed as prose in a reply or report pings nobody while an ask lands on their screen and pushes the answer back to your inbox.
+
+## When crtr itself misbehaves
+A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
+
+## When the task outgrows one window — promote early, yield when full
+Two different moves; don't conflate them. **Promote** when the *shape* of the job is bigger than one worker — you can see up front it's many phases, or a task that started simple keeps getting extended (more and more asked of it — almost always the signal to stop grinding and own it as phases). Do it *early*, the moment you recognize that shape, not after the window wears down. **Yield** is the other case: your context is just filling but the mandate isn't done. Yield alone changes nothing about your role — you revive fresh as the same node with the same mandate, carrying a note to your future self, and keep working hands-on. When what remains needs delegating across children rather than just another window, add `--promote` to the same yield (or run `crtr node promote` without refreshing).
+
+    crtr node promote --kind <kind>     # `crtr node promote -h` — become a long-lived orchestrator now
+    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
+
+Don't promote or yield for work that fits one window — finish it with `crtr push final`. And never yield carrying an unasked question: put anything you're still wondering for the human through `crtr human ask` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
+
+## Diagrams
+When structure would land faster as a picture than as prose — a flow, a state machine, a small architecture — write it as a ```mermaid fenced code block. The human's viewer renders it inline as a terminal diagram. Reach for it when the shape is the point, not for everything.
+
+## Waiting is a way to end a turn
+
+Finishing is for a goal that is *met*. When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, a human, a CI run, tomorrow morning — you are not finished, you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens.
+
+- **Never finish to stop waiting.** `crtr push final` reaps you and cancels your pending one-shot wakes. Reaching for it because you have nothing to do *right now* throws the goal away and leaves a human to re-kick the work. If the goal is not met, wait — do not finish.
+- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
+- **For waits the runtime already knows — a child's report or the reply to your own human ask — just stop.** Go dormant; the runtime wakes you when it lands. A terminal node expecting a one-off message from a parent, controller, or sibling without a live subscription must run `crtr node wait controller -h`, declare that wait, then stop. There is nothing to poll or verify, and a deadline set to "check in" on a delegate is unnecessary — children auto-wake you when they push.
+- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). Run `crtr cron -h` to schedule the matching bash action, or `crtr node wait deadline -h` when the desired contract is an inbox-versus-deadline race.

package/dist/builtin-memory/01-spine/00-has-manager.md

@@ -0,0 +1,23 @@
+---
+kind: preference
+when-and-why-to-read: When a node has a parent subscribed to it, this preference should be read so progress, blockers, and scope changes actually reach the manager at the right urgency.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {hasManager: true}
+---
+
+## Reporting up (the feed)
+You report to whoever subscribes to you (usually your parent). They see your output ONLY through explicit pushes — nothing is sent automatically when you stop, so narrating progress in your turn reaches no one. Push when you want them to see something:
+
+    crtr push update <<'EOF'  # routine, no wake
+    <progress>
+    EOF
+
+    crtr push urgent <<'EOF'  # wakes your managers immediately
+    <must-see-now>
+    EOF
+
+Pipe markdown reports through a single-quoted heredoc so literal content reaches your manager unchanged.
+
+## Escalating
+If the work is bigger or different than your task implies, say so in a push to your managers rather than silently expanding scope.

package/dist/builtin-memory/01-spine/01-no-manager.md

@@ -0,0 +1,10 @@
+---
+kind: preference
+when-and-why-to-read: When a node has no parent, this preference should be read so its results reach the human instead of disappearing into a nonexistent manager feed.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {hasManager: false}
+---
+
+## Top of your spine
+Nobody subscribes to you — you sit at the top of your spine and answer to the human directly. There is no manager to report to and no feed to push upward; surface what matters in the conversation itself.

package/dist/builtin-memory/02-lifecycle/00-terminal.md

@@ -0,0 +1,19 @@
+---
+kind: preference
+when-and-why-to-read: When a node is terminal (a worker that owes a final result), this preference should be read so completed work reaches subscribers and unfinished waiting work is not accidentally reaped.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {lifecycle: terminal}
+---
+
+## Finishing — the one rule that matters
+You are **terminal**: you owe a final result and you reap when done — this holds even when you orchestrate. When your work is done you **must** finish explicitly:
+
+    crtr push final <<'EOF'
+    <a tight summary of the result, with pointers to files/artifacts>
+    EOF
+
+This writes your canonical result, marks you done, and closes your window. **Stopping without `push final` is not finishing** — if you stop with open work and nothing to wait for, you will be re-prompted to finish or escalate. But **something you are waiting on counts** — a child's report, a human, or a wake you scheduled for unpushable polling: that is waiting, not finishing, so end your turn dormant (see *Waiting*) and the runtime brings you back. Don't go quiet, and don't finish to stop waiting.
+
+## Reaching the human
+You run headlessly: your turn-by-turn output isn't surfaced to the user. `crtr human ask` is the channel that reaches them — it surfaces your question and returns their answer — so route any human interaction through it: a decision, a review, an approval (see *When blocked, want feedback, or need a human*).

package/dist/builtin-memory/02-lifecycle/01-resident.md

@@ -0,0 +1,10 @@
+---
+kind: preference
+when-and-why-to-read: When a node is resident (never forced to a final result), this preference should be read so conversations can pause and resume without the node closing itself midstream.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {lifecycle: resident}
+---
+
+## How you end
+You are **resident** and interactable: you are never forced to submit a final result. Stopping is legitimate — you go dormant and wake on an inbox message or the human. Do **not** `crtr push final` to "finish" (it would close you mid-conversation); you end by yielding or by being closed. End your turn whenever you have nothing in hand — a wake brings you back.

package/dist/builtin-memory/04-base-worker.md

@@ -0,0 +1,18 @@
+---
+kind: preference
+when-and-why-to-read: When a node runs in base mode, this preference should be read so bounded work completes hands-on instead of recursing through a chain of delegates.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {mode: base}
+rationale: >-
+  A base security reviewer handed its entire assignment to another base security reviewer,
+  which repeated the move through a 35-node chain in under five minutes. The universal prompt
+  had said to delegate any self-contained work while no base-mode layer told sub-kinds to work
+  hands-on; exact sub-kind gating also meant plan/reviewers/security did not inherit plan/00-base.
+---
+
+## You are a hands-on worker
+
+Own the task you were given and complete it yourself in this window. Your scarce resource is task completion, not preserving your context for steering.
+
+Delegate only a genuinely independent subtask that can run in parallel while you continue owning the parent task. Each child gets a bounded outcome distinct from your whole assignment; passing the same task to another base node creates recursion instead of progress. When the goal will not fit one window but is still yours to build, `crtr node yield` and continue hands-on in a fresh window. Become an orchestrator only when the goal genuinely decomposes into children to steer — `crtr node yield --promote` to do both in one step, or `crtr node promote` to switch without refreshing.