@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/profiles/default-binding.js

@@ -44,3 +44,27 @@ export function clearDefaultProfile(cwd) {
     else
         writeJson(bindingsPath(), value);
 }
+/** Every directory currently pinned to `profileId`, in deterministic order. */
+export function defaultProfileDirs(profileId) {
+    return Object.entries(bindings())
+        .filter(([, pinnedProfileId]) => pinnedProfileId === profileId)
+        .map(([dir]) => dir)
+        .sort();
+}
+/** Clear every per-directory default that names `profileId`. */
+export function clearDefaultProfileId(profileId) {
+    const value = bindings();
+    const cleared = Object.entries(value)
+        .filter(([, pinnedProfileId]) => pinnedProfileId === profileId)
+        .map(([dir]) => dir)
+        .sort();
+    if (cleared.length === 0)
+        return [];
+    for (const dir of cleared)
+        delete value[dir];
+    if (Object.keys(value).length === 0)
+        removePath(bindingsPath());
+    else
+        writeJson(bindingsPath(), value);
+    return cleared;
+}

package/dist/core/profiles/deletion-reservation.d.ts

@@ -0,0 +1,8 @@
+/** Reserve one profile identity for its complete daemon-owned deletion lifecycle.
+ * The caller must release the returned lease after completion or failure. */
+export declare function reserveProfileDeletion(profileId: string): () => void;
+/** The synchronous birth gate. spawnNode calls this immediately before the
+ * canvas row is persisted. A reservation rejects a birth that reaches the gate
+ * during deletion; the exact manifest read rejects one whose async preflight
+ * started before a fast hard deletion and resumed after its lease was released. */
+export declare function assertProfileAvailableForBirth(profileId: string | null): void;

package/dist/core/profiles/deletion-reservation.js

@@ -0,0 +1,38 @@
+import { usage } from '../errors.js';
+import { loadExactProfileManifest } from './manifest.js';
+const deletingProfileIds = new Set();
+/** Reserve one profile identity for its complete daemon-owned deletion lifecycle.
+ * The caller must release the returned lease after completion or failure. */
+export function reserveProfileDeletion(profileId) {
+    if (deletingProfileIds.has(profileId)) {
+        throw usage(`profile deletion is already in progress: ${profileId}`, {
+            error: 'profile_deletion_in_progress',
+            profile_id: profileId,
+            next: 'Wait for the accepted deletion to finish before using this profile again.',
+        });
+    }
+    deletingProfileIds.add(profileId);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        deletingProfileIds.delete(profileId);
+    };
+}
+/** The synchronous birth gate. spawnNode calls this immediately before the
+ * canvas row is persisted. A reservation rejects a birth that reaches the gate
+ * during deletion; the exact manifest read rejects one whose async preflight
+ * started before a fast hard deletion and resumed after its lease was released. */
+export function assertProfileAvailableForBirth(profileId) {
+    if (profileId === null)
+        return;
+    if (deletingProfileIds.has(profileId)) {
+        throw usage(`cannot create a node while its profile is being deleted: ${profileId}`, {
+            error: 'profile_deletion_in_progress',
+            profile_id: profileId,
+            next: 'Choose another profile or wait for this deletion to finish.',
+        });
+    }
+    loadExactProfileManifest(profileId);
+}

package/dist/core/profiles/manifest.d.ts

@@ -30,6 +30,9 @@ export declare function listProfiles(): ProfileEntry[];
  *  function every command leaf and runtime consumer should
  *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
  *  safe profile id. */
+/** Read one exact profile id without falling back to manifest-name matching.
+ * Used at persistence gates that already hold a resolved durable identity. */
+export declare function loadExactProfileManifest(profileId: string): ProfileEntry;
 export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;
 /** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
  *  mutations (create/rename/add-project/remove-project/delete/last-used)

package/dist/core/profiles/manifest.js

@@ -150,6 +150,18 @@ export function listProfiles() {
  *  function every command leaf and runtime consumer should
  *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
  *  safe profile id. */
