@north-light/crouter 0.3.179 → 0.3.181

package/dist/clients/inbox/review/document-surface.d.ts

@@ -119,7 +119,7 @@ export declare class ReviewDocumentSurface implements SurfaceComponent {
      *  only after the close, because the host's restoring close disposes every
      *  notice raised over the closing surface — a notice raised first would die
      *  with the surface and the disposition would never paint. */
-    teardown(notice: string): void;
+    teardown(notice: string, opts?: SurfaceNoticeOptions): void;
     /** Releases this surface's render cache and stops every projected repaint.
      *  This surface closes the source it was handed; that close stops its watcher.
      *  The companion pane deliberately survives: only {@link teardown} closes it. */

package/dist/clients/inbox/review/document-surface.js

@@ -264,7 +264,7 @@ export class ReviewDocumentSurface {
             const notice = this.tornDownNotice;
             this.tornDownNotice = undefined;
             if (notice !== undefined)
-                this.services.notice(notice);
+                this.services.notice(notice.text, notice.opts);
         }
     }
     /** The status row's left segment: this document's state in one line. */
@@ -333,7 +333,7 @@ export class ReviewDocumentSurface {
      *  only after the close, because the host's restoring close disposes every
      *  notice raised over the closing surface — a notice raised first would die
      *  with the surface and the disposition would never paint. */
-    teardown(notice) {
+    teardown(notice, opts) {
         if (this.tornDown)
             return;
         this.tornDown = true;
@@ -342,9 +342,9 @@ export class ReviewDocumentSurface {
         this.paneId = undefined;
         this.paneOrigin = undefined;
         if (this.handle === undefined)
-            this.tornDownNotice = notice;
+            this.tornDownNotice = { text: notice, ...(opts === undefined ? {} : { opts }) };
         this.handle?.close();
-        this.services.notice(notice);
+        this.services.notice(notice, opts);
     }
     /** Releases this surface's render cache and stops every projected repaint.
      *  This surface closes the source it was handed; that close stops its watcher.

package/dist/clients/inbox/review/launch.js

@@ -19,7 +19,7 @@ export async function openReviewSurface(host, opts) {
     const reviewClient = createReviewClient({
         onTerminalConflict: (notice) => {
             terminalConflict = true;
-            surface.teardown(notice);
+            finish(notice);
         },
     });
     const comments = reviewClient.comments(review.reviewId);
@@ -52,8 +52,17 @@ export async function openReviewSurface(host, opts) {
             return;
         submitting = true;
         try {
-            const result = await reviewClient.submit(review.reviewId);
-            surface.teardown(approvalNotice(result));
+            const disposition = await reviewClient.submit(review.reviewId);
+            if (disposition.outcome === 'approved') {
+                finish(approvalNotice(disposition));
+                return;
+            }
+            // The companion is mid-edit. The review is off the human's hands either
+            // way: the daemon approves the document as it reads once the companion
+            // stops, and the origin has already been told the approval is coming.
+            // Sticky, because the wait outlives a three-second notice — the review's
+            // cockpit row below the editor carries it from there.
+            finish('Review submitted before the companion finished — the agent resumes when the review completes.', { sticky: true });
         }
         catch (error) {
             if (terminalConflict)
@@ -62,13 +71,16 @@ export async function openReviewSurface(host, opts) {
             host.notice(`couldn't submit review: ${describeError(error)}`);
         }
     }
+    function finish(notice, opts) {
+        surface.teardown(notice, opts);
+    }
     async function cancel() {
         if (canceling)
             return;
         canceling = true;
         try {
             await reviewClient.cancel(review.reviewId, 'canceled from the review surface');
-            surface.teardown('Review canceled.');
+            finish('Review canceled.');
         }
         catch (error) {
             if (terminalConflict)

package/dist/clients/inbox/review/review-client.d.ts

@@ -19,12 +19,17 @@ export interface ReviewClient {
         file: string;
     }): Promise<ResolvedReview>;
     comments(reviewId: string): CommentAuthority;
-    submit(reviewId: string): Promise<{
-        changed: boolean;
-        resultPath: string;
-    }>;
+    submit(reviewId: string): Promise<SubmitDisposition>;
     cancel(reviewId: string, reason: string): Promise<void>;
 }
+/** An approval that landed, or one the daemon is holding for the companion. */
+export type SubmitDisposition = {
+    outcome: 'approved';
+    changed: boolean;
+    resultPath: string;
+} | {
+    outcome: 'awaiting_companion';
+};
 export interface ReviewClientOptions {
     onTerminalConflict?: (notice: string) => void;
 }

package/dist/clients/inbox/review/review-client.js

@@ -54,7 +54,10 @@ export function createReviewClient(opts = {}) {
         },
         async submit(reviewId) {
             const submitted = await request(() => cliClient().submitReview(reviewId));
+            if (submitted.outcome === 'awaiting_companion')
+                return { outcome: 'awaiting_companion' };
             return {
+                outcome: 'approved',
                 changed: requireChanged(submitted.review),
                 resultPath: requireResultPath(submitted.review),
             };

package/dist/commands/cron.js

@@ -134,12 +134,12 @@ const addLeaf = defineLeaf({
             { kind: 'stdin', name: 'command', required: true, constraint: "Arbitrary bash the daemon runs at each fire. Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Runs via `bash -c` in this cwd with $CRTR_CRON_ID, $CRTR_CRON_NAME, and $CRTR_RUN_ID in the env ($CRTR_ANCHOR too when anchored). The scheduler does not interpret it as a node action; a bash predicate can decide whether this fire acts, not arm a native predicate trigger." },
             { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Agent-legible label — how the cron shows in `cron list`.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'One-shot: run the stored bash once at <when> — a duration ("90s","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", interpreted in --tz else host zone). Exactly one of --at / --every is required. The row is deleted after its run unless the run\'s disposition pauses it.' },
-            { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required.' },
+            { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required. For a gated cron (a command that exits 75 while ineligible), pick a LONG cadence: each natural slot is only the backstop re-check, and the daemon poke supplies the latency — "6h" plus poke beats "15m" polling on both latency and cost.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone (e.g. "America/New_York") for a bare-ISO --at or a calendar --every. Defaults to the host zone.' },
             { kind: 'flag', name: 'on-output', type: 'enum', choices: ['silent', 'on-failure', 'always', 'on-change'], required: false, default: 'on-failure', constraint: 'What each run does with its output. silent: record in the run log, tell nobody — never escalate. on-failure (default): no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run\'s — the shape polling wants.' },
             { kind: 'flag', name: 'sink', type: 'string', required: false, constraint: 'Where always/on-change stdout deliveries go: "node:<id>" (an existing node\'s inbox — must exist now; gone/finalized at fire time is a failure), "spawn:<kind>" (each delivered output creates a self-finishing node with stdout as kickoff — a managed child while its creator exists, otherwise a terminal parentless root), or "human" (the humanloop inbox). Required by always/on-change, rejected otherwise.' },
             { kind: 'flag', name: 'tier', type: 'enum', choices: ['normal', 'urgent', 'critical'], required: false, default: 'urgent', constraint: 'Inbox priority of a node-sink delivery. urgent (default): steers the target mid-turn, or wakes it when dormant — a fire is news the node asked for on a schedule, so it should land now. normal: waits for the running turn to settle. critical: aborts the running turn outright.' },
-            { kind: 'flag', name: 'expires', type: 'string', required: false, constraint: 'Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern.' },
+            { kind: 'flag', name: 'expires', type: 'string', required: false, constraint: 'Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern. For a held one-shot (last run exited 75), expiry bounds the wait for eligibility — the row is deleted UNFIRED, never fired blind at expiry.' },
             { kind: 'flag', name: 'anchor', type: 'string', required: false, constraint: 'Couple the cron\'s lifetime to a node: the row is deleted when that node is deleted. Without an anchor it outlives every node; it ends through its one-shot run, --expires, explicit cancellation, or self-cancellation from its bash.' },
             { kind: 'flag', name: 'anchor-self', type: 'bool', required: false, constraint: 'Anchor to the calling node ($CRTR_NODE_ID). Errors outside a node.' },
             { kind: 'flag', name: 'cancel-on-wake', type: 'bool', required: false, constraint: 'Also delete the row when the anchor node revives: use only when the cron belongs to that current dormancy, not for standing work. Requires an anchor; at most one cancel-on-wake cron per anchor — arming a second replaces the anchor’s pending one.' },
@@ -287,7 +287,7 @@ const listLeaf = defineLeaf({
         summary: 'every cron in scope, next-fire order',
         params: [],
         output: [
-            { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
+            { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true while parked by an exit-75 gate — fires on daemon poke, else at fire_at), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
         ],
         outputKind: 'object',
         effects: [],
@@ -301,6 +301,7 @@ const listLeaf = defineLeaf({
                 fire_at: c.fire_at,
                 recur: cadenceDisplay(c.recur),
                 state: c.state,
+                held: c.held,
                 on_output: c.on_output,
                 sink: c.sink,
                 expires_at: c.expires_at,
@@ -321,7 +322,16 @@ const listLeaf = defineLeaf({
             ];
             if (c.expires_at !== null)
                 bits.push(`expires ${c.expires_at}`);
-            const marker = c.state === 'paused' ? ' [PAUSED — resume or cancel]' : '';
+            // The state cell derives from both fields: an active held row must never
+            // present as paused (paused is user-owned and blocks firing; held fires
+            // the moment a poke lands), and the held fact is never hidden.
+            const marker = c.state === 'paused'
+                ? c.held
+                    ? ' [PAUSED (held) — resume or cancel]'
+                    : ' [PAUSED — resume or cancel]'
+                : c.held
+                    ? ' [HELD — last run exited 75; fires on daemon poke]'
+                    : '';
             return `- ${c.name} (${c.cron_id}) — ${bits.join(', ')}${marker}`;
         });
         return `${crons.length} cron(s):\n\n${lines.join('\n')}`;
@@ -355,11 +365,23 @@ const showLeaf = defineLeaf({
     render: (r) => {
         const c = r['cron'];
         const runs = r['runs'];
-        const schedule = c.recur !== null ? cadenceDisplay(c.recur) : `one-shot at ${c.fire_at}`;
+        const schedule = c.recur !== null ? cadenceDisplay(c.recur) : c.held ? 'one-shot' : `one-shot at ${c.fire_at}`;
+        const tzPart = c.tz !== null ? ` (tz ${c.tz})` : '';
+        // A held row's next-fire is its BACKSTOP, not a promise: a daemon poke
+        // fires it earlier. A held one-shot has no clock slot at all — it waits
+        // for a poke until --expires deletes it (or forever, without one).
+        const scheduleLine = !c.held
+            ? `- schedule: ${schedule}${tzPart} — next fire ${c.fire_at}`
+            : c.recur !== null
+                ? `- schedule: ${schedule}${tzPart} — backstop ${c.fire_at} (held — fires early on daemon poke; last run exited 75)`
+                : c.expires_at !== null
+                    ? `- schedule: ${schedule}${tzPart} — backstop none — expires ${c.expires_at} (held — fires on daemon poke; deleted unfired at expiry)`
+                    : `- schedule: ${schedule}${tzPart} — backstop none (held — fires only on daemon poke)`;
+        const stateTag = c.state === 'paused' ? (c.held ? ' — PAUSED (held)' : ' — PAUSED') : c.held ? ' — HELD' : '';
         const lines = [
-            `# ${c.name} (${c.cron_id})${c.state === 'paused' ? ' — PAUSED' : ''}`,
+            `# ${c.name} (${c.cron_id})${stateTag}`,
             '',
-            `- schedule: ${schedule}${c.tz !== null ? ` (tz ${c.tz})` : ''} — next fire ${c.fire_at}`,
+            scheduleLine,
             `- disposition: ${c.on_output}${c.sink !== null ? ` → ${c.sink} (tier ${c.tier})` : ''}`,
             `- context: cwd ${c.cwd}${c.profile !== null ? `, profile ${c.profile}` : ''}, scope ${c.scope}${c.env_keys.length > 0 ? `, env ${c.env_keys.join(', ')}` : ''}`,
             `- run: timeout ${c.run_timeout_s}s, overlap ${c.overlap}${c.run_state === 'running' ? ' — a run is IN FLIGHT now' : ''}`,
@@ -521,7 +543,7 @@ export function registerCron() {
         help: {
             name: 'cron',
             summary: 'scheduled bash commands, daemon-run',
-            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node, an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A bash predicate can gate whether a fire acts; cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
+            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node, an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 and the occurrence is OWED: the row is held, fires again the moment the daemon receives an eligibility poke from the host platform, and otherwise re-checks at its next natural slot (a held one-shot instead waits for a poke until --expires deletes it unfired). Any other nonzero exit is a real failure and escalates per --on-output. Use 75 for "not yet — retry when conditions change" (a device coming online); keep gate ERRORS nonzero so a broken probe is loud instead of silently parked. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
         },
         children: [addLeaf, listLeaf, showLeaf, runLeaf, pauseLeaf, resumeLeaf, cancelLeaf],
     });

package/dist/commands/human/prompts.d.ts

@@ -1,6 +1,11 @@
 import type { DeckSource } from '../../core/human/types.js';
-/** Optional presentation label for crouter tickets. Ticket identity and attribution
- * come from the bridge node directory and parent relation, never ticket data. */
+/** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
+ * directory, never ticket data; `nodeId` carries the originating node so a
+ * consumer can relate a ticket back to whatever that node belongs to, and
+ * `sessionName` is a presentation label only. Review tickets already stamp
+ * `nodeId` the same way (`core/review/realize.ts`), so decks match them.
+ * `nodeId` is stamped even when the daemon is unreachable — losing the label is
+ * survivable, losing machine attribution is not. */
 export declare function sourceStamp(): Promise<DeckSource>;
 export declare const humanAsk: import("../../core/command.js").LeafDef;
 export declare const humanNotify: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -17,23 +17,27 @@ import { ticketDir } from '../../core/human/root.js';
 import { submitDeck } from '../../core/human/tickets.js';
 import { display } from '../../core/termrender/display.js';
 import { BODY_PATH_CONTRACT, DECK_SCHEMA_HINT, resolveMaxPanes } from './shared.js';
-import { inboxHint, inboxOpenInstruction } from '../../core/keybindings/index.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
 }
-/** Optional presentation label for crouter tickets. Ticket identity and attribution
- * come from the bridge node directory and parent relation, never ticket data. */
+/** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
+ * directory, never ticket data; `nodeId` carries the originating node so a
+ * consumer can relate a ticket back to whatever that node belongs to, and
+ * `sessionName` is a presentation label only. Review tickets already stamp
+ * `nodeId` the same way (`core/review/realize.ts`), so decks match them.
+ * `nodeId` is stamped even when the daemon is unreachable — losing the label is
+ * survivable, losing machine attribution is not. */
 export async function sourceStamp() {
     const nodeId = askingNode();
     if (nodeId === null || nodeId === '')
         return {};
     try {
         const sessionName = (await cliClient().getNode(nodeId)).name.trim();
-        return sessionName === '' ? {} : { sessionName };
+        return sessionName === '' ? { nodeId } : { nodeId, sessionName };
     }
     catch {
-        return {};
+        return { nodeId };
     }
 }
 function requireAskTitle(title) {
@@ -100,11 +104,12 @@ function canonicalizeAskKinds(deck) {
         })),
     };
 }
-/** The non-blocking status peek returned by ask/review. Resolved per call so
- *  the inbox affordance reflects the human's current keybinding (or the CLI
- *  fallback when the toggle is disabled). */
+/** The non-blocking status peek returned by ask/review. How the human reaches
+ *  their inbox is theirs, not the agent's — naming a shortcut here only teaches
+ *  agents to repeat a screen-specific gesture back to a reader who may be on a
+ *  different surface entirely. */
 function queuedFollowUp() {
-    return `Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block. To see the queue, ${inboxOpenInstruction()}.`;
+    return 'Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block.';
 }
 // ---------------------------------------------------------------------------
 // ask
@@ -131,7 +136,7 @@ export const humanAsk = defineLeaf({
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" node under you and enqueues a decision deck in the human inbox.',
-            `Returns immediately; nothing opens on screen. The human answers from the inbox (${inboxHint()}) on their own time.`,
+            'Returns immediately; nothing opens on screen. The human answers from their inbox on their own time.',
         ],
     },
     run: async (input, context) => {

package/dist/commands/human.js

@@ -9,7 +9,6 @@ import { humanReviewBranch } from './human/review.js';
 import { humanList, humanDeck, humanResolve, humanCancel } from './human/queue.js';
 import { humanInbox } from './human/inbox.js';
 import { humanDoc } from './human/doc.js';
-import { inboxOpenInstruction } from '../core/keybindings/index.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
@@ -21,7 +20,7 @@ export function registerHuman() {
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`crtr human doc check\` to validate a body before submitting it. ask creates a kind:'human' bridge node under you and returns instantly, never blocking. Nothing opens on screen — the ticket is queued in the human inbox; the human opens it — ${inboxOpenInstruction()} — on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call. review is a branch: new queues a live document for the human to review in the attach viewer alongside a companion agent, while comment verbs operate on daemon-owned anchored comments; approval is pushed back as an approval fact, and a changed document instructs the origin to re-read it. notify enqueues a durable acknowledgement with no node; show is passive live display. inbox opens or toggles the queue on this screen; doc validates or renders a directive-flavored markdown body.`,
+            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`crtr human doc check\` to validate a body before submitting it. ask creates a kind:'human' bridge node under you and returns instantly, never blocking. Nothing opens on screen — the ticket is queued in the human inbox; the human opens it on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call. review is a branch: new queues a live document for the human to review in the attach viewer alongside a companion agent, while comment verbs operate on daemon-owned anchored comments; approval is pushed back as an approval fact, and a changed document instructs the origin to re-read it. notify enqueues a durable acknowledgement with no node; show is passive live display. inbox opens or toggles the queue on this screen; doc validates or renders a directive-flavored markdown body.`,
         },
         children: [
             humanAsk,

package/dist/commands/memory/find.js

@@ -3,7 +3,7 @@ import { usage } from '../../core/errors.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { paginate } from '../../core/pagination.js';
-import { MEMORY_KINDS } from './shared.js';
+import { MEMORY_KINDS, MEMORY_SCOPES } from './shared.js';
 function substrateUnit(d) {
     return {
         name: d.name,
@@ -16,14 +16,15 @@ function substrateUnit(d) {
     };
 }
 /** The candidate set: every substrate memory document (native + plugin, supplied
- *  by listAllMemoryDocs), optionally narrowed to one kind. find searches
- *  EVERYTHING — it never applies gate or visibility-rung filtering (design
- *  §11#3).
+ *  by listAllMemoryDocs), optionally narrowed to one kind and/or one scope.
+ *  Within that explicit narrowing find searches EVERYTHING — it never applies
+ *  gate or visibility-rung filtering (design §11#3); --kind/--scope are caller
+ *  intent, not a visibility policy.
  *
  *  Dedup by (scope, name): native and plugin docs of the same scope can collide
  *  on identity. The FIRST unit encountered for a given identity wins — native
  *  before plugin, which mirrors the memory resolver's own precedence. */
-function candidates(kindFilter) {
+function candidates(kindFilter, scopeFilter) {
     const seen = new Set(); // "scope/name" → first wins
     const add = (u) => {
         const id = `${u.scope}/${u.name}`;
@@ -33,7 +34,7 @@ function candidates(kindFilter) {
         units.push(u);
     };
     const units = [];
-    for (const doc of listAllMemoryDocs()) {
+    for (const doc of listAllMemoryDocs(scopeFilter)) {
         const sub = parseSubstrateDoc(doc);
         if (sub === null)
             continue;
@@ -46,13 +47,14 @@ function candidates(kindFilter) {
 export const findLeaf = defineLeaf({
     name: 'find',
     description: 'relevance search across memory documents',
-    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, the read-routing line, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
+    whenToUse: 'you already have a topic or keyword in mind and need to find which document covers it — ranks documents by relevance, weighted over name, the read-routing line, and short-form (add --body to also weigh body text). Searches every scope by default regardless of any visibility gate; --scope narrows to one. Reach for `crtr memory list` instead when you want the whole inventory rather than a topic match, and --grep when you need an exact regex or literal-string match across document bodies.',
     help: {
         name: 'memory find',
         summary: 'bounded relevance search across memory documents, weighted over name/routing-line/short-form (and body with --body)',
         params: [
             { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. By default returns at most 10 hits scoring at least half the top score. With --grep: an ECMAScript regex applied to each document body line.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes, builtin included.' },
             { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body.' },
             { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies.' },
             { kind: 'flag', name: 'limit', type: 'int', required: false, constraint: 'Maximum hits to return per page after relevance filtering. Default 10, hard max 100.' },
@@ -73,6 +75,7 @@ export const findLeaf = defineLeaf({
     run: async (input) => {
         const query = input['query'];
         const kindFilter = input['kind'];
+        const scopeFilter = input['scope'];
         const grep = input['grep'];
         const weighBody = input['body'];
         const limitArg = input['limit'];
@@ -90,7 +93,7 @@ export const findLeaf = defineLeaf({
         if (minScore !== undefined && minScore < 1)
             throw usage('--min-score must be at least 1.');
         const limit = limitArg ?? 10;
-        const units = candidates(kindFilter);
+        const units = candidates(kindFilter, scopeFilter);
         // --- grep mode: regex over every unit's body, one row per matching line ---
         if (grep) {
             let regex;

package/dist/commands/memory/read.js

@@ -1,12 +1,13 @@
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.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 { createMemoryDocSnapshot, listAllMemoryDocs, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
+import { effectiveDocKind, parseSubstrateDoc, previewLine } from '../../core/substrate/schema.js';
+import { displayName, indexDirOf, isIndexName } 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 { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
 import { MEMORY_KINDS } from './shared.js';
 export { createMemoryDocSnapshot, resolveMemoryDocs };
 /** Load the body at an already-resolved memory path with the same frontmatter
@@ -19,6 +20,89 @@ export function readMemoryDocContent(path, includeFrontmatter = false) {
     const nodeId = process.env['CRTR_NODE_ID'];
     return nodeId ? interpolateNodePaths(content, nodeId) : content;
 }
+/** The routing list appended to a directory-INDEX read: one line per document
+ * the INDEX gates, `[[name]]: <when-and-why-to-read>`. Membership is the
+ * directory's docs unioned with the body's resolvable `[[links]]`, deduped —
+ * a nested INDEX stands in for its whole subtree with a single line, while a
+ * subdirectory without an INDEX is transparent and its leaves render directly
+ * (mirroring how boot ceilings govern to the nearest INDEX). Every member
+ * renders regardless of its own visibility rung: rungs price unsolicited
+ * surfaces, and a read is a deliberate act. The root INDEX is excluded — the
+ * top-level namespace merges across stores, so its "directory" would
+ * enumerate the entire corpus. */
+function indexRoutes(doc) {
+    // A dir INDEX resolves two ways: the explicit `dir/INDEX` name, or the bare
+    // dir name (which carries the dir as its identity while the path is the
+    // INDEX.md). Detect from the path so both shapes route identically.
+    if (!doc.path.endsWith('/INDEX.md'))
+        return [];
+    const dir = isIndexName(doc.name) ? indexDirOf(doc.name) : doc.name;
+    if (dir === '')
+        return [];
+    const canonicalName = `${dir}/INDEX`;
+    let corpus;
+    try {
+        corpus = listAllMemoryDocs(undefined, true);
+    }
+    catch {
+        return [];
+    }
+    // First occurrence wins: listAllMemoryDocs emits in resolver-precedence
+    // order, so the doc that renders a name's line is the doc a read of that
+    // name would actually return.
+    const byName = new Map();
+    for (const d of corpus)
+        if (!byName.has(d.name))
+            byName.set(d.name, d);
+    const prefix = dir + '/';
+    const members = new Map();
+    for (const [name, d] of byName) {
+        if (!name.startsWith(prefix) || name === canonicalName)
+            continue;
+        // The shallowest INDEX between the gating dir and this doc stands in for
+        // it (an INDEX finds itself here, keeping its own single line).
+        const segs = name.slice(prefix.length).split('/');
+        let member = d;
+        for (let i = 1; i < segs.length; i++) {
+            const gate = byName.get(`${prefix}${segs.slice(0, i).join('/')}/INDEX`);
+            if (gate !== undefined) {
+                member = gate;
+                break;
+            }
+        }
+        if (!members.has(member.name))
+            members.set(member.name, member);
+    }
+    // No members means this INDEX gates no cluster in the corpus namespace — a
+    // store-root front door whose explicit frontmatter name dodges the root
+    // check above lands here. Fall back to the plain links field.
+    if (members.size === 0)
+        return [];
+    // Union the body's authored links so one list carries everything this INDEX
+    // routes to — the routes list subsumes `links` on an INDEX read.
+    for (const linkName of docLinkNames(doc.body)) {
+        let linked;
+        try {
+            linked = resolveMemoryDoc(linkName);
+        }
+        catch {
+            continue; // dangling link — lint's finding, not read's
+        }
+        if (displayName(linked.name) !== linkName || linked.name === canonicalName || linked.name === doc.name)
+            continue;
+        if (!members.has(linked.name))
+            members.set(linked.name, linked);
+    }
+    return [...members.values()]
+        .map((m) => {
+        const label = displayName(m.name);
+        const sub = parseSubstrateDoc(m);
+        const line = sub === null ? '' : previewLine(sub);
+        return { label, line: line === '' ? `[[${label}]]` : `[[${label}]]: ${line}` };
+    })
+        .sort((a, b) => a.label.localeCompare(b.label))
+        .map((e) => e.line);
+}
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
@@ -36,12 +120,15 @@ export const readLeaf = defineLeaf({
             { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — direct edits here are for a small body-only tweak; any routing/frontmatter/visibility change goes through `crtr memory write`.' },
-            { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
-            { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. Omitted when the body carries no resolvable links.' },
+            { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text.' },
+            { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. Omitted when the body carries no resolvable links, and subsumed by `routes` on a directory-INDEX read.' },
+            { name: 'routes', type: 'string[]', required: false, constraint: 'Present only when the document is a directory INDEX: one routing line per document the INDEX gates — the directory’s members plus the body’s resolvable links, a nested INDEX standing in for its subtree with a single line. Follow one with `crtr memory read <name>` when the task in front of you matches its line.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only.'],
+        effects: [
+            'Reads the document. A document that embeds shell (`!`cmd`` or a ```! block) runs those commands once, in the current working directory.',
+        ],
     },
     run: async (input) => {
         const nameRaw = input['name'];
@@ -63,11 +150,21 @@ export const readLeaf = defineLeaf({
         }
         if (doc !== undefined) {
             const kind = effectiveDocKind(doc);
-            const content = readMemoryDocContent(doc.path, includeFrontmatter);
+            const raw = readMemoryDocContent(doc.path, includeFrontmatter);
+            // A read is an explicit act by an agent that can already run shell, so a
+            // document's embedded commands run here and their output lands inline —
+            // the same contract as invoking the document as a slash command. Nothing
+            // executes on the auto-load path, which never reaches this leaf.
+            const content = hasShellBlocks(raw)
+                ? await expandShellBlocks(raw, makeNodeShellRunner({ cwd: process.cwd() }))
+                : raw;
             // `[[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.
-            const links = docLinkNames(doc.body).filter((linkName) => {
+            // A directory INDEX is a gate: its read appends one routing line per doc
+            // it gates, subsuming the links field. Non-INDEX reads keep plain links.
+            const routes = indexRoutes(doc);
+            const links = routes.length > 0 ? [] : docLinkNames(doc.body).filter((linkName) => {
                 try {
                     // `resolveMemoryDoc` permits leaf-name fallback for interactive reads;
                     // a stored graph edge does not. Compare the resolved canonical name
@@ -84,10 +181,13 @@ export const readLeaf = defineLeaf({
                 scope: doc.scope,
                 path: doc.path,
                 content,
+                ...(routes.length > 0 ? { routes } : {}),
                 ...(links.length > 0 ? { links } : {}),
-                follow_up: (links.length > 0
-                    ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
-                    : '') +
+                follow_up: (routes.length > 0
+                    ? 'This INDEX gates the docs listed in `routes` — follow one with `crtr memory read <name>` when the task in front of you matches its line. '
+                    : links.length > 0
+                        ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
+                        : '') +
                     'Use --frontmatter on this same command to inspect the YAML frontmatter, or edit `path` directly for a body-only tweak. Browse the inventory with `crtr memory list`.',
             };
         }

package/dist/commands/memory/write.js

@@ -24,7 +24,7 @@ export const writeLeaf = defineLeaf({
             '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. 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' +
+            'A directory INDEX earns existence only where the aggregate view beats the sum of per-file rungs. Aggregated child routing is automatic: `crtr memory read` of a directory INDEX appends every member’s routing line (`[[name]]: <when-and-why-to-read>`), so never author that list in the body. Two shapes pass: synthesis — an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single child can carry — and a pure gate — one preview line covering a cluster with one shared routing condition, the body adding nothing the automatic list does not. 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 body 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: [

package/dist/commands/memory.js

@@ -19,7 +19,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Discover a document with `find` when its name is unknown; address it directly with `read`/`write` when known. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read`/`write` once you know its name. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, deleteLeaf, originLeaf, lintLeaf],
     });

package/dist/commands/pkg/market-manage.d.ts

@@ -1,3 +1,16 @@
+import type { Scope } from '../../types.js';
+/** Clone a marketplace repo into `scope` and register it in that scope's
+ *  config. Shared by the `pkg market add` leaf and `crtr sys setup`, which
+ *  offers the official marketplace as a checked-by-default entry. */
+export declare function addMarketplace(opts: {
+    url: string;
+    ref?: string;
+    scope: Scope;
+}): {
+    name: string;
+    scope: Scope;
+    path: string;
+};
 export declare const marketAdd: import("../../core/command.js").LeafDef;
 export declare const marketRemove: import("../../core/command.js").LeafDef;
 export declare const marketUpdate: import("../../core/command.js").LeafDef;