@north-light/crouter 0.3.226 → 0.3.228

package/dist/builtin-memory/plan/roadmap.md

@@ -1,25 +1,27 @@
 ---
 kind: knowledge
-when-and-why-to-read: When choosing between a flat plan and a decomposed one, or synthesizing part-plans into an index, this knowledge should be read so a planning effort splits only where a domain seam pays for the synthesis it costs.
+when-and-why-to-read: When choosing between a flat plan and a decomposed one, or synthesizing part-plans into an index, this knowledge should be read so a planning effort splits only where independent execution repays the synthesis it costs.
 short-form: Use when deciding whether a planning effort splits into part-plans, and how to synthesize them into one index.
 gate: {kind: plan}
 rationale: >-
-  Carries plan shape and decomposition only. The general planning contract — scope discipline, task quality, plan review — lives in the plan kind layer so every plan node loads it whether or not the effort ever needs a roadmap; do not pull generic planning guidance back in here.
+  Carries plan shape and decomposition only. The implementation-unit contract lives in [[plan/guide]] so every planner can use it whether or not the effort ever needs a roadmap; do not pull generic planning guidance back in here.
 surfaces:
   - on: boot
     at: preview
 ---
 
-# Plan Shapes and the Decomposition Decision
+# Plan shapes and the decomposition decision
 
-Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choose decomposition for worthwhile parallel planning, not raw size: a flat plan can span many yields, while part-plans add delegation and synthesis cost that independent slices must repay.
+Every planning effort produces either one flat plan or an index with part-plans. Choose decomposition for worthwhile parallel planning, not raw size: a flat plan can span many yields, while part-plans add delegation and synthesis cost that independent slices must repay.
 
 ## Choosing a shape
 
-**Use a flat plan** when the work is a single coherent domain and can be written at consistent task granularity in one plan. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
+Use a **flat plan** when one coherent owner can map the work at consistent unit granularity. It follows [[plan/guide]] in one file.
 
-**Use a decomposed plan** when settled boundaries expose independent planning slices that can proceed concurrently and the effort is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. Produce an index plan (the navigable master) and delegate each slice to a `plan`-kind child node, giving it the relevant spec, explicit scope, and place in the dependency graph. A slice goes to a `plan` sub-orchestrator (`crtr node new --kind plan --mode orchestrator`) only when its own work passes the same parallelism threshold; a long sequential slice goes to a base child that can yield. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
+Use a **decomposed plan** when settled dependency edges expose slices that can be planned independently, their edit ownership does not overlap, and the effort is large enough that parallel work materially improves intelligence, productivity, or elapsed time. A frontend/backend distinction alone is not a decomposition trigger when both sides still share an unsettled seam or edit surface.
 
-**The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
+Produce a navigable index and delegate each slice to a `plan`-kind child with the approved spec and design, explicit scope, dependencies, and ownership boundary. A slice goes to a `plan` sub-orchestrator only when it independently passes the same parallelism threshold; a long sequential slice stays with a base child across yields.
 
-After collecting part-plans from children, synthesize before declaring done: resolve file ownership conflicts (two sub-plans naming the same file means you decide the sequence), align naming across all parts, fill integration gaps at domain boundaries, and ensure the task table in the index accurately reflects dependencies exposed only by reading all sub-plans together.
+Each part-plan follows [[plan/guide]]. The index links every part-plan and carries a lane table with each plan, its outcome, dependencies, ownership boundary, and proof gate. It also maps every acceptance criterion to the responsible part-plan or a final cross-lane runtime gate. Unit detail stays in the part-plans.
+
+After the part-plans land, synthesize the index before declaring done. Resolve file and symbol ownership conflicts, align names and phase gates, fill integration gaps, confirm the dependency graph permits every claimed parallel lane, and prove that part-plan and cross-lane gates cover the full approved outcome. Do not duplicate part-plan units in the index.

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

@@ -1,12 +1,20 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { listMemoryDocs } from "../../../commands/memory/list.js";
 import { createMemoryDocSnapshot, readMemoryDocContent } from "../../../commands/memory/read.js";
