@north-light/crouter 0.3.227 → 0.3.229

package/dist/api/client.d.ts

@@ -21,7 +21,7 @@ import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, I
 import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { CloseWorktreeResultDTO } from './dto/worktree.js';
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
 export interface CrtrClientOptions {
     /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
     socketPath?: string;
@@ -101,7 +101,7 @@ export declare class CrtrClient {
     commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
     brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;
     commitBrokerGeneratedName(id: string, req: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
-    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<void>;
+    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<BrokerPersonaAckResultDTO>;
     closeNode(id: string, req?: CloseRequest): Promise<CloseResultDTO>;
     recycleNode(id: string): Promise<NodeDetailDTO>;
     demoteNode(id: string): Promise<NodeDetailDTO>;
@@ -164,9 +164,9 @@ 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. */
+    /** Resolve an exact canonical `[[name]]` memory-document link to the winning
+     *  document's physical origin for the given node — the node's own precedence
+     *  chain, not this process's. Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
     /** Create-or-return by name. Supplied `projects` are shape-checked even when
      *  the profile already exists; their directories are only required to exist

package/dist/api/client.js

@@ -290,9 +290,9 @@ export class CrtrClient {
         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. */
+    /** Resolve an exact canonical `[[name]]` memory-document link to the winning
+     *  document's physical origin for the given node — 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 }));
     }

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

@@ -90,7 +90,10 @@ export interface BrokerExtensionNodeDTO {
         target_file: string;
     } | null;
     intent: ExitIntentDTO;
+    /** `kind` is absent on rows written before kind joined the drift key; a read
+     *  resolves it to the node's current kind. */
     persona_ack?: {
+        kind?: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
@@ -145,11 +148,16 @@ export interface BrokerGeneratedNameResultDTO {
 }
 export interface BrokerPersonaAckRequest {
     from: {
+        kind: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
     to: {
+        kind: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
 }
+export interface BrokerPersonaAckResultDTO {
+    applied: boolean;
+}

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

@@ -1,16 +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. */
+/** `GET /v1/memory/resolve?name=<name>&node=<id>` result. Resolution runs the
+ *  node's own precedence chain (its context store, its project stack, its
+ *  profile, user, builtin) and returns the winner for the exact canonical name. */
 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. */
+    /** The winner's canonical identity for the exact resolved query. */
     name: string;
     /** Which store it came from: node | project | profile | user | builtin. */
     scope: string;
     /** Absolute path to the `.md` file. */
     path: string;
+    /** Absolute path to the physical memory store root. */
+    store_root: string;
+    /** Store-relative markdown path of the winning document. */
+    physical_relative_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

@@ -1,6 +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.
+// holding a canonical `[[name]]` link out of a node's transcript gets the
+// winning document's canonical identity and physical origin.
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 export {};

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

@@ -3,7 +3,7 @@ kind: preference
 when-and-why-to-read: When a node runs in base mode, this preference should be read so bounded work completes hands-on instead of recursing through a chain of delegates.
 gate: {mode: base}
 rationale: >-
-  A base security reviewer handed its entire assignment to another base security reviewer, which repeated the move through a 35-node chain in under five minutes. The universal prompt had said to delegate any self-contained work while no base-mode layer told sub-kinds to work hands-on; exact sub-kind gating also meant plan/reviewers/security did not inherit plan/00-base.
+  A base security reviewer handed its entire assignment to another base security reviewer, which repeated the move through a 35-node chain in under five minutes. The universal prompt had said to delegate any self-contained work while no base-mode layer told sub-kinds to work hands-on; exact sub-kind gating also meant the reviewer did not inherit its parent kind's base layer.
 
   The scout section exists because the kernel's "understand before you delegate" line is orchestrator-gated, so base workers had no counterweight to mapping unfamiliar code in their own window: they spent a strong-model context on read-only exploration and yielded before the real work. Explore defaults to a light tier, which is the mechanism the section leans on.
 surfaces:

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

@@ -28,11 +28,11 @@ Choose the narrowest durable scope that reaches every future conversation where
 
 Infer the scope from the request and current workspace. Ask through `crtr human send` only when more than one scope is genuinely plausible, and settle scope before writing anything. Never use node scope for an ongoing listener.
 
-Search the chosen scope before creating. If `insights/<topic>` already represents the same domain, refine that listener rather than creating an overlapping directory.
+Search the chosen scope before creating. Use `<namespace>/insights/<topic>` for project scope and `insights/<topic>` for profile or user scope; if that canonical address already represents the same domain, refine that listener rather than creating an overlapping directory.
 
 ## Create the listener
 
-Run `crtr memory write -h`, then create `insights/<topic>/INDEX.md` at the chosen scope as a preference surfaced `{on: boot, at: preview}`.
+Run `crtr memory write -h`, then create the directory document at the chosen scope under its canonical address: `<namespace>/insights/<topic>` for project scope and `insights/<topic>` for profile or user scope, as a preference surfaced `{on: boot, at: preview}`. Its physical front door remains `insights/<topic>/INDEX.md`.
 
 Its routing line must name the actual domain trigger: when user-supplied information, a correction, or a user response relates to this domain, read the preference because recognizing the underlying principle preserves knowledge future decisions can use.
 
@@ -52,7 +52,7 @@ When `--active` is present, do not stop after creating the listener. After initi
 
 ### 1. Create the listener first
 
-Follow the passive mode steps above through "Initialization is complete." The listener INDEX must exist before spawning the explorer.
+Follow the passive mode steps above through "Initialization is complete." The listener directory document must exist before spawning the explorer.
 
 ### 2. Spawn the explorer child
 
@@ -81,8 +81,8 @@ When the explorer reports, share its claims with the user. For each claim, ask:
 - 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.
+For each user response, use [[insights/capture]] to extract and review the insight. Apply approved insights directly to the listener directory document'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.
+Once claims have been surfaced and user guidance has generated approved insights, report that active initialization is complete. The listener directory document now passively captures this domain as new user material emerges.

package/dist/builtin-memory/internal/INDEX.md

@@ -25,4 +25,4 @@ Adjacent, outside this dir: authoring memory documents (kind, surfaces routing,
 
 Briefly: **plugins** package docs and commands, with command execution selected by `plugin.json.transport` (`exec` for a trusted local executable or `http` for a fetched remote REST manifest); **marketplaces** index and distribute plugins. Plugin commands enter the **external-command** fallthrough, leaving the core fast-path untouched.
 
-The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.
+The individual files surface at their canonical names (open the one the situation calls for); this directory document surfaces at `internal` at `preview`, and `crtr memory read internal` returns its body followed by the directory's immediate listing.

package/dist/builtin-memory/internal/agent-shaping.md

@@ -23,7 +23,7 @@ A fifth axis, **lifecycle** (`terminal` vs `resident`), is orthogonal too but be
 
 ## Kinds — role, model tier, and tools
 
-A kind is a **persona** (gated memory docs at `kinds/<kind>/00-base.md` and `01-orchestrator.md`, gated `{kind, mode}` so exactly the node's role prose splices into its boot context) plus a **`KindConfig`** in the launch registry (its one-line `whenToUse`, a default model tier, the tools/extensions it gets, and which sub-personas it may spawn). Set it at spawn with `crtr node new --kind`, or change it live with `crtr node config --kind` / `crtr node promote --kind`.
+A kind starts with a **`KindConfig`** in the launch registry: its one-line `whenToUse`, default model tier, tools and extensions, and which sub-personas it may spawn. Core or an enabled plugin can add role guidance with ordinary memory documents gated by `{kind, mode}`. Set the kind at spawn with `crtr node new --kind`, or change it live with `crtr node config --kind` / `crtr node promote --kind`.
 
 **Why kinds exist at all.** Two payoffs a per-task instruction can't buy. First, **model-tier economics ride the kind boundary**: `explore` defaults to a fast/cheap model (right for mapping and summarization, wrong for judgment); `advisor` defaults to the slow, expensive think-y tier (right for debugging and tradeoffs). Fencing the tier into the kind is what stops an orchestrator from delegating debugging to a cheap explore scout. Second, a kind is **standing role discipline** that survives across every task of that type — the reviewer's neutral priming, the developer's done-bar, the planner's decision-resolution — rather than prose you must restate and that erodes each spawn.
 
@@ -31,20 +31,20 @@ A kind is a **persona** (gated memory docs at `kinds/<kind>/00-base.md` and `01-
 
 | kind | what it's for | reach for it when |
 |---|---|---|
-| **general** | catch-all worker for work that fits no specialist kind | nothing more specific fits. Its persona optimizes for self-agency — reshaping its own kind/mode/config mid-flight — because it's the default spawn, not custom-shaped for the task |
-| **explore** | read-only orientation and code-path mapping, `file:line` evidence, facts without opinion, effort scaled to requested depth | you need to understand unfamiliar code or architecture. **Never** for diagnosis — anything about why something is broken or misbehaving is advisor |
-| **advisor** | diagnosis, debugging, tradeoff analysis, engineering second opinions — reason from evidence, recommend the next move | you need to find out what is going wrong, or want judgment on a consequential call. The reciprocal of explore: expensive think-y tier, fenced here so judgment doesn't leak onto a cheap scout |
-| **spec** | discover-then-write *what to build* — behavior, non-goals, interfaces, edge cases, testable acceptance criteria | the requirement itself is unsettled and needs enumerating (which pages exist, which error cases) before anyone designs |
-| **design** | architect *how it should be built* — cross-service, high-level decisions (schema, patterns, performance), worked out interactively, deliberately not the most obvious solution | the *how* has real architectural weight. Distinct from plan: design decides the shape; plan sequences an already-decided shape |
-| **plan** | decompose an approved spec/design into concrete, phased, parallelizable steps with every decision resolved | you have a spec or design and need an executable breakdown a less-capable model can run without re-deciding. A plan 80% right costs more than no plan — pin every decision |
-| **developer** | implement a change and make it *genuinely work* against acceptance criteria, not merely compile | you're building the feature or fix. Green proves it ran, not that it's right — the persona carries the prove-it discipline and the build→review cycle |
-| **review** | critique code, a plan, or a spec once — deliver a complete, severity-rated verdict, **detect don't adjudicate** | substantive work needs one independent check. Use a *separate* node from the author — agents can't self-audit — and prime it neutrally ("review this", never "find what fails", which manufactures false positives) |
+| **general** | catch-all worker | no specialist role fits |
+| **explore** | read-only current-state and code-path mapping | you need evidence about unfamiliar code or architecture, not diagnosis or recommendations |
+| **advisor** | diagnosis, debugging, tradeoff analysis, and engineering second opinions | you need to explain a failure or judge a consequential call |
+| **spec** | define what outcome and behavior to build | the requirement itself is unsettled |
+| **design** | decide the structural shape of a solution | the implementation has consequential architectural choices |
+| **plan** | sequence implementation of an approved specification or design | the outcome and structure are settled but the build path is not |
+| **developer** | implement a change | you are building the feature or fix |
+| **review** | independently critique code or an artifact | substantive work needs a severity-rated verdict |
 
-The discriminators that get missed: **explore vs advisor** (mapping vs judgment — cheap vs expensive tier); **spec vs design** (what to build vs how to build it); **design vs plan** (decide the shape vs sequence a decided shape); **review is always a separate node from the implementer**. **Developer is the kind closest to "general with a mood"** — the first merge candidate if the roster ever shrinks.
+The discriminators that get missed are **explore vs advisor** (mapping vs judgment), **spec vs design** (what to build vs how it is structured), and **design vs plan** (decide the shape vs sequence a decided shape).
 
 ### Sub-kinds
 
-Specialist sub-personas hang off a parent kind — `plan/reviewers/*` (architecture-fit, code-smells, pattern-consistency, requirements-coverage, security) and `spec/requirements`. They aren't in the top-level `--kind` list but are valid by exact path (`crtr node new --kind plan/reviewers/security`). Use a sub-persona for one narrowly targeted assignment, not as a mandatory lens roster; discover the available roles with `crtr sys prompt-review --list --kind <kind>`.
+Specialist sub-personas hang off a parent kind. They are not in the top-level `--kind` list but are valid by exact registered path. Use one for a narrowly targeted assignment, not as a mandatory roster; discover the roles available from a kind with `crtr sys prompt-review --list --kind <kind>`. Core and plugins register sub-kinds through the same launch registry.
 
 ### Custom personas
 

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -13,4 +13,4 @@ The other internal/ docs explain the primitives one at a time; this dir shows th
 
 - **imessage-assistant** — an OpenClaw-style always-on assistant: resident root node with its own dir and persona, woken event-style by a launchd watcher via `node message send`, reading `chat.db` (with the attributedBody gotcha), replying via osascript, remembering people through project-scope memory.
 
-Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it.
+Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it. Read `internal/examples` for this overview and its immediate example listing; the physical front door remains `INDEX.md`, but `INDEX` is not part of the canonical address.

package/dist/builtin-memory/internal/memory-loading.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need to know why a memory doc did or didn't load — or are deciding how a new doc should surface — this reference should be read because it names the event, rung, gate, and ordering that produced the behavior, so you fix loading by turning the right dial instead of guessing at frontmatter.
-short-form: The complete load model — the five surface events, the rung ladder, gates, listings, transcript dedup, boot-render ordering, and store mounting/precedence.
+short-form: The complete load model — the five surface events, the rung ladder, gates, listings, context exposure, boot-render ordering, and store mounting/precedence.
 surfaces:
   - on: boot
     at: name
@@ -15,10 +15,10 @@ Every memory doc declares its own delivery in frontmatter `surfaces` entries; th
 
 A doc with no `surfaces` does exactly one thing: appears in its directory's listing. Everything beyond that is an explicit entry — `{on: <event>, match?, match-frontmatter?, gate?, at: <rung>}`. An entry's event constraints and optional node-config `gate` must both match; participating entries OR across and fold to their highest rung (`content` > `preview` > `name`), with no cross-entry deny precedence. Multiple entries per event are legal. The events:
 
-- **boot** — the catalog assembled into every node's system prompt at revive. No match; the entry's presence is the match.
+- **boot** — the frozen preference system snapshot and first-message knowledge catalog assembled when a context begins. No match; the entry's presence is the match.
 - **workspace-open** — first-message context when cwd/profile mounts the doc's project store. Project stores only.
 - **read** — a `read` tool call returned a matching file: path globs vs the file's absolute path and basename, `./`-anchored globs vs its path relative to the store's owning repo dir, `match-frontmatter` predicates over the read file's own YAML frontmatter.
-- **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's own name directory.
+- **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's canonical routing anchor (a collapsed directory document anchors at its own directory name).
 - **command** — a matching shell command ran: globs vs the whole command string, `*` crossing `/`. Delivery is post-execution — right for "you are now in this territory," never for "don't run this at all."
 
 Nothing positional fires from where a doc happens to sit on disk — only from its declared entries and its listing.
@@ -39,9 +39,9 @@ A document-level `gate` is the hard eligibility predicate over the node's own co
 
 ## Listings and dedup
 
-Reading a doc discloses where it sits: `crtr memory read <doc>` also renders, once per transcript, the listing of the doc's directory and each ancestor — one routing line per member doc, one bare name per subdirectory. `crtr memory read <dir>` (or a bare-dir `[[ref]]`) returns the listing itself; no doc answers for a directory. `unlisted: true` suppresses a doc from every listing. Store roots are never auto-listed — `crtr memory list` is the deliberate root browse.
+Reading a doc discloses where it sits: `crtr memory read <doc>` also renders, once per loaded context, the listing of the doc's directory and each ancestor — one routing line per member doc, one bare name per subdirectory. A directory document owns its canonical directory node, so `crtr memory read <dir>` (or a bare-dir `[[ref]]`) returns that document's body followed by the directory's immediate listing without repeating the document; a directory without a document returns its listing. `unlisted: true` suppresses a doc from every listing. Store roots are never auto-listed — `crtr memory list` is the deliberate root browse.
 
-Every delivery dedups per transcript keyed on (doc, rung), higher rungs piercing lower: a listing line is a preview-rank render, boot renders seed the set at their boot rung, and a content delivery silences everything after it.
+Every delivery registers its document or listing identity and rung in the loaded context's exposure ledger. System and transcript ranks max-fold, so a higher rung pierces a lower one while a content delivery silences later lower-rung deliveries. A strict resume preserves that ledger and the byte-stable preference snapshot; yield or another new-context boundary replaces them with exactly the new system and first-message snapshots.
 
 ## Store mounting and precedence
 
@@ -53,7 +53,7 @@ The maximum reaches those two events and nothing else. Read, memory-read, and co
 
 A workspace's front door is an ordinary doc carrying the entry pair `{on: workspace-open, at: content}` + `{on: read, match: "./**", at: content}` — the operating guide loads when that workspace mounts or its files are read, not in every boot catalog. `crtr memory lint` requires exactly one workspace-open content doc per profile-managed project store. Multiple mounted roots render broad-to-specific.
 
-A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, deduplicated against everything already in the transcript. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).
+A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, filtered against what the loaded context already contains. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).
 
 ## Ordering
 

package/dist/builtin-memory/internal/plugins.md

@@ -33,7 +33,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
 └── memory/
     ├── <name>.md                    # a kind:knowledge or kind:preference doc
     └── <area>/
-        ├── INDEX.md                 # optional — an ordinary doc; a bare-dir read answers with the listing
+        ├── INDEX.md                 # optional physical front door; its canonical address is the directory and read combines body + immediate listing
         └── <name>.md
 ```
 

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;