@north-light/crouter 0.3.173 → 0.3.175

package/dist/commands/human/queue.js

@@ -217,55 +217,22 @@ function parseResolveBody(raw) {
         throw new InputError({ error: 'invalid_field', message: 'responses must be an array', field: 'responses', next: 'Pass {"responses":[{"interaction_id":"...","selected_option_ids":["..."]}]}.' });
     }
     return parsed.responses.map((r) => {
-        const id = r.interaction_id ?? r.id;
-        if (id === undefined || id === '') {
+        if (r.interaction_id === undefined || r.interaction_id === '') {
             throw new InputError({ error: 'invalid_field', message: 'each response needs interaction_id', field: 'responses', next: 'Include interaction_id for every response.' });
         }
-        const selectedOptionIds = r.selected_option_ids ?? r.selectedOptionIds;
-        const selectedOptionId = r.selected_option_id ?? r.selectedOptionId;
         return {
-            id,
-            ...(selectedOptionIds !== undefined ? { selectedOptionIds } : {}),
-            ...(selectedOptionId !== undefined ? { selectedOptionId } : {}),
+            id: r.interaction_id,
+            ...(r.selected_option_ids !== undefined ? { selectedOptionIds: r.selected_option_ids } : {}),
+            ...(r.selected_option_id !== undefined ? { selectedOptionId: r.selected_option_id } : {}),
             ...(r.freetext !== undefined ? { freetext: r.freetext } : {}),
-            ...(r.optionComments !== undefined ? { optionComments: r.optionComments } : {}),
+            ...(r.option_comments !== undefined ? { optionComments: r.option_comments } : {}),
         };
     });
 }