+import { parseSubstrateDoc } from "../../../core/substrate/schema.js";
 import {
   expandDeterministicCommand,
   type DeterministicCommandExpansion,
 } from "../../../core/runtime/command-expansion.js";
 import { expandShellBlocks, hasShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from "../../../core/runtime/shell-expansion.js";
 import type { ChatCommandMetadata } from "../../../core/runtime/command-surface.js";
+import {
+  exposureTarget,
+  loadContextExposureState,
+  mergeContextExposureState,
+  registerDocumentExposure,
+  saveContextExposureState,
+  sharedContextExposureState,
+} from "../../../core/substrate/injected-store.js";
 import { piShellRunner } from "./pi-shell-runner.js";
 
 // ---------------------------------------------------------------------------
@@ -16,57 +24,50 @@ import { piShellRunner } from "./pi-shell-runner.js";
 // the doc body (plus the user's free-text args) as a normal turn instead of
 // requiring a separate skill-invocation mechanism.
 //
-// Discovery uses the in-process `memory list` inventory and its source
-// snapshot, which already resolve the substrate's scope precedence (project
-// stack > profile > user > builtin). This file does not walk memory/
-// directories or reimplement scope resolution. `list`'s items are
-// scope-precedence sorted (see `scopeRank` in crouter's memory/shared.ts), so
-// first-occurrence-wins per doc name reproduces the resolver's identity
-// precedence for free. The inventory carries parsed `slash` flags and resolved
-// paths for command bodies.
+// Discovery uses one in-process target snapshot for both listing and body
+// resolution. The snapshot already resolves exact canonical identities in
+// source precedence; this file does not walk memory directories or reimplement
+// scope resolution.
 // ---------------------------------------------------------------------------
 
 interface MemoryListItem {
   name: string;
-  path: string;
   short_form: string;
   slash: boolean;
 }
 
 export interface SlashDoc {
-  /** Path-derived doc name, e.g. "research-alpha" or "taste/foo" — what
-   *  `crtr memory read` resolves. */
+  /** Canonical name resolved by `crtr memory read`. */
   name: string;
-  /** `name` with `/` -> `:` — the registered command name (a flat name is
-   *  unchanged). */
+  /** Canonical `/` segments rendered as ordinary `:` command segments. */
   commandName: string;
   /** The memory document's short-form description, shown in the slash menu. */
   description: string;
 }
 
-// `memory list` already chose each winning document. Keep its canonical body
-// for disclosure classification and its path for the existing execution read.
+// Keep each canonical winner's body and path for disclosure classification and
+// the existing execution read.
 const resolvedMemoryDocs = new Map<string, { path: string; canonicalBody: string }>();
 
 async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
   const snapshot = createMemoryDocSnapshot();
-  const items = listMemoryDocs(undefined, undefined, true, snapshot.docs).map((doc) => ({
-    name: doc.name,
-    path: doc.path,
-    short_form: doc.shortForm,
-    slash: doc.slash,
-  }));
-
-  // Slash eligibility follows the list identity, while the body follows the
-  // separate `memory read <name>` resolver contract (including direct-path
-  // precedence). Resolve all eligible names against one source snapshot.
+  const items: MemoryListItem[] = [];
   const seen = new Set<string>();
-  const names = items.flatMap((item) => {
-    if (seen.has(item.name)) return [];
-    seen.add(item.name);
-    return item.slash === true ? [item.name] : [];
-  });
-  const resolved = snapshot.resolve(names);
+  for (const memoryDoc of snapshot.docs) {
+    if (seen.has(memoryDoc.name)) continue;
+    seen.add(memoryDoc.name);
+    const doc = parseSubstrateDoc(memoryDoc);
+    if (doc === null) continue;
+    items.push({
+      name: memoryDoc.name,
+      short_form: doc.shortForm,
+      slash: doc.slash,
+    });
+  }
+
+  // Resolve eligible canonical names against the same target snapshot that
+  // supplied the list rows.
+  const resolved = snapshot.resolve(items.filter((item) => item.slash).map((item) => item.name));
   resolvedMemoryDocs.clear();
   for (const [name, doc] of resolved) {
     resolvedMemoryDocs.set(name, { path: doc.path, canonicalBody: doc.body });
@@ -74,27 +75,36 @@ async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
   return items;
 }
 
-function defaultReadMemoryDoc(name: string): { canonicalBody: string; executionBody: string } {
+function defaultReadMemoryDoc(name: string): { path: string; canonicalBody: string; executionBody: string } {
   const resolved = resolvedMemoryDocs.get(name);
   if (resolved === undefined) throw new Error(`memory slash document was not resolved: ${name}`);
   return {
+    path: resolved.path,
     canonicalBody: resolved.canonicalBody,
     executionBody: readMemoryDocContent(resolved.path),
   };
 }
 
+function registerSlashExposure(path: string, body: string): void {
+  const nodeId = process.env["CRTR_NODE_ID"];
+  if (nodeId === undefined || nodeId === "") return;
+  const state = sharedContextExposureState(nodeId);
+  mergeContextExposureState(state, loadContextExposureState(nodeId));
+  registerDocumentExposure(exposureTarget(state, "transcript"), path, body, "content");
+  saveContextExposureState(nodeId, state);
+}
+
 function hasNodeRelativeExpansion(body: string): boolean {
   return body.includes("$CRTR_CONTEXT_DIR") || body.includes("$CRTR_NODE_ID");
 }
 
-/** `/`-joined path-derived doc name -> the registered slash-command name. */
+/** Canonical name -> the registered slash-command name. */
 export function slashCommandName(docName: string): string {
   return docName.split("/").join(":");
 }
 
-/** Every `slash: true` memory doc, scope-precedence-deduped by name (see
- *  module header). Directory INDEX entries never register as commands. A doc
- *  without `slash` (or `slash: false`) is silently excluded. */
+/** Every `slash: true` canonical winner, scope-precedence-deduped by name. A
+ *  doc without `slash` (or `slash: false`) is silently excluded. */
 export async function discoverSlashDocs(): Promise<SlashDoc[]> {
   let items: MemoryListItem[];
   try {
@@ -118,6 +128,7 @@ export default async function (pi: ExtensionAPI) {
   const docs = await discoverSlashDocs();
   for (const doc of docs) {
     let expansion: DeterministicCommandExpansion | undefined;
+    let exposure: { path: string; body: string } | undefined;
     let discloseExpansion = false;
     let loadError: unknown;
     try {
@@ -127,6 +138,7 @@ export default async function (pi: ExtensionAPI) {
         commandName: doc.commandName,
         body: body.executionBody,
       };
+      exposure = { path: body.path, body: body.canonicalBody };
       discloseExpansion = !hasNodeRelativeExpansion(body.canonicalBody);
     } catch (err) {
       loadError = err;
@@ -174,6 +186,7 @@ export default async function (pi: ExtensionAPI) {
           },
           { triggerTurn: true },
         );
+        if (exposure !== undefined) registerSlashExposure(exposure.path, exposure.body);
       },
     } as Parameters<ExtensionAPI["registerCommand"]>[1] & { expansion?: DeterministicCommandExpansion } & ChatCommandMetadata);
   }

package/dist/clients/attach/__tests__/pane-tag-successor.test.js

@@ -0,0 +1,56 @@
+// Regression: a viewer pane lost `@crtr_node` and `@crtr_attach` while a live
+// viewer was running in it, so `surface reload` and viewer focus refused the
+// pane (`no_viewer`, exit 2) until it was re-tagged by hand.
+//
+// tmux `respawn-pane -k` SIGHUPs the outgoing viewer and starts the replacement
+// ~50ms later without waiting for it. Measured on this machine: SIGHUP at t+0,
+// successor running at t+49ms. An outgoing viewer whose event loop was busy
+// when the signal landed therefore ran its teardown AFTER the successor had
+// claimed the pane, and cleared the successor's tags.
+// Run with: node --conditions=crtr-src --import tsx/esm --test 'src/clients/attach/__tests__/pane-tag-successor.test.ts'
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createPaneTag } from '../session/pane-tag.js';
+const PANE = '%474';
+const NODE = '3zl47w7d-mt0chixr-cd2fc29b';
+function fakeTmux() {
+    const options = new Map();
+    let stampCounter = 1_000;
+    const io = (pid) => ({
+        readOption: (_pane, name) => options.get(name) ?? '',
+        writeOption: (_pane, name, value) => { options.set(name, value); },
+        stampAsync: () => { options.set('@crtr_viewer_at', String(++stampCounter)); },
+        currentPane: () => PANE,
+        ownerId: () => pid,
+    });
+    return { options, io };
+}
+test('a late teardown does not clear the tags of the viewer that replaced it', () => {
+    const { options, io } = fakeTmux();
+    const outgoing = createPaneTag(false, NODE, io('4001'));
+    outgoing.set();
+    // The replacement claims the pane while the outgoing viewer is still busy.
+    const successor = createPaneTag(false, NODE, io('4002'));
+    successor.set();
+    outgoing.clear();
+    assert.equal(options.get('@crtr_node'), NODE, 'live viewer kept its node tag');
+    assert.equal(options.get('@crtr_attach'), '1', 'live viewer kept its attach tag');
+    assert.notEqual(options.get('@crtr_viewer_at'), '', 'live viewer kept its stamp');
+});
+test('an ordinary teardown still clears the tags it owns', () => {
+    const { options, io } = fakeTmux();
+    const viewer = createPaneTag(false, NODE, io('4001'));
+    viewer.set();
+    viewer.clear();
+    assert.equal(options.get('@crtr_node'), '');
+    assert.equal(options.get('@crtr_attach'), '');
+    assert.equal(options.get('@crtr_viewer_at'), '');
+});
+test('a focus refresh does not cost a viewer its own claim', () => {
+    const { options, io } = fakeTmux();
+    const viewer = createPaneTag(false, NODE, io('4001'));
+    viewer.set();
+    viewer.stamp(); // focus refresh
+    viewer.clear();
+    assert.equal(options.get('@crtr_node'), '', 'the pane it still owns is cleared');
+});

package/dist/clients/attach/__tests__/profile-files.test.js

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { relatedNodeDirs } from '../session/profile-files.js';
+test('relatedNodeDirs includes a node family but not unrelated nodes', () => {
+    const nodes = [
+        { node_id: 'root', cwd: '/work/root', parent: null },
+        { node_id: 'parent', cwd: '/work/parent', parent: 'root' },
+        { node_id: 'current', cwd: '/work/current', parent: 'parent' },
+        { node_id: 'child', cwd: '/work/child', parent: 'current' },
+        { node_id: 'grandchild', cwd: '/work/grandchild', parent: 'child' },
+        { node_id: 'sibling', cwd: '/work/sibling', parent: 'parent' },
+        { node_id: 'unrelated', cwd: '/work/unrelated', parent: null },
+    ];
+    assert.deepEqual(relatedNodeDirs(nodes, 'current'), [
+        '/work/root',
+        '/work/parent',
+        '/work/current',
+        '/work/child',
+        '/work/grandchild',
+    ]);
+});

package/dist/clients/attach/chrome/inbox-strip.js

@@ -91,16 +91,20 @@ export function createInboxStrip(s, hooks) {
         // Same pending merge the inbox surface does — inbox-projected tickets plus
         // reply-bearing no-inbox pages — but for every subtree node, then scoped to
         // tickets whose origin is in the subtree.
+        // ONE page-history walk for the whole subtree, filtered by origin here.
+        // Calling `scanPageHistory(id)` per node re-walked every ticket directory
+        // once per subtree node — the same O(all tickets) scan repeated N times for
+        // a result that is just the union over subtree origins.
         const merged = new Map();
         for (const item of scanInbox())
             merged.set(item.dir, item);
-        for (const id of nodes.keys()) {
-            for (const page of scanPageHistory(id)) {
-                if (page.state !== 'pending' || !page.awaitsResponse || page.inbox)
-                    continue;
-                if (!merged.has(page.dir))
-                    merged.set(page.dir, page);
-            }
+        for (const page of scanPageHistory()) {
+            if (page.source.nodeId === undefined || !nodes.has(page.source.nodeId))
+                continue;
+            if (page.state !== 'pending' || !page.awaitsResponse || page.inbox)
+                continue;
+            if (!merged.has(page.dir))
+                merged.set(page.dir, page);
         }
         tickets = [...merged.values()]
             .filter((t) => t.source.nodeId !== undefined && nodes.has(t.source.nodeId))

package/dist/clients/attach/session/pane-tag.d.ts

@@ -5,13 +5,39 @@
  *  Split into a claim + a clear because ordering matters: a remote relay's "no
  *  node"/"no running broker" close can still throw AFTER the socket is up, so
  *  the tag is claimed only past that checkpoint — while `clear()` must be safe
- *  to call from a teardown that runs before it was ever claimed. */
-export declare function createPaneTag(remote: boolean, nodeId: string): {
+ *  to call from a teardown that runs before it was ever claimed.
+ *
+ *  `clear()` also has to survive a SUCCESSOR already owning the pane. tmux
+ *  `respawn-pane -k` only SIGHUPs the old viewer — it does not wait for it, and
+ *  the replacement is running ~50ms later. A departing viewer whose event loop
+ *  was busy when the signal arrived therefore runs its teardown after the
+ *  replacement has claimed the pane, and an unconditional clear then wipes the
+ *  LIVE viewer's identity: `nodeInPane()` returns nothing, so `surface reload`
+ *  and viewer focus refuse the pane until someone re-tags it by hand. So the
+ *  clear is conditional on still owning the pane, decided by `@crtr_viewer_pid`:
+ *  a pane carrying someone else's pid has a successor, and its tags are not
+ *  ours to remove. Skipping leaves at worst a stale tag on a dead pane, which
+ *  `liveViewerPanes` and `surface reload` already validate against the live
+ *  process; wiping a live viewer's tag has no such defense. */
+/** The tmux reads and writes the tag lifecycle makes, injectable so the
+ *  successor race is testable without a live tmux server. */
+export interface PaneTagIo {
+    readOption: (pane: string, name: string) => string | undefined;
+    writeOption: (pane: string, name: string, value: string) => void;
+    stampAsync: (pane: string) => void;
+    currentPane: () => string | undefined;
+    /** This viewer process's identity — the pid, unique per viewer by construction. */
+    ownerId: () => string;
+}
+export declare function createPaneTag(remote: boolean, nodeId: string, io?: PaneTagIo): {
     set: () => void;
     stamp: () => void;
     clear: () => void;
     pane: () => string | undefined;
 };
+/** Which viewer process owns this pane's tags. Read only by `clear()`, so a
+ *  departing viewer never removes a successor's identity. */
+export declare const VIEWER_OWNER_OPTION = "@crtr_viewer_pid";
 export declare function tagAttachPane(remote: boolean, pane: string | undefined, nodeId: string, setOpt?: (pane: string, name: string, value: string) => void): void;
 export declare function untagAttachPane(remote: boolean, pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;
 export declare function tagAttachViewerPane(pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;

package/dist/clients/attach/session/pane-tag.js

@@ -5,50 +5,76 @@
 // local id) from that pane. `@crtr_attach` carries no identity: every local or
 // remote attach viewer sets it so tmux can conditionally forward opted-in root
 // gestures into whichever attach pane currently has focus.
-import { currentTmux, setPaneOption, stampViewerPaneAsync, VIEWER_STAMP_OPTION, } from '../../../core/runtime/placement-tmux.js';
-/** The tag's lifecycle for one viewer: `set()` once the startup checkpoint has
- *  cleared, `clear()` on teardown so a stray tag can't outlive the pane.
- *  `pane()` is the id teardown reports as this viewer's home.
- *
- *  Split into a claim + a clear because ordering matters: a remote relay's "no
- *  node"/"no running broker" close can still throw AFTER the socket is up, so
- *  the tag is claimed only past that checkpoint — while `clear()` must be safe
- *  to call from a teardown that runs before it was ever claimed. */
-export function createPaneTag(remote, nodeId) {
+import { currentTmux, getPaneOption, setPaneOption, stampViewerPaneAsync, VIEWER_STAMP_OPTION, } from '../../../core/runtime/placement-tmux.js';
+const realPaneTagIo = {
+    readOption: getPaneOption,
+    writeOption: (pane, name, value) => { setPaneOption(pane, name, value); },
+    stampAsync: stampViewerPaneAsync,
+    currentPane: () => process.env['TMUX_PANE'] ?? currentTmux()?.pane,
+    ownerId: () => String(process.pid),
+};
+export function createPaneTag(remote, nodeId, io = realPaneTagIo) {
     let pane;
+    const ownerPid = io.ownerId();
+    /** False once another viewer's pid is on the pane. An unclaimed pane (no pid
+     *  recorded — a viewer that never reached `set()`, or one from a generation
+     *  that predates this option) keeps the old unconditional behavior. */
+    const stillOwnsPane = () => {
+        if (pane === undefined || pane === '')
+            return true;
+        const claimed = io.readOption(pane, VIEWER_OWNER_OPTION);
+        if (claimed === undefined || claimed === '')
+            return true;
+        return claimed === ownerPid;
+    };
     return {
         set: () => {
-            pane = process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-            tagAttachPane(remote, pane, nodeId);
-            tagAttachViewerPane(pane);
-            stampAttachPane(remote, pane);
+            pane = io.currentPane();
+            claimAttachPane(pane, ownerPid, io.writeOption);
+            tagAttachPane(remote, pane, nodeId, io.writeOption);
+            tagAttachViewerPane(pane, io.writeOption);
+            stampAttachPane(remote, pane, io.writeOption);
         },
         stamp: () => {
             if (remote || pane === undefined || pane === '')
                 return;
-            stampViewerPaneAsync(pane);
+            io.stampAsync(pane);
         },
         clear: () => {
-            untagAttachPane(remote, pane);
-            untagAttachViewerPane(pane);
-            unstampAttachPane(remote, pane);
+            if (!stillOwnsPane())
+                return;
+            untagAttachPane(remote, pane, io.writeOption);
+            untagAttachViewerPane(pane, io.writeOption);
+            unstampAttachPane(remote, pane, io.writeOption);
+            claimAttachPane(pane, '', io.writeOption);
         },
         pane: () => pane,
     };
 }
-function stampAttachPane(remote, pane) {
+/** Which viewer process owns this pane's tags. Read only by `clear()`, so a
+ *  departing viewer never removes a successor's identity. */
+export const VIEWER_OWNER_OPTION = '@crtr_viewer_pid';
+function claimAttachPane(pane, ownerPid, setOpt) {
+    if (pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, VIEWER_OWNER_OPTION, ownerPid);
+    }
+    catch { /* best-effort */ }
+}
+function stampAttachPane(remote, pane, setOpt) {
     if (remote || pane === undefined || pane === '')
         return;
     try {
-        setPaneOption(pane, VIEWER_STAMP_OPTION, String(Date.now()));
+        setOpt(pane, VIEWER_STAMP_OPTION, String(Date.now()));
     }
     catch { /* best-effort */ }
 }
-function unstampAttachPane(remote, pane) {
+function unstampAttachPane(remote, pane, setOpt = setPaneOption) {
     if (remote || pane === undefined || pane === '')
         return;
     try {
-        setPaneOption(pane, VIEWER_STAMP_OPTION, '');
+        setOpt(pane, VIEWER_STAMP_OPTION, '');
     }
     catch { /* best-effort */ }
 }

package/dist/clients/attach/session/profile-files.d.ts

@@ -1,8 +1,14 @@
+import type { NodeRow } from '../../../core/canvas/types.js';
 interface ProfileFileSearchOptions {
     cwd: string;
+    nodeDirs: readonly string[];
     profileId: string | null;
     fdPath: string | null;
     onNotice: (message: string) => void;
 }
+/** Return the working directories for this node, its complete parent chain,
+ *  and its full descendant subtree. The `parent` hierarchy, rather than the
+ *  subscription graph, is the user-visible child/parent relationship. */
+export declare function relatedNodeDirs(nodes: readonly Pick<NodeRow, 'node_id' | 'cwd' | 'parent'>[], nodeId: string): string[];
 export declare function launchProfileFileSearch(opts: ProfileFileSearchOptions): void;
 export {};

package/dist/clients/attach/session/profile-files.js

@@ -1,11 +1,11 @@
-// session/profile-files.ts — fuzzy file search across a node's local profile.
+// session/profile-files.ts — fuzzy file search across a node's working family and local profile.
 //
-// The popup searches the current workspace, every project named by the node's
-// profile manifest, and the profile's own memory store. Ancestor
-// `.crouter/memory/` stores are added with ignore rules disabled, so project
-// memory remains findable even when a parent ignore file hides `.crouter/`.
-// fzf owns selection and nvim owns viewing; the attach viewer only resolves the
-// relevant roots and wires the two popups.
+// The popup searches the current workspace, every ancestor and descendant
+// node's workspace, every project named by the node's profile manifest, and the
+// profile's own memory store. Ancestor `.crouter/memory/` stores are added with
+// ignore rules disabled, so project memory remains findable even when a parent
+// ignore file hides `.crouter/`. fzf owns matching and selection and nvim owns
+// viewing; the attach viewer resolves the related nodes and wires the two popups.
 import { constants, accessSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { delimiter, dirname, join, resolve, sep } from 'node:path';
@@ -13,6 +13,31 @@ import { execFile, spawnSync } from 'node:child_process';
 import { loadProfileManifest, profileMemoryDir } from '../../../core/profiles/manifest.js';
 import { shellQuote } from '../../../core/runtime/placement-tmux.js';
 import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+/** Return the working directories for this node, its complete parent chain,
+ *  and its full descendant subtree. The `parent` hierarchy, rather than the
+ *  subscription graph, is the user-visible child/parent relationship. */
+export function relatedNodeDirs(nodes, nodeId) {
+    const byId = new Map(nodes.map((node) => [node.node_id, node]));
+    const included = new Set([nodeId]);
+    for (let current = byId.get(nodeId); current?.parent !== null && current?.parent !== undefined;) {
+        const parentId = current.parent;
+        if (included.has(parentId))
+            break;
+        included.add(parentId);
+        current = byId.get(parentId);
+    }
+    const pending = [nodeId];
+    while (pending.length > 0) {
+        const parentId = pending.pop();
+        for (const child of nodes) {
+            if (child.parent !== parentId || included.has(child.node_id))
+                continue;
+            included.add(child.node_id);
+            pending.push(child.node_id);
+        }
+    }
+    return nodes.filter((node) => included.has(node.node_id)).map((node) => node.cwd);
+}
 function isDirectory(path) {
     try {
         return statSync(path).isDirectory();
@@ -93,6 +118,9 @@ function ancestorMemoryDirs(pointers) {
     }
     return dedupeExistingDirs(found);
 }
+/** Columns fzf keeps to the right of the matched substring when it scrolls a
+ *  long path into view. Wide enough to show the rest of the filename. */
+const HSCROLL_OFF = 20;
 function selectionPath(path) {
     try {
         const bytes = readFileSync(path);
@@ -122,7 +150,7 @@ export function launchProfileFileSearch(opts) {
         return;
     }
     const profile = profileSearchRoots(opts.profileId);
-    const pointers = dedupeExistingDirs([opts.cwd, ...profile.projects]);
+    const pointers = dedupeExistingDirs([opts.cwd, ...opts.nodeDirs, ...profile.projects]);
     if (pointers.length === 0) {
         opts.onNotice('No profile file-search directories exist');
         return;
@@ -134,11 +162,16 @@ export function launchProfileFileSearch(opts) {
     ]);
     const tempDir = mkdtempSync(join(tmpdir(), 'crtr-profile-files-'));
     const selected = join(tempDir, 'selection');
+    const candidates = join(tempDir, 'candidates');
     const scans = [
-        ...roots.map((root) => `${shellQuote(fd)} --type f --hidden --exclude .git --exclude ${shellQuote('**/.crouter/memory/**')} --print0 . ${shellQuote(root)}`),
-        ...memoryDirs.map((memory) => `${shellQuote(fd)} --type f --hidden --exclude .git --no-ignore --print0 . ${shellQuote(memory)}`),
+        ...roots.map((root) => `${shellQuote(fd)} --type f --hidden --exclude .git --exclude ${shellQuote('**/.crouter/memory/**')} . ${shellQuote(root)}`),
+        ...memoryDirs.map((memory) => `${shellQuote(fd)} --type f --hidden --exclude .git --no-ignore . ${shellQuote(memory)}`),
     ];
-    const command = `{ ${scans.map((scan) => `${scan} &`).join(' ')} wait; } | ${shellQuote(fzf)} --read0 --print0 --preview ${shellQuote('head -100 -- {}')} > ${shellQuote(selected)}`;
+    // Every line is the whole path and nothing else, so fzf matches, ranks, and
+    // horizontally scrolls against the same text — a hidden field would be
+    // unsearchable, and a display slice would silently narrow the query.
+    const yankPath = 'printf \'%s\' {} | { if command -v pbcopy >/dev/null 2>&1; then pbcopy; elif command -v wl-copy >/dev/null 2>&1; then wl-copy; elif command -v xclip >/dev/null 2>&1; then xclip -selection clipboard; else cat >/dev/null; fi; }; printf \'%s\' {} | tmux load-buffer -w -';
+    const command = `{ ${scans.map((scan) => `${scan} &`).join(' ')} wait; } > ${shellQuote(candidates)} && ${shellQuote(fzf)} --print0 --scheme=path --hscroll-off=${HSCROLL_OFF} --header ${shellQuote('fuzzy path • ctrl-y yank file path')} --bind ${shellQuote(`ctrl-y:execute-silent(${yankPath})`)} --preview ${shellQuote('head -100 -- {}')} < ${shellQuote(candidates)} > ${shellQuote(selected)}`;
     try {
         execFile('tmux', ['display-popup', '-E', '-T', ' profile files ', '-w', '80%', '-h', '60%', ...surfaceTmuxStyleArgs(), command], () => {
             const file = selectionPath(selected);

package/dist/clients/attach/slash/dispatch.js

@@ -396,11 +396,8 @@ function dispatchCanvasCommand(name, arg, ctx) {
             return true;
     }
 }
-/** `/promote [kind]` — the live promote path (the broker is headless, so promotion
- *  has no in-engine command). Shells `crtr node promote --json` for
- *  this node (out-of-process), notifies the result, then triggers a turn so the
- *  persona injector steers in the new-role guidance at the turn boundary — exactly
- *  as the node would by running the command itself. */
+/** `/promote [kind]` shells the out-of-process mutation, reports it, then
+ * triggers a turn whose provider gate appends the pending transition context. */
 function promoteNode(arg, ctx) {
     const nodeId = nodeIdFor(ctx).trim();
     if (nodeId === '') {
@@ -446,8 +443,8 @@ function promoteNode(arg, ctx) {
         }
         const rmPath = (result.roadmap_path ?? '').trim();
         ctx.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`);
-        // Trigger a turn so the persona injector (canvas-stophook turn_end) fires and
-        // delivers the new-role guidance — the viewer's only turn-trigger is `prompt`.
+        // Trigger a turn so the pending transition lands before the promoted
+        // node's response; the viewer's only turn trigger is `prompt`.
         ctx.send({
             type: 'prompt',
             text: 'You have just been promoted to an orchestrator. Your new-role guidance is arriving — read it, author your roadmap, and start delegating.',