@north-light/crouter 0.3.180 → 0.3.182

package/dist/api/client.d.ts

@@ -5,11 +5,12 @@ import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery }
 import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
 import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
 import type { FocusDTO, RegisterFocusRequest, SetFocusPaneRequest } from './dto/focus.js';
-import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery } from './dto/crons.js';
+import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery, type PokeCronsResult } from './dto/crons.js';
 import type { NodeConfigPatch } from './dto/config.js';
 import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
 import type { EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
+import type { MemoryDocRefDTO } from './dto/memory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
 import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
@@ -131,6 +132,10 @@ export declare class CrtrClient {
     runCron(cronId: string, q?: CronScopeQuery): Promise<CronRunDTO>;
     /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
     cancelCron(cronId: string, q?: CancelCronQuery): Promise<void>;
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons(): Promise<PokeCronsResult>;
     ensureAttach(id: string, req?: AttachEnsureRequest): Promise<AttachEnsureResultDTO>;
     getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
     getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
@@ -143,6 +148,10 @@ export declare class CrtrClient {
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
      *  the browser file-peek panel. */
     peekFile(path: string): Promise<FilePeekDTO>;
+    /** Resolve a `[[name]]` memory-document link to the absolute path the given
+     *  node would read — the node's own precedence chain, not this process's.
+     *  Pair with `peekFile` to render the document. */
+    resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;

package/dist/api/client.js

@@ -227,6 +227,12 @@ export class CrtrClient {
     async cancelCron(cronId, q) {
         await this.request('DELETE', withQuery(routes.cron(this.cronPath(cronId)), q));
     }
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons() {
+        return this.request('POST', routes.cronsPoke(), {});
+    }
     ensureAttach(id, req) {
         return this.request('POST', routes.nodeAttach(this.nodePath(id)), req ?? {});
     }
@@ -257,6 +263,13 @@ export class CrtrClient {
     peekFile(path) {
         return this.request('GET', withQuery(routes.filePeek(), { path }));
     }
+    // ---- Memory documents --------------------------------------------------
+    /** Resolve a `[[name]]` memory-document link to the absolute path the given
+     *  node would read — the node's own precedence chain, not this process's.
+     *  Pair with `peekFile` to render the document. */
+    resolveMemoryDoc(name, nodeId) {
+        return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
+    }
     // ---- Profiles ----------------------------------------------------------
     ensureProfile(name, req) {
         return this.request('PUT', routes.profile(name), req ?? {});

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

@@ -28,6 +28,38 @@ export interface BrokerWelcomeSnapshot<M = unknown> {
 export interface BrokerWelcomeFrame<M = unknown> {
     type: 'welcome';
     snapshot?: BrokerWelcomeSnapshot<M>;
+    /** The last few id-bearing user-message dispatches from the broker's message
+     *  ledger, oldest first — so a reattaching follower can key the snapshot's
+     *  trailing user wakes by id (the id a sender minted via `message_id` on
+     *  `POST .../messages`) instead of discarding them heuristically. Live-process
+     *  memory only: a broker restart loses it. Absent on a broker pinned to an
+     *  older runtime generation. */
+    recentUserMessages?: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+/**
+ * The additive identity fields the broker sets on a relayed pi `queue_update`:
+ * id arrays PARALLEL to pi's text arrays (`steeringIds[i]` identifies
+ * `steering[i]`). Sender-minted when the send carried `message_id`,
+ * broker-minted otherwise. Absent on a broker pinned to an older runtime
+ * generation — consumers fall back to bare texts. Intersect with the pinned pi
+ * `queue_update` event shape to read them typed.
+ */
+export interface RelayedQueueUpdateIdentity {
+    steeringIds?: string[];
+    followUpIds?: string[];
+}
+/**
+ * The additive identity field the broker sets on a relayed USER-role
+ * `message_start`: the message's crouter id — the `message_id` its sender
+ * minted, or a broker-minted one. Absent when the message carries none (an
+ * engine-command expansion, a pre-ledger replay, an older broker). Intersect
+ * with the pinned pi `message_start` event shape to read it typed.
+ */
+export interface RelayedUserMessageStartIdentity {
+    crtrMessageId?: string;
 }
 /**
  * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot)

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

@@ -53,6 +53,14 @@ export interface CronDTO {
     sink: string | null;
     tier: string;
     state: CronStateDTO;
+    /** True while the row is parked by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A daemon poke re-dues it now; otherwise a
+     *  recurring row re-checks at its natural `fire_at` slot (the backstop) and
+     *  a held one-shot waits for a poke until `expires_at` deletes it. `state`
+     *  stays honest (active|paused) — renderers derive; an active held row must
+     *  never present as paused. */
+    held: boolean;
     run_state: CronRunStateDTO;
     /** Recent health: the most recent settled run, or null if it never ran. */
     last_run: CronLastRunDTO | null;
@@ -93,6 +101,15 @@ export interface CronRunDTO {
     /** What the sink did with this run's output, or why it didn't. */
     delivered: string | null;
 }
+/** `POST /v1/crons/poke` — the bare daemon-level eligibility poke. Re-dues
+ *  every held active cron now; paused rows keep their held state. Idempotent
+ *  and free when nothing is held. */
+export interface PokeCronsResult {
+    /** How many held rows were re-dued — for the caller's log line. */
+    unparked: number;
+    /** The poke receipt instant (UTC). */
+    at: IsoTime;
+}
 /** `GET /v1/crons/:cronId` — one cron with its run-log ring (most recent first). */
 export interface CronShowDTO {
     cron: CronDTO;

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

@@ -0,0 +1,17 @@
+/** `GET /v1/memory/resolve?name=<name>&node=<id>` result — where the named
+ *  document lives for that node. Resolution runs the node's own precedence
+ *  chain (its context store, its project stack, its profile, user, builtin), so
+ *  the same name can answer with different documents for different nodes. */
+export interface MemoryDocRefDTO {
+    /** The document's canonical identity (its frontmatter `name`, else its
+     *  path-derived name) — which may differ from the queried name when the query
+     *  was a bare leaf or a directory whose INDEX resolved. */
+    name: string;
+    /** Which store it came from: node | project | profile | user | builtin. */
+    scope: string;
+    /** Absolute path to the `.md` file. */
+    path: string;
+    /** The owning plugin's name when the doc is mounted from an installed plugin,
+     *  absent for a native scope doc. */
+    plugin?: string;
+}

package/dist/api/dto/memory.js

@@ -0,0 +1,6 @@
+// Memory-document resolution DTO. Backs `GET /v1/memory/resolve` — a client
+// holding a `[[name]]` link out of a node's transcript turns it into the
+// absolute path of the document that node would read, then peeks that path.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

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

@@ -26,6 +26,11 @@ export interface SendMessageRequest {
      *  body only — rejected with fresh/reopen/situational_context/
      *  output_schema or tier 'deferred'. Absent → durable inbox (unchanged). */
     delivery?: 'interactive';
+    /** Sender-minted message identity for a `delivery:'interactive'` send. The
+     *  broker mirrors it through pi's queues and echoes it on the relayed user
+     *  `message_start` (`crtrMessageId`), so an optimistic sender (the gateway)
+     *  retires its pending entry by exact id. Ignored on the durable-inbox path. */
+    message_id?: string;
 }
 /** Result of an immediate message send. */
 export interface MessageResultDTO {

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

@@ -38,6 +38,9 @@ export interface ReviewDTO {
     created: IsoTime;
     /** Daemon open timestamp, after the companion binds. */
     opened_at?: IsoTime;
+    /** When the human submitted a review whose companion was still working. The
+     *  review remains `open` until the companion goes quiet. */
+    submit_requested_at?: IsoTime;
     /** Daemon source-read status at projection time. */
     source_missing: boolean;
     /** Daemon-owned current comment-coordinate source digest. */
@@ -73,12 +76,13 @@ export interface ListReviewsQuery {
 export interface ReviewListDTO {
     reviews: ReviewDTO[];
 }
-/** Daemon-derived result of terminal review approval. */
+/** Daemon-derived result of review approval, which may still be waiting on the
+ *  review's companion. */
 export interface ReviewSubmitResultDTO {
     review: ReviewDTO;
-    /** Immutable approval result. */
-    result: FeedbackResultDTO;
-    outcome: 'settled' | 'already_settled';
+    /** Immutable approval result; absent while the approval awaits the companion. */
+    result?: FeedbackResultDTO;
+    outcome: 'settled' | 'already_settled' | 'awaiting_companion';
 }
 /** Daemon-derived result of terminal review cancellation. */
 export interface ReviewCancelResultDTO {

package/dist/api/index.d.ts

@@ -21,6 +21,7 @@ export * from './dto/canvas.js';
 export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
+export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';

package/dist/api/index.js

@@ -22,6 +22,7 @@ export * from './dto/canvas.js';
 export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
+export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';

package/dist/api/routes.d.ts

@@ -46,6 +46,7 @@ export declare const routes: {
     readonly cronPause: (cronId: string) => string;
     readonly cronResume: (cronId: string) => string;
     readonly cronRun: (cronId: string) => string;
+    readonly cronsPoke: () => string;
     readonly canvasAttention: () => string;
     readonly canvasAttentionCounts: () => string;
     readonly canvasHistorySearch: () => string;
@@ -81,4 +82,5 @@ export declare const routes: {
     readonly modelAuths: () => string;
     readonly modelAuth: (provider: string) => string;
     readonly filePeek: () => string;
+    readonly memoryResolve: () => string;
 };

package/dist/api/routes.js

@@ -67,6 +67,7 @@ export const routes = {
     cronPause: (cronId) => `${V}/crons/${cronId}/pause`,
     cronResume: (cronId) => `${V}/crons/${cronId}/resume`,
     cronRun: (cronId) => `${V}/crons/${cronId}/run`,
+    cronsPoke: () => `${V}/crons/poke`,
     // Canvas maintenance / reads
     canvasAttention: () => `${V}/canvas/attention`,
     canvasAttentionCounts: () => `${V}/canvas/attention/counts`,
@@ -112,4 +113,7 @@ export const routes = {
     // Host file read (browser file-peek panel). The absolute path rides as a
     // `path` query param, not a path segment — it is not a single safe segment.
     filePeek: () => `${V}/files/peek`,
+    // Memory-document resolution (a `[[name]]` link in a node's transcript). Both
+    // the name and the node it is resolved for ride as query params.
+    memoryResolve: () => `${V}/memory/resolve`,
 };

package/dist/build-root.d.ts

@@ -2,6 +2,13 @@ import type { RootDef } from './core/command.js';
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */
 export declare const SUBTREE_NAMES: readonly string[];
+/** Every core command path, space-joined ("cron", "cron add", …) — the set
+ *  plugin `helpAddenda` keys are validated against at the strict gates
+ *  (install, bundle parse, doctor/inspect reports). Loads every core subtree,
+ *  so call it only from those gates, never on a dispatch path. Passthrough
+ *  branches are excluded: crtr never renders their help, so an addendum
+ *  targeting one could never appear. */
+export declare function coreCommandPaths(): Promise<ReadonlySet<string>>;
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
  *  `-h`/`--help`, `--version`, and any unknown leading token all need the

package/dist/build-root.js

@@ -23,6 +23,27 @@ const SUBTREE_LOADERS = {
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */
 export const SUBTREE_NAMES = Object.freeze(Object.keys(SUBTREE_LOADERS));
+/** Every core command path, space-joined ("cron", "cron add", …) — the set
+ *  plugin `helpAddenda` keys are validated against at the strict gates
+ *  (install, bundle parse, doctor/inspect reports). Loads every core subtree,
+ *  so call it only from those gates, never on a dispatch path. Passthrough
+ *  branches are excluded: crtr never renders their help, so an addendum
+ *  targeting one could never appear. */
+export async function coreCommandPaths() {
+    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    const paths = new Set();
+    const visit = (node, prefix) => {
+        if (node.kind === 'branch' && node.passthrough !== undefined)
+            return;
+        paths.add(prefix);
+        if (node.kind === 'branch')
+            for (const child of node.children)
+                visit(child, `${prefix} ${child.name}`);
+    };
+    for (const subtree of core)
+        visit(subtree, subtree.name);
+    return paths;
+}
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
  *  `-h`/`--help`, `--version`, and any unknown leading token all need the

package/dist/builtin-memory/insights/init.md

@@ -8,11 +8,15 @@ slash: true
 rationale: Ordinary conversations, corrections, answers to `crtr human ask`, and review comments carry unique user knowledge that agents inconsistently recognize or save; when agents do infer a deeper principle, they have written it without first letting the user correct the extrapolation.
 ---
 
-# /insights:init — begin passive domain listening
+# /insights:init — begin domain listening
 
-Initialize an ordinary memory directory that listens for user-derived insight about this domain. This version is passive: do not start research, schedule work, create a standing node, or proactively question the user after initialization.
+Initialize an ordinary memory directory that listens for user-derived insight about this domain.
 
-**Requested domain:** $ARGUMENTS
+**Requested domain and mode:** $ARGUMENTS
+
+## Check for --active flag
+
+If `$ARGUMENTS` contains `--active`, follow the **active mode** steps below. Otherwise, follow the **passive mode** steps.
 
 ## Establish the topic and scope
 
@@ -43,3 +47,44 @@ Keep the body short. It contains:
 Do not copy the capture workflow into the listener. The link keeps that process in one maintained place. Do not create placeholder principle documents.
 
 Run `crtr memory lint`, fix every finding, then report the canonical listener name, selected scope, and the domain boundary. Initialization is complete once the routed listener exists; no independent work follows.
+
+## Active mode: research and surface claims
+
+When `--active` is present, do not stop after creating the listener. After initialization:
+
+### 1. Create the listener first
+
+Follow the passive mode steps above through "Initialization is complete." The listener INDEX must exist before spawning the explorer.
+
+### 2. Spawn the explorer child
+
+Run this exact command, replacing `<topic>` with the topic slug you chose above:
+
+```bash
+crtr node new --kind explore --name "explore-<topic>" <<'TASK'
+Investigate the domain "<topic>" thoroughly. Your goal is to surface 3–5 distinct, falsifiable claims or questions about how this domain works, what its gaps are, or what fundamental principles govern it. Each claim should be specific enough that the user can confirm it, refine it, or reject it outright.
+
+Gather evidence from code, docs, existing understanding, and project artifacts. Then present your claims clearly:
+
+**Claim 1:** [claim text]
+**Evidence:** [why you believe this]
+**Question:** [what would prove or disprove this?]
+
+Repeat for each claim. Write findings to $CRTR_CONTEXT_DIR/claims.md and report the absolute path.
+TASK
+```
+
+Do not wait for the explorer to finish—it runs in parallel. Move to the next step while it works.
+
+### 3. Coordinate user responses and capture flow
+
+When the explorer reports, share its claims with the user. For each claim, ask:
+- Does this ring true?
+- Is it incomplete or wrong?
+- What's the actual principle?
+
+For each user response, use [[insights/capture]] to extract and review the insight. Apply approved insights directly to the listener INDEX's `Approved insights` section.
+
+### 4. Report completion
+
+Once claims have been surfaced and user guidance has generated approved insights, report that active initialization is complete. The listener INDEX now passively captures this domain as new user material emerges.

package/dist/builtin-pi-packages/pi-crtr-extensions/__tests__/insights-active-init.test.ts

@@ -0,0 +1,98 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+
+// Integration test: /insights:init --active spawns an explorer and coordinates
+// insight capture flow. This test verifies that:
+// 1. The active mode doc exists and has slash: true
+// 2. The active mode instructions are present and executable
+// 3. A reader following the instructions can spawn an explorer
+
+test('insights/init has active mode documentation with executable commands', async () => {
+  const { readFileSync } = await import('fs');
+  const initPath = new URL('../../../builtin-memory/insights/init.md', import.meta.url);
+  const content = readFileSync(initPath, 'utf-8');
+
+  // Must be marked as a slash command
+  assert(content.includes('slash: true'), 'init.md must have slash: true frontmatter');
+
+  // Must have active mode section
+  assert(
+    content.includes('## Active mode: research and surface claims'),
+    'init.md must document active mode'
+  );
+
+  // Must have active flag check
+  assert(
+    content.includes('Check for --active flag') || content.includes('--active'),
+    'init.md must explain --active flag'
+  );
+
+  // Must have executable crtr commands for spawning explorer
+  assert(
+    content.includes('crtr node new --kind explore'),
+    'init.md must include crtr command to spawn explorer'
+  );
+
+  // Must reference the capture workflow
+  assert(
+    content.includes('[[insights/capture]]'),
+    'init.md must link to capture workflow'
+  );
+
+  // Must document waiting for explorer report
+  assert(
+    content.includes('Wait for the explorer to report') || content.includes('explorer'),
+    'init.md must explain waiting for explorer'
+  );
+
+  // Must document coordinating user responses
+  assert(
+    content.includes('user response') || content.includes('Turn user responses'),
+    'init.md must explain handling user responses'
+  );
+});
+
+test('active mode provides concrete bash commands agent can execute', async () => {
+  const { readFileSync } = await import('fs');
+  const initPath = new URL('../../../builtin-memory/insights/init.md', import.meta.url);
+  const content = readFileSync(initPath, 'utf-8');
+
+  // The active mode section should have a bash code block
+  const bashBlockMatch = content.match(/```bash\n([\s\S]*?)\n```/);
+  assert(bashBlockMatch, 'active mode must have a bash code block');
+
+  const bashContent = bashBlockMatch[1];
+
+  // Must have the crtr node new command
+  assert(bashContent.includes('crtr node new'), 'bash block must invoke crtr node new');
+
+  // Must specify --kind explore
+  assert(
+    bashContent.includes('--kind explore'),
+    'bash command must spawn explore kind'
+  );
+
+  // Must have the task heredoc
+  assert(
+    bashContent.includes('<<') || bashContent.includes('TASK'),
+    'bash command must include task definition'
+  );
+
+  // Must document the explorer task
+  assert(
+    bashContent.includes('investigate') || bashContent.includes('domain'),
+    'explorer task must mention domain investigation'
+  );
+
+  // Must ask explorer to surface claims
+  assert(
+    bashContent.includes('claim') || bashContent.includes('surface'),
+    'explorer task must ask for claims/surface evidence'
+  );
+
+  // Must reference output location
+  assert(
+    bashContent.includes('$CRTR_CONTEXT_DIR') || bashContent.includes('context'),
+    'explorer task must reference context directory output'
+  );
+});

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/claude-plugin-commands.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { truncateTail, formatSize, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import {
   readFileSync,
   readdirSync,
@@ -14,6 +13,8 @@ import { homedir } from "node:os";
 import { join, resolve, dirname } from "node:path";
 import { loadProfileManifest } from "../../../core/profiles/manifest.js";
 import { stripMarkdownComments } from "../../../core/runtime/command-expansion.js";
+import { expandShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from "../../../core/runtime/shell-expansion.js";
+import { piShellRunner } from "./pi-shell-runner.js";
 
 // ---------------------------------------------------------------------------
 // claude-plugin-commands: surfaces Claude Code commands AND skills as pi slash
@@ -367,57 +368,13 @@ function shellTimeoutMs(fm: string): number {
 }
 
 // ---- shell execution (mirrors @juicesharp/rpiv-args) -----------------------
-
-const SHELL_INLINE = /!`([^`\n]+)`/g;
-const SHELL_BLOCK = /```!\n([\s\S]*?)\n```/g;
-const DEFAULT_SHELL_TIMEOUT_MS = 120_000;
-
-function truncateForLLM(content: string): string {
-  const t = truncateTail(content, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
-  let out = t.content;
-  if (t.truncated) {
-    const limit = t.truncatedBy === "lines" ? `${t.maxLines} lines` : formatSize(t.maxBytes);
-    out += `\n[truncated: hit ${limit}]`;
-  }
-  return out;
-}
-
-async function runShell(cmd: string, pi: ExtensionAPI, cwd: string, timeoutMs: number): Promise<string> {
-  const [sh, flag] = process.platform === "win32" ? ["powershell.exe", "-Command"] : ["sh", "-c"];
-  const res: any = await pi.exec(sh, [flag, cmd], { cwd, timeout: timeoutMs });
-  if (res.killed) return `[Shell error: timed out after ${Math.max(1, Math.round(timeoutMs / 1000))}s]`;
-  if (res.code !== 0) return `[Shell error: exit code ${res.code}]\n${truncateForLLM(res.stderr ?? "")}`;
-  let combined = res.stdout ?? "";
-  if (res.stderr) {
-    const sep = combined.length === 0 || combined.endsWith("\n") ? "" : "\n";
-    combined = `${combined}${sep}[stderr]\n${res.stderr}`;
-  }
-  return truncateForLLM(combined);
-}
+//
+// The `!`cmd`` / ```! grammar and substitution order are shared with every
+// other surface that expands a Markdown body (`core/runtime/shell-expansion`);
+// the pi-engine execution strategy is shared through `pi-shell-runner`.
 
 async function executeShell(body: string, pi: ExtensionAPI, cwd: string, timeoutMs: number): Promise<string> {
-  // blocks first (mask with sentinels), then inlines, then restore.
-  const blockOut: string[] = [];
-  let masked = "";
-  let last = 0;
-  for (const m of body.matchAll(SHELL_BLOCK)) {
-    const idx = m.index ?? 0;
-    masked += body.slice(last, idx) + `\x00B${blockOut.length}\x00`;
-    blockOut.push(await runShell(m[1] ?? "", pi, cwd, timeoutMs));
-    last = idx + m[0].length;
-  }
-  masked += body.slice(last);
-
-  let inlined = "";
-  last = 0;
-  for (const m of masked.matchAll(SHELL_INLINE)) {
-    const idx = m.index ?? 0;
-    inlined += masked.slice(last, idx) + (await runShell(m[1] ?? "", pi, cwd, timeoutMs));
-    last = idx + m[0].length;
-  }
-  inlined += masked.slice(last);
-
-  return inlined.replace(/\x00B(\d+)\x00/g, (_, n) => blockOut[parseInt(n, 10)] ?? "");
+  return expandShellBlocks(body, piShellRunner(pi, cwd, timeoutMs));
 }
 
 // ---------------------------------------------------------------------------

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -5,6 +5,8 @@ import {
   expandDeterministicCommand,
   type DeterministicCommandExpansion,
 } from "../../../core/runtime/command-expansion.js";
+import { expandShellBlocks, hasShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from "../../../core/runtime/shell-expansion.js";
+import { piShellRunner } from "./pi-shell-runner.js";
 
 // ---------------------------------------------------------------------------
 // memory-slash-commands: any memory doc frontmatter-flagged `slash: true`
@@ -136,10 +138,23 @@ export default async function (pi: ExtensionAPI) {
           );
           return;
         }
+        // Shell runs HERE and only here. `expandDeterministicCommand` stays
+        // inert because it also drives the attach viewer's pre-submit preview,
+        // which re-expands on every keystroke — executing there would run the
+        // document's commands repeatedly while the user is still typing. This
+        // handler fires once, at submit, so the preview shows the command text
+        // and the submitted turn carries its output.
+        const expanded = expandDeterministicCommand(expansion, args ?? "");
+        const content = hasShellBlocks(expanded)
+          ? await expandShellBlocks(
+              expanded,
+              piShellRunner(pi, (ctx as { cwd?: string }).cwd ?? process.cwd(), DEFAULT_SHELL_TIMEOUT_MS),
+            )
+          : expanded;
         pi.sendMessage(
           {
             customType: "memory-slash-command",
-            content: expandDeterministicCommand(expansion, args ?? ""),
+            content,
             display: true,
           },
           { triggerTurn: true },

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/pi-shell-runner.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateTail, formatSize, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
+
+// The broker-side execution strategy for `core/runtime/shell-expansion`. Every
+// command surface that expands a Markdown body inside a pi engine shares it, so
+// the engine owns the subprocess and truncation uses pi's own limits. The
+// grammar and substitution order live in the shared module; only this strategy
+// is pi-specific, and it stays out of that module so CLI leaves can import the
+// expander without loading the pi runtime.
+
+function truncateForLLM(content: string): string {
+  const t = truncateTail(content, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+  let out = t.content;
+  if (t.truncated) {
+    const limit = t.truncatedBy === "lines" ? `${t.maxLines} lines` : formatSize(t.maxBytes);
+    out += `\n[truncated: hit ${limit}]`;
+  }
+  return out;
+}
+
+export function piShellRunner(pi: ExtensionAPI, cwd: string, timeoutMs: number) {
+  const [sh, flag] = process.platform === "win32" ? ["powershell.exe", "-Command"] : ["sh", "-c"];
+  return async (cmd: string): Promise<string> => {
+    const res: any = await pi.exec(sh, [flag, cmd], { cwd, timeout: timeoutMs });
+    if (res.killed) return `[Shell error: timed out after ${Math.max(1, Math.round(timeoutMs / 1000))}s]`;
+    if (res.code !== 0) return `[Shell error: exit code ${res.code}]\n${truncateForLLM(res.stderr ?? "")}`;
+    let combined = res.stdout ?? "";
+    if (res.stderr) {
+      const sep = combined.length === 0 || combined.endsWith("\n") ? "" : "\n";
+      combined = `${combined}${sep}[stderr]\n${res.stderr}`;
+    }
+    return truncateForLLM(combined);
+  };
+}

package/dist/cli.js

@@ -7,7 +7,7 @@ import { runCli } from './core/command.js';
 import { resolveRoot } from './build-root.js';
 import { maybeBootRoot } from './core/runtime/front-door.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
-import { ensureOfficialMarketplace, ensureProjectScope } from './core/bootstrap.js';
+import { ensureProjectScope } from './core/bootstrap.js';
 import { provisionExports, pruneLegacyExports } from './core/host-exports/export.js';
 import { installStdoutErrorPolicy } from './core/stdout-errors.js';
 import { handle } from './core/io.js';
@@ -54,7 +54,6 @@ async function main() {
     const root = await resolveRoot(process.argv[2]);
     mark('cli.root_resolved');
     provisionExports(root, process.argv);
-    ensureOfficialMarketplace(process.argv);
     ensureProjectScope(process.argv);
     maybeAutoUpdate(process.argv);
     mark('cli.dispatch_start');