-/**
- * Translate web-shaped answers into the ticket response contract. Web clients
- * always send `selectedOptionIds` (an array) for every option pick, but the
- * strict deck validator rejects an array on any non-multiSelect
- * interaction. For a single-select interaction we faithfully fold a
- * single-element array down to `selectedOptionId` (deterministic given the
- * deck's own multiSelect flag — not a lenient guess). Multi-select and freetext
- * responses pass through untouched; an unreadable deck is left to the daemon.
- */
-function coerceSingleSelect(responses, dir) {
-    const deck = readJson(deckPath(dir));
-    if (deck === null || deck === undefined)
-        return responses;
-    return coerceSingleSelectAgainst(responses, deck);
-}
-/** Pure core of {@link coerceSingleSelect}, split out so it is testable without
- *  a deck.json on disk. */
-export function coerceSingleSelectAgainst(responses, deck) {
-    const isMulti = new Map(deck.interactions.map((it) => [it.id, it.multiSelect === true]));
-    return responses.map((r) => {
-        if (isMulti.get(r.id) === true)
-            return r;
-        if (r.selectedOptionId !== undefined || r.selectedOptionIds === undefined)
-            return r;
-        if (r.selectedOptionIds.length !== 1)
-            return r; // 0 or >1 stays → the validator rejects
-        const { selectedOptionIds, ...keep } = r;
-        return { ...keep, selectedOptionId: selectedOptionIds[0] };
-    });
-}
 export const humanResolve = defineLeaf({
     name: 'resolve',
     description: 'resolve one human deck from stdin answers',
-    whenToUse: 'a browser or local tool is submitting answers for a pending human interaction.',
+    whenToUse: 'an API client or local tool is submitting answers for a pending human interaction.',
     tier: 'hidden',
     help: {
         name: 'human resolve',
@@ -290,7 +257,7 @@ export const humanResolve = defineLeaf({
         if (!existsSync(deckPath(dir))) {
             throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
         }
-        const responses = coerceSingleSelect(parseResolveBody(input['body']), dir);
+        const responses = parseResolveBody(input['body']);
         // A published result on a live bridge may be an interrupted delivery. The
         // daemon re-drives that delivery before it returns its 409, so only bypass
         // it when the bridge is already terminal.

package/dist/commands/memory/list.d.ts

@@ -1 +1,15 @@
+import type { MemoryDoc, MemoryScope } from '../../core/memory-resolver.js';
+/** A fully-resolved memory inventory before command pagination/output shaping.
+ * Shared in-process consumers retain `memory list`'s scope ordering and
+ * identity behavior without rescanning the corpus once per output page. */
+export interface ListedMemoryDoc {
+    name: string;
+    kind: string;
+    scope: MemoryScope;
+    path: string;
+    shortForm: string;
+    isDir: boolean;
+    slash: boolean;
+}
+export declare function listMemoryDocs(kindFilter?: string, scopeFilter?: MemoryScope, quiet?: boolean, docs?: readonly MemoryDoc[]): ListedMemoryDoc[];
 export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/list.js

@@ -4,6 +4,40 @@ import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { isIndexName, indexDirOf } from '../../core/substrate/ceiling.js';
 import { paginate } from '../../core/pagination.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
+export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = listAllMemoryDocs(scopeFilter, quiet)) {
+    const seen = new Set(); // "scope/name" → first wins
+    const items = [];
+    const addItem = (item) => {
+        const id = `${item.scope}/${item.name}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        items.push(item);
+    };
+    // Substrate memory docs (project > user > builtin precedence).
+    for (const doc of docs) {
+        const sub = parseSubstrateDoc(doc);
+        if (sub === null)
+            continue;
+        if (kindFilter !== undefined && sub.kind !== kindFilter)
+            continue;
+        // A directory INDEX surfaces as a dir entry: its dir path with a trailing
+        // slash, flagged is_dir, so the inventory distinguishes it from a doc.
+        const isDir = isIndexName(sub.name);
+        const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
+        addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir, slash: sub.slash });
+    }
+    items.sort((a, b) => {
+        const sr = scopeRank(a.scope) - scopeRank(b.scope);
+        if (sr !== 0)
+            return sr;
+        const kc = a.kind.localeCompare(b.kind);
+        if (kc !== 0)
+            return kc;
+        return a.name.localeCompare(b.name);
+    });
+    return items;
+}
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory of stored memory documents',
@@ -34,37 +68,7 @@ export const listLeaf = defineLeaf({
         const limitRaw = input['limit'];
         const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
         const cursor = input['cursor'];
-        const seen = new Set(); // "scope/name" → first wins
-        const items = [];
-        const addItem = (item) => {
-            const id = `${item.scope}/${item.name}`;
-            if (seen.has(id))
-                return;
-            seen.add(id);
-            items.push(item);
-        };
-        // Substrate memory docs (project > user > builtin precedence).
-        for (const doc of listAllMemoryDocs(scopeFilter)) {
-            const sub = parseSubstrateDoc(doc);
-            if (sub === null)
-                continue;
-            if (kindFilter !== undefined && sub.kind !== kindFilter)
-                continue;
-            // A directory INDEX surfaces as a dir entry: its dir path with a trailing
-            // slash, flagged is_dir, so the inventory distinguishes it from a doc.
-            const isDir = isIndexName(sub.name);
-            const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
-            addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir });
-        }
-        items.sort((a, b) => {
-            const sr = scopeRank(a.scope) - scopeRank(b.scope);
-            if (sr !== 0)
-                return sr;
-            const kc = a.kind.localeCompare(b.kind);
-            if (kc !== 0)
-                return kc;
-            return a.name.localeCompare(b.name);
-        });
+        const items = listMemoryDocs(kindFilter, scopeFilter);
         const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}`;
         const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, total: 'count' });
         return {

package/dist/commands/memory/read.d.ts

@@ -1 +1,8 @@
+import { createMemoryDocSnapshot, resolveMemoryDocs } from '../../core/memory-resolver.js';
+export { createMemoryDocSnapshot, resolveMemoryDocs };
+/** Load the body at an already-resolved memory path with the same frontmatter
+ * stripping and in-node path interpolation as `memory read`. Callers that
+ * already have the resolved path (such as slash-command discovery) avoid
+ * re-walking every memory store for each document. */
+export declare function readMemoryDocContent(path: string, includeFrontmatter?: boolean): string;
 export declare const readLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/read.js

@@ -1,12 +1,24 @@
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
-import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { createMemoryDocSnapshot, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
 import { effectiveDocKind } from '../../core/substrate/schema.js';
 import { displayName } from '../../core/substrate/ceiling.js';
 import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { readText } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { MEMORY_KINDS } from './shared.js';
+export { createMemoryDocSnapshot, resolveMemoryDocs };
+/** Load the body at an already-resolved memory path with the same frontmatter
+ * stripping and in-node path interpolation as `memory read`. Callers that
+ * already have the resolved path (such as slash-command discovery) avoid
+ * re-walking every memory store for each document. */
+export function readMemoryDocContent(path, includeFrontmatter = false) {
+    const raw = readText(path);
+    const content = includeFrontmatter ? raw : parseFrontmatterGeneric(raw).body;
+    const nodeId = process.env['CRTR_NODE_ID'];
+    return nodeId ? interpolateNodePaths(content, nodeId) : content;
+}
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
@@ -51,13 +63,7 @@ export const readLeaf = defineLeaf({
         }
         if (doc !== undefined) {
             const kind = effectiveDocKind(doc);
-            const raw = includeFrontmatter ? readText(doc.path) : doc.body;
-            // In-node reads (CRTR_NODE_ID set) get the literal `$CRTR_CONTEXT_DIR`
-            // token swapped for this node's real absolute path, so agents don't
-            // paste it into the non-expanding Write tool. A human/contributor
-            // reading generically (env unset) keeps the token literal.
-            const nodeId = process.env['CRTR_NODE_ID'];
-            const content = nodeId ? interpolateNodePaths(raw, nodeId) : raw;
+            const content = readMemoryDocContent(doc.path, includeFrontmatter);
             // `[[name]]` doc links are pointers, never transclusion: surface which
             // linked names actually resolve so the reader can follow one when the
             // task needs that depth, without ever auto-loading a linked body.

package/dist/commands/memory/write.js

@@ -9,23 +9,24 @@ import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memo
 export const writeLeaf = defineLeaf({
     name: 'write',
     description: 'create or update a memory document',
-    whenToUse: 'you are recording a new knowledge document or preference — or revising one that already exists. Writes memory/<name>.md at the resolved scope from the frontmatter flags plus a body piped on stdin. Identity is path-derived: if <name> already exists at the scope it is updated in place, otherwise it is created.',
+    whenToUse: 'you are recording a new knowledge document or preference, or revising one that already exists — an existing <name> at the resolved scope is updated in place, so revision is also this leaf.',
     help: {
         name: 'memory write',
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
-        guide: 'The body is the easy part; the craft is routing — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung down.\n\n' +
+        guide: 'Every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
-            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
-            'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
-            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
-            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". The `.` route surfaces the full operating guide in first-message context whenever cwd or a selected profile mounts that project store; its envelope name comes from the owning project directory unless the document already carries an explicit name. It is a front door, not a manual — keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
-            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog. Every non-none file-read rung also requires at least one explicit applies-to route: `.` means project workspace/profile mount and is evaluated during first-message assembly; every other value is a glob evaluated only after a matching file is actually read. There is no positional fallback from where the memory file lives. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
-            'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the READER’s payoff — the consequence they secure for the task in front of them by spending the read — never what the document says, its rule, or why it should be obeyed. The trap most authors fall into is the DISGUISED restatement: a because-clause that reads like a benefit but is just the doc’s own thesis reworded as an outcome. It still fails. The test: if you could derive the because-clause by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad (naked restatement): "because only genuine first principles belong in taste memory." Bad (restatement in benefit’s clothing): "because keeping the test loop fast and free of speculative tests protects the development pace" — that is the doc’s rule in outcome costume, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." The stranger test: someone mid-task who has NOT read the doc must be able to decide from this one line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising.\n\n' +
+            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
+            'The visibility rungs `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc fits in a single sentence — a one-line preference or a one-sentence knowledge fact — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
+            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". Its envelope name comes from the owning project directory unless the document already carries an explicit name. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
+            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog; file-read visibility fires on the applies-to routes. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
+            'Write the routing line (--when-and-why-to-read) first, before storing anything. The test for its because-clause: if it can be derived by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" — the doc’s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
             'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name — the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc’s resolvable links alongside its body. There is no alias or label form.\n\n' +
-            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. This is the same layering the visibility rungs apply to boot cost, applied to the body itself. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
-            'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body that would make the existing document harder to route or use. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Run `crtr memory lint` — the frontmatter validator — after authoring.\n\n' +
-            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only via `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
+            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
+            'A directory INDEX earns existence only where the aggregate view beats the sum of per-file rungs. Two shapes pass: synthesis — an operating guide or the cluster’s mechanics, ordering, and relationships, content no single child can carry — and aggregated routing — one preview line covering a large cluster with one shared routing condition, children dropped to `name` or `none`. Otherwise skip the INDEX and let each doc’s own rung route it: frontmatter routing lines are self-maintaining, while an INDEX body describing its children is a hand-maintained copy that drifts. Never write an INDEX that restates child names, paraphrases their routing lines, fronts a small directory of sharply named docs, or summarizes children a reader should open.\n\n' +
+            'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is automatic on create and preserved on update. Run `crtr memory lint` after authoring.\n\n' +
+            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
@@ -34,7 +35,7 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
             { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Required when creating — there is no kind default. Every value except none also requires at least one applies-to route in the resulting document.' },
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. Required whenever file-read-visibility is not none.' },
+            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. There is no positional fallback from where the memory file lives. Required whenever file-read-visibility is not none.' },
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
             { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },

package/dist/commands/node/bash.d.ts

@@ -0,0 +1 @@
+export declare const nodeBash: import("../../core/command.js").BranchDef;

package/dist/commands/node/bash.js

@@ -0,0 +1,198 @@
+// `crtr node bash` — file-backed background job controls.
+import { existsSync, writeFileSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { displayMessage } from '../../core/runtime/tmux-chrome.js';
+import { contextDir } from '../../core/canvas/paths.js';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobPaths, formatBashElapsed, jobStartedAtMs, readJobPgid, tailJobLog } from '../../core/bash-jobs.js';
+import { cliClient, getNodeOrNull } from '../api-client.js';
+import { nodeInPane } from '../surface/node/placement.js';
+function resolveBashTarget(input, missingMessage) {
+    const pane = input['pane'] ?? process.env['TMUX_PANE'];
+    let id = input['node'];
+    if (id === undefined || id === '')
+        id = nodeInPane(pane);
+    if (id === undefined || id === '')
+        id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id === '') {
+        throw new InputError({ error: 'no_node', message: missingMessage, next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+    }
+    return { id, pane };
+}
+const nodeBashBackground = defineLeaf({
+    name: 'background',
+    description: 'hand the focused node’s running bash command to its background job system',
+    whenToUse: 'the tmux prefix menu invokes this when a foreground bash command should stop blocking the agent immediately but keep running as a file-backed background job',
+    tier: 'hidden',
+    help: {
+        name: 'node bash background',
+        summary: 'hand every running foreground bash command for one node to its file-backed background job system',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose running bash command to background. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE. The prefix menu passes this for you.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'backgrounded', type: 'number', required: true, constraint: 'Number of running bash commands handed off.' },
+            { name: 'job_ids', type: 'string[]', required: true, constraint: 'File-backed job ids now running independently of the agent tool call.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Per handed-off job {job_id, elapsed_ms} — the foreground elapsed time in milliseconds at the moment of handoff.' },
+        ],
+        outputKind: 'object',
+        effects: ['Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.', 'Each handed-off command retains its log under the node context jobs directory and sends the node an urgent inbox message when it exits, which steers the node mid-turn.'],
+    },
+    run: async (input) => {
+        const { id, pane } = resolveBashTarget(input, 'no node found for the bash handoff');
+        if ((await getNodeOrNull(id)) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobs = backgroundRunningBashJobs(contextDir(id));
+        const now = Date.now();
+        const elapsed = jobs.map((job) => ({ job_id: job.jobId, elapsed_ms: now - (jobStartedAtMs(job.jobId) ?? now) }));
+        const toast = jobs.length === 0
+            ? 'crtr: no running bash command'
+            : jobs.length === 1
+                ? `crtr: bash handed off · ${formatBashElapsed(elapsed[0].elapsed_ms)}`
+                : `crtr: bash handed off (${jobs.length})`;
+        displayMessage(toast, pane);
+        return { node_id: id, backgrounded: jobs.length, job_ids: jobs.map((job) => job.jobId), jobs: elapsed };
+    },
+    render: (result) => {
+        if (result['backgrounded'] === 0)
+            return `No foreground bash command is running for ${result['node_id']}.`;
+        const jobs = result['jobs'];
+        const oldestElapsedMs = Math.max(...jobs.map((job) => job.elapsed_ms));
+        return `Handed ${result['backgrounded']} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
+    },
+});
+const nodeBashList = defineLeaf({
+    name: 'list',
+    description: 'list a node’s live background bash jobs',
+    whenToUse: 'the Inspector’s jobs section reads this to show what a node handed off to the background',
+    tier: 'hidden',
+    help: {
+        name: 'node bash list',
+        summary: 'read every still-running background bash job owned by one node',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, started_at, elapsed_ms, log_path, pgid, log_tail} for every live background job.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the node context jobs directory. Changes nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job list');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const now = Date.now();
+        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
+        const dir = contextDir(node.node_id);
+        const jobs = activeBackgroundBashJobs(dir).map((job) => ({
+            job_id: job.jobId,
+            command: job.command,
+            started_at: new Date(job.startedAtMs).toISOString(),
+            elapsed_ms: now - job.startedAtMs,
+            log_path: job.logPath,
+            pgid: readJobPgid(dir, job.jobId) ?? null,
+            log_tail: tailJobLog(job.logPath, tail),
+        }));
+        return { node_id: node.node_id, jobs };
+    },
+    render: (result) => {
+        const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No background bash jobs for ${result['node_id']}.`;
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${job.command.split('\n')[0]}\n  log: ${job.log_path}`).join('\n');
+    },
+});
+/** SIGTERM the job's process group, give it a moment, then SIGKILL. Returns
+ *  false only when the group was already gone at the first signal. */
+function stopJobGroup(pgid) {
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+const nodeBashKill = defineLeaf({
+    name: 'kill',
+    description: 'stop one of a node’s background bash jobs',
+    whenToUse: 'a human watching the Inspector or the attach cockpit’s bash row wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
+    tier: 'hidden',
+    help: {
+        name: 'node bash kill',
+        summary: 'terminate a background bash job’s process group and tell the owning node it was canceled',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job that was stopped.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Sends SIGTERM (then SIGKILL) to the job’s whole process group, stopping the command and anything it forked.',
+            'Records the job’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was stopped — which steers that node mid-turn.',
+        ],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        const dir = contextDir(node.node_id);
+        const paths = bashJobPaths(dir, jobId);
+        if (!existsSync(paths.dir)) {
+            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        const pgid = readJobPgid(dir, jobId);
+        if (pgid === undefined) {
+            throw new InputError({
+                error: 'not_stoppable',
+                message: `job ${jobId} recorded no process group`,
+                next: `It started before crtr persisted one. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
+            });
+        }
+        const signaled = stopJobGroup(pgid);
+        // The supervisor shares the group it leads, so it usually dies with the
+        // command and never writes job.exit. Record the cancellation ourselves —
+        // that sentinel is what retires the job from every live-jobs read.
+        await new Promise((r) => setTimeout(r, 400));
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        if (!existsSync(paths.jobExit))
+            writeFileSync(paths.jobExit, '143\n');
+        await cliClient().sendMessage(node.node_id, {
+            body: `Background bash job ${jobId} was stopped by the human before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
+            tier: 'urgent',
+        });
+        return { node_id: node.node_id, job_id: jobId, signaled };
+    },
+    render: (result) => `Canceled background bash job ${result['job_id']} for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+});
+export const nodeBash = defineBranch({
+    name: 'bash',
+    description: 'control file-backed bash jobs owned by a node',
+    whenToUse: 'a running bash command must be handed off, listed, or stopped — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
+    tier: 'hidden',
+    help: {
+        name: 'node bash',
+        summary: 'control file-backed bash jobs owned by a node',
+    },
+    children: [nodeBashBackground, nodeBashList, nodeBashKill],
+});

package/dist/commands/node/create.d.ts

@@ -0,0 +1,23 @@
+/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
+ *  but when the SPAWNER is an orchestrator whose context has already grown past
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export declare function childFollowUp(spawnerId: string | undefined): Promise<string>;
+/** Validate a `--kind` against the installed personas; throws a listing InputError. */
+export declare function assertKind(kind: string): void;
+/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  installed top-level persona kind (project > user > builtin), lazily built so
+ *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
+ *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
+ *
+ *  Keep this block cheap and caller-agnostic: help should not depend on the
+ *  running node's current persona env, which can lag after polymorph. Sub-kinds
+ *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  defaults to the sub-kind's own top-level ancestor, and this generic block has
+ *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
+ *  sub-kind (universally available) earns a place in this list. A direct launch
+ *  by full sub-kind string is always valid regardless (visibility-only
+ *  filtering) — discover the roster for a specific kind via
+ *  `crtr sys prompt-review --list --kind <kind>`. */
+export declare function kindsStateBlock(): string;
+export declare const nodeNew: import("../../core/command.js").LeafDef;