+/** Read one exact profile id without falling back to manifest-name matching.
+ * Used at persistence gates that already hold a resolved durable identity. */
+export function loadExactProfileManifest(profileId) {
+    assertSafeProfileId(profileId);
+    const manifest = readManifestFile(profileManifestPath(profileId), profileId);
+    if (manifest !== null)
+        return { profileId, manifest };
+    throw notFound(`profile not found: ${profileId}`, {
+        received: profileId,
+        next: 'Run `crtr profile list` to see available profiles.',
+    });
+}
 export function loadProfileManifest(profileIdOrName) {
     const all = listProfiles();
     if (ID_SHAPE.test(profileIdOrName)) {

package/dist/core/profiles/select.js

@@ -296,10 +296,10 @@ function rootProfileMessage(cwd) {
 /** The one synchronous (pre-boot) decision point: no profile covers cwd, and
  *  the session IS interactive. Ask on the controlling terminal — create a
  *  profile pointing at cwd, or proceed as root — and block until answered.
- *  Deliberately a minimal `readline` prompt, not `crtr human ask`: that bridge
+ *  Deliberately a minimal `readline` prompt, not `crtr human send`: that bridge
  *  is asynchronous (registers an interaction in the ticket store, then waits for
  *  the human to answer it from a separate inbox) and cannot gate pi's boot; those
- *  entry points (`human ask`/`review`) are built for a queued,
+ *  entry points (`human send`/`review`) are built for a queued,
  *  asynchronously-answered interaction, not a two-choice gate on the same TTY pi
  *  is about to take over — a raw `readline` question is the actual minimal
  *  fit here. */

package/dist/core/review/realize.js

@@ -1,11 +1,12 @@
 import { existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename } from 'node:path';
 import { getNode, subscribersOf, subscribe } from '../canvas/index.js';
 import { withCanvasWrite } from '../canvas/db.js';
-import { atomicWriteJson } from '../human/convention.js';
+import { bindTicketReplyRoute } from '../human/convention.js';
 import { ticketDir } from '../human/root.js';
 import { submitReview } from '../human/tickets.js';
 import { NodeIdConflictError, spawnNode } from '../runtime/nodes.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
 import { transition } from '../runtime/lifecycle.js';
 import { reviveNode } from '../runtime/revive.js';
 import { awaitCompanionBind, spawnReviewCompanion } from './companion.js';
@@ -107,7 +108,7 @@ function realizeBridge(review) {
             profile_id: origin.profile_id ?? null,
             name: 'human-review',
         });
-        atomicWriteJson(join(ticketDir(bridge.node_id), 'run.json'), { mode: 'review' });
+        bindTicketReplyRoute(ticketDir(bridge.node_id), bridge.node_id);
         if (!bindBridgeNode(current.review_id, bridge.node_id)) {
             cancelInvisibleBridge(bridge.node_id);
             current = requireReview(current.review_id);
@@ -126,6 +127,10 @@ function publishTicket(review) {
         throw bridgeUnsubscribed(review, '');
     if (review.subtitle === null)
         throw new Error(`ticket review has no subtitle: ${review.review_id}`);
+    const origin = requireOrigin(review);
+    const profileName = origin.profile_id == null
+        ? undefined
+        : loadProfileManifest(origin.profile_id).manifest.name;
     submitReview({
         dir: ticketDir(review.bridge_node_id),
         review: {
@@ -133,7 +138,10 @@ function publishTicket(review) {
             ...(review.output_path !== null ? { output: review.output_path } : {}),
             title: basename(review.file),
             subtitle: review.subtitle,
-            source: { nodeId: review.origin_node_id },
+            source: {
+                nodeId: review.origin_node_id,
+                ...(profileName === undefined ? {} : { profileName }),
+            },
             blockedSince: review.created,
         },
     });

package/dist/core/review/store.d.ts

@@ -28,6 +28,12 @@ export declare function listReviews(filter: {
     origin_node_id?: string;
     file?: string;
 }): ReviewRecord[];
+/** Review ids whose immutable origin is one of `nodeIds`, including binding
+ *  rows that normal user-facing review listings intentionally hide. */
+export declare function reviewIdsByOriginNodes(nodeIds: readonly string[]): string[];
+/** Delete review audit state for the selected origins in dependency order.
+ *  Filesystem cleanup is deliberately left to the daemon lifecycle owner. */
+export declare function deleteReviewsByOriginNodes(nodeIds: readonly string[]): string[];
 export declare function listBindingReviews(): ReviewRecord[];
 /** Open reviews the human has already submitted, still waiting on their companion. */
 export declare function listSubmitRequestedReviews(): ReviewRecord[];

package/dist/core/review/store.js

@@ -116,6 +116,37 @@ export function listReviews(filter) {
     }
     return readRecords(openDb(), clauses.join(' AND '), ...params);
 }
+/** Review ids whose immutable origin is one of `nodeIds`, including binding
+ *  rows that normal user-facing review listings intentionally hide. */
+export function reviewIdsByOriginNodes(nodeIds) {
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => '?').join(',');
+    return openDb()
+        .prepare(`SELECT review_id FROM reviews WHERE origin_node_id IN (${placeholders}) ORDER BY created, review_id`)
+        .all(...ids).map(({ review_id }) => review_id);
+}
+/** Delete review audit state for the selected origins in dependency order.
+ *  Filesystem cleanup is deliberately left to the daemon lifecycle owner. */
+export function deleteReviewsByOriginNodes(nodeIds) {
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return [];
+    const originPlaceholders = ids.map(() => '?').join(',');
+    return withCanvasWrite((db) => {
+        const reviewIds = db
+            .prepare(`SELECT review_id FROM reviews WHERE origin_node_id IN (${originPlaceholders}) ORDER BY created, review_id`)
+            .all(...ids).map(({ review_id }) => review_id);
+        if (reviewIds.length === 0)
+            return [];
+        const reviewPlaceholders = reviewIds.map(() => '?').join(',');
+        db.prepare(`DELETE FROM review_comment_events WHERE review_id IN (${reviewPlaceholders})`).run(...reviewIds);
+        db.prepare(`DELETE FROM review_comments WHERE review_id IN (${reviewPlaceholders})`).run(...reviewIds);
+        db.prepare(`DELETE FROM reviews WHERE review_id IN (${reviewPlaceholders})`).run(...reviewIds);
+        return reviewIds;
+    });
+}
 export function listBindingReviews() {
     return readRecords(openDb(), "state = 'binding'");
 }

package/dist/core/runtime/bearings.d.ts

@@ -61,10 +61,6 @@ export declare function cronWakeOrigin(c: Cron, kind: WakeOrigin['kind']): WakeO
  *  carry the signal, and a raw ISO instant is noise an agent cannot cheaply turn
  *  into an elapsed delta. */
 export declare function buildWakeBearings(origin: WakeOrigin): string;
-/** The node-scoped update for a fork whose copied branch already contains a
- *  full crouter baseline. Shared project and operating context stays in the
- *  inherited branch; this block replaces only source-owned facts. */
-export declare function buildForkBearings(nodeId: string): string;
 /** The full boot intro, four top-level sections:
  *
  *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity

package/dist/core/runtime/bearings.js

@@ -3,9 +3,10 @@
 // A conversation with no inherited crouter bearings receives the full baseline:
 // node identity and graph position, context-directory guidance, routed knowledge,
 // auto-loaded project docs, situational context, and the current environment.
-// A fork whose copied branch already carries that baseline receives only
-// buildForkBearings(): the new node-scoped facts that supersede its source's
-// identity. The copied baseline remains useful reference without being repeated.
+// A fork whose copied branch already carries that baseline receives only the
+// new node-scoped facts that supersede its source's identity — rendered by
+// buildForkBearingsFromState() in broker-extension-render.ts, the broker-side
+// mirror. The copied baseline remains useful reference without being repeated.
 //
 // promote.ts separately delivers orchestratorContextNote() when a base node
 // becomes an orchestrator after birth.
@@ -329,65 +330,6 @@ function managedWorktreeNote(node) {
         return '';
     return `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.base_sha}\`\nCommit work here. Land it with \`crtr node worktree close\` before finishing. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); unlanded commits (commits not already contained in the base) or uncommitted changes require an explicit close/landing decision.`;
 }
-/** The review-companion block — rendered ONLY when a node carries its immutable
- *  review binding. Names the target file (the document under review), clarifies
- *  that inherited context belongs to the origin node and is not visible to the
- *  person, and notes that the visible transcript begins at the boundary marker
- *  above. */
-function reviewCompanionBlock(meta) {
-    if (meta?.review_binding === undefined || meta?.review_binding === null)
-        return '';
-    const targetFile = meta.review_binding.target_file;
-    return (`You exist for one human review of \`${targetFile}\`. The inherited conversation belongs to ` +
-        `the origin node, not you — carry only the context needed for this review. The person's visible ` +
-        `transcript begins at the boundary marker above; everything earlier is context they cannot see.`);
-}
-/** The node-scoped update for a fork whose copied branch already contains a
- *  full crouter baseline. Shared project and operating context stays in the
- *  inherited branch; this block replaces only source-owned facts. */
-export function buildForkBearings(nodeId) {
-    const node = getNode(nodeId);
-    const bearings = [
-        '<crtr-bearings>',
-        buildIdentityAssertion(nodeId),
-        '',
-        'The source node’s earlier task, graph position, lifecycle, children, schedules, worktree, situational context, and context-directory path do not carry over. Shared conversation, project, and operating context remain reference material.',
-        '',
-        '## Your node now',
-        `Lifecycle: ${node?.lifecycle ?? 'terminal'}.`,
-    ];
-    const map = buildGraphMap(nodeId);
-    if (map === '') {
-        bearings.push('Canvas: independent root with no parent or inherited graph edges.');
-    }
-    else {
-        bearings.push('', map);
-    }
-    bearings.push(`Context directory: \`${contextDir(nodeId)}\` (\`$CRTR_CONTEXT_DIR\`). Use this path in place of every source-node context path above.`);
-    const forkFrom = node?.fork_from;
-    const source = forkFrom !== undefined && forkFrom !== null && isSafeNodeId(forkFrom)
-        ? getNode(forkFrom)
-        : null;
-    if (node !== null && (source === null || source.cwd !== node.cwd)) {
-        bearings.push(`Working directory: \`${node.cwd}\`.`);
-    }
-    if (node !== null && (source === null || source.profile_id !== node.profile_id)) {
-        const profileSection = profileNote(nodeId);
-        if (profileSection !== '')
-            bearings.push(profileSection);
-    }
-    const worktree = managedWorktreeNote(node);
-    if (worktree !== '')
-        bearings.push('', '## Your managed worktree', worktree);
-    if (node?.mode === 'orchestrator')
-        bearings.push('', orchestratorContextNote(nodeId));
-    const review = reviewCompanionBlock(node);
-    if (review !== '')
-        bearings.push('', review);
-    bearings.push('', 'The first real user message after these bearings is your mandate.', '</crtr-bearings>');
-    const situational = situationalContextBlock(nodeId);
-    return [bearings.join('\n'), situational].filter((s) => s !== '').join('\n');
-}
 /** The full boot intro, four top-level sections:
  *
  *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity

package/dist/core/runtime/bin-contributions.d.ts

@@ -0,0 +1,44 @@
+import type { Scope } from '../../types.js';
+/** One resolved bare command: the name a node's bash sees, and the absolute
+ *  real path the shim links to. */
+export interface ResolvedBin {
+    name: string;
+    /** Absolute target validated inside the contributing root when this set resolved. */
+    target: string;
+    /** Human-readable contributor, e.g. `plugin "deploy-tools"` or
+     *  `config.json (/repo/.crouter)`. */
+    origin: string;
+    scope: Scope;
+}
+/** A declaration that did NOT become a bare command, with why. Surfaced by
+ *  `crtr sys doctor`; never thrown, so one bad entry can never stop a node
+ *  from launching. */
+export interface BinIssue {
+    name: string;
+    origin: string;
+    scope: Scope;
+    message: string;
+}
+export interface BinResolution {
+    /** Effective name → resolved bin, after layering. */
+    bins: Map<string, ResolvedBin>;
+    issues: BinIssue[];
+}
+/** The effective bare-command set for one node's cwd/profile, plus every
+ *  declaration that failed to become one.
+ *
+ *  Layers ascend in precedence (see `contributionLayers`). A name claimed by
+ *  two contributors in the SAME layer selects no winner: it is reported and
+ *  removed, so an ambiguous name resolves to nothing rather than to whichever
+ *  plugin sorted first. A higher layer may still claim that name explicitly —
+ *  that is an unambiguous choice, not a collision. */
+export declare function resolveBinContributions(targetCwd: string, targetProfileId: string | null): BinResolution;
+/** Materialize (idempotently) the shim directory for one effective set and
+ *  return its absolute path, or null when the set is empty. Built in a staging
+ *  dir and renamed into place, so a concurrent launch either sees no directory
+ *  or sees a complete one. */
+export declare function ensureBinShimDir(bins: Map<string, ResolvedBin>): string | null;
+/** The shim directory to prepend to a target node's PATH, or null when that
+ *  node's scopes declare no bare command. The one entry point the spawn-env
+ *  boundary calls. */
+export declare function binShimDirFor(targetCwd: string, targetProfileId: string | null): string | null;

package/dist/core/runtime/bin-contributions.js

@@ -0,0 +1,186 @@
+// Bare-binary contributions — the plain executables a node's bash can call by
+// name, with no `crtr` command leaf and no exec-command JSON protocol between
+// them and the agent.
+//
+// A plugin declares them in its manifest (`bin`), a user or project scope in
+// its own `config.json` (`bin`); both are a small name → root-relative-path
+// map. This module resolves those declarations across the same layering the
+// rest of the config uses (project stack > user, and within one root: that
+// root's own config > its enabled plugins), materializes one crouter-owned
+// shim directory of symlinks, and hands its path to the spawn-env boundary
+// (`spawn-env.ts`), which PREPENDS it to every broker child's PATH while
+// leaving the host PATH intact behind it.
+//
+// The shim directory exists so the declaration stays a per-name grant: crouter
+// links exactly the names that were declared, rather than putting a
+// contributor's whole `bin/` directory on the agent's PATH and admitting every
+// sibling file in it.
+//
+// These binaries are trusted local code running with the caller's authority —
+// the same authority the agent's bash tool already has. There is no sandbox,
+// no install hook, and no shell evaluation anywhere in this path. Containment
+// is checked while resolving the effective set; a contributor can change later
+// because it is trusted local code, not a sandboxed artifact.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { binDeclarationIssues, normalizeBin, readRawConfigAtRoot } from '../config.js';
+import { listInstalledPluginsInRoot } from '../installed-plugins.js';
+import { crtrHome } from '../canvas/paths.js';
+import { findProjectScopeRoots, scopeRoot } from '../scope.js';
+function contributorIssues(origin, scope, raw) {
+    return binDeclarationIssues(raw).map((issue) => ({ name: issue.name, origin, scope, message: issue.message }));
+}
+function pluginContributors(scope, root) {
+    return listInstalledPluginsInRoot(scope, root)
+        .filter((plugin) => plugin.enabled && plugin.manifest.bin !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((plugin) => {
+        const origin = `plugin "${plugin.name}"`;
+        return { origin, scope, root: plugin.root, bin: normalizeBin(plugin.manifest.bin), issues: contributorIssues(origin, scope, plugin.manifest.bin) };
+    });
+}
+/** A scope's own `config.json` contributions. Paths resolve against the scope's
+ *  AUTHORING root: the project directory for a project scope (so a repo writes
+ *  `tools/repoctl`, where its tools actually live, not `../tools/repoctl` out
+ *  of `.crouter/`), and `~/.crouter` itself for the user scope, which has no
+ *  enclosing project. */
+function configContributor(scope, scopeRootPath) {
+    const raw = readRawConfigAtRoot(scopeRootPath)?.bin;
+    if (raw === undefined)
+        return [];
+    const origin = `config.json (${scopeRootPath})`;
+    const bin = normalizeBin(raw);
+    const root = scope === 'project' ? dirname(scopeRootPath) : scopeRootPath;
+    return [{ origin, scope, root, bin, issues: contributorIssues(origin, scope, raw) }];
+}
+/** The contribution LAYERS in ascending precedence: a later layer's entry
+ *  replaces an earlier layer's same name. Within one root the root's own
+ *  `config.json` outranks its plugins (the rule `layerPluginKinds` follows for
+ *  `kinds`), and the project stack — nearest root last — outranks the user
+ *  scope entirely. Contributors WITHIN one layer never outrank each other:
+ *  two of them claiming one name is a collision, not a precedence question. */
+function contributionLayers(targetCwd, targetProfileId) {
+    const layers = [];
+    const userRoot = scopeRoot('user');
+    if (userRoot !== null) {
+        layers.push(pluginContributors('user', userRoot), configContributor('user', userRoot));
+    }
+    const projectRootsNearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
+    for (const root of [...projectRootsNearestFirst].reverse()) {
+        layers.push(pluginContributors('project', root), configContributor('project', root));
+    }
+    return layers.filter((layer) => layer.length > 0);
+}
+/** Resolve one declared path against its contributing root: it must stay
+ *  inside that root, be a regular file, and carry a POSIX exec bit when the
+ *  effective set is resolved. Returns the absolute real path, or the reason it
+ *  is not usable. */
+function resolveTarget(root, relative) {
+    let rootReal;
+    let target;
+    try {
+        rootReal = realpathSync(root);
+        target = realpathSync(resolve(root, relative));
+    }
+    catch {
+        return { reason: `target does not exist: ${join(root, relative)}` };
+    }
+    if (target !== rootReal && !target.startsWith(rootReal + sep)) {
+        return { reason: `target escapes its contributing root: ${relative}` };
+    }
+    const stat = statSync(target);
+    if (!stat.isFile())
+        return { reason: `target is not a regular file: ${target}` };
+    if ((stat.mode & 0o111) === 0)
+        return { reason: `target lacks the POSIX exec bit: ${target}` };
+    return { target };
+}
+/** The effective bare-command set for one node's cwd/profile, plus every
+ *  declaration that failed to become one.
+ *
+ *  Layers ascend in precedence (see `contributionLayers`). A name claimed by
+ *  two contributors in the SAME layer selects no winner: it is reported and
+ *  removed, so an ambiguous name resolves to nothing rather than to whichever
+ *  plugin sorted first. A higher layer may still claim that name explicitly —
+ *  that is an unambiguous choice, not a collision. */
+export function resolveBinContributions(targetCwd, targetProfileId) {
+    const bins = new Map();
+    const issues = [];
+    for (const layer of contributionLayers(targetCwd, targetProfileId)) {
+        const claims = new Map();
+        for (const contributor of layer) {
+            issues.push(...contributor.issues);
+            for (const name of Object.keys(contributor.bin)) {
+                const existing = claims.get(name);
+                if (existing === undefined)
+                    claims.set(name, [contributor]);
+                else
+                    existing.push(contributor);
+            }
+        }
+        for (const [name, claimants] of claims) {
+            if (claimants.length > 1) {
+                const origins = claimants.map((claimant) => claimant.origin).join(', ');
+                bins.delete(name);
+                for (const claimant of claimants) {
+                    issues.push({ name, origin: claimant.origin, scope: claimant.scope, message: `bare command "${name}" is claimed by ${origins} at the same precedence — no winner is selected and the name is not installed` });
+                }
+                continue;
+            }
+            const contributor = claimants[0];
+            const resolved = resolveTarget(contributor.root, contributor.bin[name]);
+            if ('reason' in resolved) {
+                issues.push({ name, origin: contributor.origin, scope: contributor.scope, message: resolved.reason });
+                continue;
+            }
+            bins.set(name, { name, target: resolved.target, origin: contributor.origin, scope: contributor.scope });
+        }
+    }
+    return { bins, issues };
+}
+/** Content address of one effective bare-command set — the shim directory's
+ *  name. Because the address covers every name and target, an existing
+ *  directory is already correct: nothing is ever rewritten in place, a changed
+ *  set simply materializes beside the old one, and two processes racing the
+ *  same set produce byte-identical trees. */
+function shimAddress(bins) {
+    const lines = [...bins.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((bin) => `${bin.name}\u0000${bin.target}`)
+        .join('\n');
+    return createHash('sha256').update(lines).digest('hex').slice(0, 32);
+}
+/** Materialize (idempotently) the shim directory for one effective set and
+ *  return its absolute path, or null when the set is empty. Built in a staging
+ *  dir and renamed into place, so a concurrent launch either sees no directory
+ *  or sees a complete one. */
+export function ensureBinShimDir(bins) {
+    if (bins.size === 0)
+        return null;
+    const dir = join(crtrHome(), 'bin-shims', shimAddress(bins));
+    if (existsSync(dir))
+        return dir;
+    const staging = `${dir}.staging-${process.pid}-${Date.now().toString(36)}`;
+    mkdirSync(staging, { recursive: true });
+    try {
+        for (const bin of bins.values())
+            symlinkSync(bin.target, join(staging, bin.name));
+        renameSync(staging, dir);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        // Another launch materializing the same address won the rename — its tree
+        // is identical by construction, so the address is still correct.
+        if (existsSync(dir))
+            return dir;
+        throw error;
+    }
+    return dir;
+}
+/** The shim directory to prepend to a target node's PATH, or null when that
+ *  node's scopes declare no bare command. The one entry point the spawn-env
+ *  boundary calls. */
+export function binShimDirFor(targetCwd, targetProfileId) {
+    return ensureBinShimDir(resolveBinContributions(targetCwd, targetProfileId).bins);
+}

package/dist/core/runtime/boot-root.js

@@ -89,7 +89,12 @@ export async function bootRoot(opts) {
     // user's OWN pre-existing shell pane (not one crtr split open): on a
     // detach-reap of an empty root it must delete the node WITHOUT kill-pane, else
     // a plain ctrl+c closes the user's whole tmux pane.
-    const attachEnv = { ...process.env, ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: '30000' };
+    const attachEnv = {
+        ...process.env,
+        ...viewerSplitEnv(),
+        CRTR_ATTACH_WAIT_MS: '30000',
+        ...(opts.prompt !== undefined && opts.prompt !== '' ? { CRTR_ATTACH_INITIAL_WHIP: '1' } : {}),
+    };
     if (here !== null)
         attachEnv['CRTR_ATTACH_BORROWED_PANE'] = here.pane;
     mark('boot_root.viewer_spawn');

package/dist/core/runtime/broker/client-registry.d.ts

@@ -1,5 +1,9 @@
 import type { Socket } from 'node:net';
 import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole } from '../broker-protocol.js';
+/** True when the live broker has at least one helloed terminal or web viewer.
+ *  Callers establish broker liveness separately because a crash can leave the
+ *  last persisted count behind. */
+export declare function hasAttachedBrokerViewers(nodeId: string): boolean;
 export interface BrokerClient {
     id: string;
     role: ClientRole;

package/dist/core/runtime/broker/client-registry.js

@@ -1,10 +1,22 @@
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { jobDir } from '../../canvas/paths.js';
 import { emitEvent } from '../../events/emit.js';
 import { encodeFrame, FrameDecoder, BROKER_READ_CAPS, } from '../broker-protocol.js';
 /** Per-viewer outbound high-water mark. Slow viewers are shed rather than allowed to backpressure the shared engine indefinitely. */
 const MAX_QUEUED_FRAMES = 1000;
 const MAX_PENDING_BYTES = 32 * 1024 * 1024;
+/** True when the live broker has at least one helloed terminal or web viewer.
+ *  Callers establish broker liveness separately because a crash can leave the
+ *  last persisted count behind. */
+export function hasAttachedBrokerViewers(nodeId) {
+    try {
+        const record = JSON.parse(readFileSync(`${jobDir(nodeId)}/attach.json`, 'utf8'));
+        return typeof record.viewers === 'number' && record.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
 /** Owns connected viewers, their outbound backpressure, and durable attach presence. */
 export class BrokerClientRegistry {
     nodeId;

package/dist/core/runtime/broker/extension-abort.d.ts

@@ -5,5 +5,5 @@ interface AbortableSession {
 /** Mark one synchronous ExtensionContext.abort() call as a refresh boundary. */
 export declare function runRefreshAbort(abort: () => void): void;
 /** Bound into Pi's extension context by the broker for every session generation. */
-export declare function abortSessionFromExtension(session: AbortableSession): void;
+export declare function abortSessionFromExtension(session: AbortableSession, stageRefreshAbort?: () => void): void;
 export {};

package/dist/core/runtime/broker/extension-abort.js

@@ -16,8 +16,10 @@ export function runRefreshAbort(abort) {
     }
 }
 /** Bound into Pi's extension context by the broker for every session generation. */
-export function abortSessionFromExtension(session) {
-    if (refreshAbortScope)
+export function abortSessionFromExtension(session, stageRefreshAbort) {
+    if (refreshAbortScope) {
         session.clearQueue();
+        stageRefreshAbort?.();
+    }
     void session.abort();
 }

package/dist/core/runtime/broker/fault-retry.js

@@ -48,9 +48,11 @@ export class FaultRetry {
     publishSettledProviderFault(generation) {
         const agentEnd = generation.stagedProviderAgentEnd;
         const watchdogAbort = generation.stagedWatchdogAbort;
+        const refreshAbort = generation.stagedRefreshAbort;
         const overflowFailure = generation.stagedOverflowFailure;
         generation.stagedProviderAgentEnd = null;
         generation.stagedWatchdogAbort = false;
+        generation.stagedRefreshAbort = false;
         generation.stagedOverflowFailure = null;
         const settledSession = generation.session;
         // A failed daemon retry settles here with the episode's fault marker still
@@ -84,6 +86,8 @@ export class FaultRetry {
         }
         if (last?.stopReason !== 'error')
             return;
+        if (refreshAbort)
+            return;
         const raw = typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)';
         const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
         const classified = classify('pi→provider', last);

package/dist/core/runtime/broker/frame-dispatch.d.ts

@@ -181,7 +181,9 @@ export type FrameDispatchDeps = {
     toolGroups: ToolGroupTracker;
     projection: EventProjection;
     rebind: RebindDriver;
-    reviewCompanion: boolean;
+    /** The bound review id whose boundary marker opens this companion's visible
+     *  transcript; undefined for ordinary nodes. */
+    boundaryReviewId: string | undefined;
     pendingDialogs: Map<string, PendingDialog>;
     sendWelcome: (client: BrokerClient) => void;
     replayExtraPendingDialogsTo: (client: BrokerClient) => void;