@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/runtime/session-visibility.js

@@ -38,21 +38,26 @@ function syntheticBoundary(timestamp) {
 /**
  * Project snapshot messages to the visible window for a review companion.
  *
+ * A companion passes its binding's review id so the slice starts at ITS OWN
+ * boundary marker: a node forked from another companion inherits that
+ * companion's earlier marker, and slicing at the first marker of any review
+ * would reveal the origin companion's transcript.
+ *
  * Contract (in evaluation order):
- * 1. Marker present → slice from the **first** occurrence (marker included) to
- *    the end. Everything before the marker is inherited context, hidden from
- *    the person.
- * 2. Not a review companion → return input unchanged (same reference). Ordinary
- *    nodes are not filtered.
- * 3. No marker and review companion → a leading compaction summary is replaced
+ * 1. This binding's marker present (any marker when the node has no binding) →
+ *    slice from the **first** occurrence (marker included) to the end.
+ *    Everything before the marker is inherited context, hidden from the person.
+ * 2. Not a companion (`boundaryReviewId` undefined) → return input unchanged
+ *    (same reference). Ordinary nodes are not filtered.
+ * 3. Bound but no matching marker → a leading compaction summary is replaced
  *    with a synthetic boundary while its retained tail remains visible. Every
  *    other markerless shape fails closed with the synthetic boundary alone.
  */
 export function visibleMessages(messages, opts) {
-    const markerIndex = messages.findIndex((message) => isReviewBoundary(message));
+    const markerIndex = messages.findIndex((message) => isReviewBoundary(message, opts.boundaryReviewId));
     if (markerIndex !== -1)
         return messages.slice(markerIndex);
-    if (!opts.reviewCompanion)
+    if (opts.boundaryReviewId === undefined)
         return messages;
     const [first, ...retainedTail] = messages;
     if (first?.role === 'compactionSummary') {
@@ -68,14 +73,18 @@ export function visibleMessages(messages, opts) {
  * boundary is crossed, its complete descendant subtree remains navigable. An
  * absent boundary produces an empty tree, so picker previews never disclose an
  * inherited entry before a mutation guard can reject its selection.
+ *
+ * `boundaryReviewId` selects only this binding's marker as a root, so a
+ * companion forked from another companion never navigates into the inherited
+ * subtree rooted at the origin's earlier marker.
  */
-export function boundaryRootedTree(tree) {
+export function boundaryRootedTree(tree, boundaryReviewId) {
     const retainSubtree = (node) => ({
         ...node,
         children: node.children.map(retainSubtree),
     });
     const project = (node) => {
-        if (isReviewBoundary(node.entry))
+        if (isReviewBoundary(node.entry, boundaryReviewId))
             return [retainSubtree(node)];
         return node.children.flatMap(project);
     };

package/dist/core/runtime/spawn-env.d.ts

@@ -1,4 +1,12 @@
-import type { PiInvocation } from './launch.js';
+import type { PiInvocation } from './invocation.js';
+/** The unshimmed PATH admitted from the host. Broker and cron shells resolve
+ *  crouter-owned executables from this value, while commands those shells run
+ *  still receive the shim-prepended PATH. */
+export declare const ADMITTED_HOST_PATH_ENV = "CRTR_ADMITTED_HOST_PATH";
+/** Resolve a regular executable against a shell PATH without executing it.
+ *  The result is absolute, or null when no PATH entry supplies the command. */
+export declare function resolvePathExecutable(name: string, env: NodeJS.ProcessEnv, cwd: string): string | null;
+export declare function resolveAdmittedHostCommand(name: string, env: NodeJS.ProcessEnv, cwd: string): string;
 /** Sources A–C: the operational base shared by the broker boundary (this
  *  module's `buildBrokerEnv`) and cron executor — the single shared definition
  *  of "non-secret host state the runtime exposes to any spawned shell." Does not include

package/dist/core/runtime/spawn-env.js

@@ -15,6 +15,13 @@
 // `spawnEnv.allow` entry. `inv.env` (D) is crtr-constructed and trusted, so
 // it overlays unconditionally, layered after E.
 //
+// One name IS rewritten rather than merely admitted: `PATH`. Bare-binary
+// contributions (`bin` in a plugin manifest or a scope `config.json`) are
+// materialized into a crouter-owned shim directory by
+// `core/runtime/bin-contributions.ts`, and that directory is PREPENDED here so
+// a declared bare command wins its name in every node's bash. The admitted
+// host PATH stays intact behind it.
+//
 // `GIT_*` is deliberately absent from the allowlist: the whole namespace is an
 // auth/config-injection surface (`GIT_CONFIG_KEY_*`/`GIT_CONFIG_VALUE_*`,
 // `GIT_ASKPASS`, `GIT_SSH_COMMAND`), not a non-secret operational family, and
@@ -22,9 +29,12 @@
 // `~/.gitconfig`, reached through the allowlisted `HOME`; SSH remotes via the
 // allowlisted `SSH_AUTH_SOCK`). A deliberate `GIT_*` need goes through
 // `spawnEnv.allow`.
+import { statSync } from 'node:fs';
+import { delimiter, resolve } from 'node:path';
 import { readMergedLaunchConfig } from '../config.js';
 import { readProfileEnvVars } from '../profiles/env-store.js';
-import { FRONT_DOOR_ENV } from './front-door.js';
+import { binShimDirFor } from './bin-contributions.js';
+import { FRONT_DOOR_ENV } from './front-door-env.js';
 /** A1 — literal env-var names copied verbatim (no value inspection): a login
  *  shell plus dev toolchain needs exactly these, and none of them can carry a
  *  credential. */
@@ -54,6 +64,39 @@ const OPERATIONAL_LITERAL_NAMES = new Set([
  *  file-backed in `auth.json`, never an env value). `GIT_` is NOT here — see
  *  module comment. */
 const OPERATIONAL_PREFIXES = ['LC_', 'XDG_', 'PI_'];
+/** The unshimmed PATH admitted from the host. Broker and cron shells resolve
+ *  crouter-owned executables from this value, while commands those shells run
+ *  still receive the shim-prepended PATH. */
+export const ADMITTED_HOST_PATH_ENV = 'CRTR_ADMITTED_HOST_PATH';
+/** Resolve a regular executable against a shell PATH without executing it.
+ *  The result is absolute, or null when no PATH entry supplies the command. */
+export function resolvePathExecutable(name, env, cwd) {
+    const pathValue = env['PATH'];
+    if (pathValue === undefined || pathValue === '')
+        return null;
+    for (const directory of pathValue.split(delimiter)) {
+        const candidate = resolve(cwd, directory === '' ? '.' : directory, name);
+        try {
+            const stat = statSync(candidate);
+            if (stat.isFile() && (stat.mode & 0o111) !== 0)
+                return candidate;
+        }
+        catch {
+            // Keep searching exactly as PATH resolution does.
+        }
+    }
+    return null;
+}
+export function resolveAdmittedHostCommand(name, env, cwd) {
+    const pathValue = env[ADMITTED_HOST_PATH_ENV] ?? env['PATH'];
+    if (pathValue === undefined || pathValue === '') {
+        throw new Error(`cannot resolve crouter-owned ${name}: the admitted host PATH is empty`);
+    }
+    const command = resolvePathExecutable(name, { PATH: pathValue }, cwd);
+    if (command !== null)
+        return command;
+    throw new Error(`cannot resolve crouter-owned ${name} from the admitted host PATH`);
+}
 /** A2 — proxy var names. Admitted only when the value's URL authority carries
  *  no userinfo component (no `user@` / `user:pass@`) — the one value-inspected
  *  entry in the whole builder, because a proxy var is the single operational
@@ -151,6 +194,21 @@ export function buildOperationalEnvBase(opts) {
                 out[key] = value;
         }
     }
+    // Preserve the unshimmed admitted host PATH across broker and cron children.
+    // A nested `crtr` launched from an agent inherits this constructed value,
+    // rather than mistaking its shim-prepended PATH for the host path.
+    const admittedHostPath = host[ADMITTED_HOST_PATH_ENV] ?? out['PATH'];
+    if (admittedHostPath !== undefined && admittedHostPath !== '')
+        out[ADMITTED_HOST_PATH_ENV] = admittedHostPath;
+    // Bare-binary contributions (`core/runtime/bin-contributions.ts`): the shim
+    // dir holding one symlink per declared bare command, PREPENDED so a
+    // contribution wins its name, with the host PATH admitted above left intact
+    // behind it. Resolved from the TARGET's own cwd/profile like source C.
+    const shimDir = binShimDirFor(opts.targetCwd, opts.targetProfileId);
+    if (shimDir !== null) {
+        const hostPath = out['PATH'];
+        out['PATH'] = hostPath === undefined || hostPath === '' ? shimDir : `${shimDir}:${hostPath}`;
+    }
     return out;
 }
 /** The one authoritative broker child env: sources A–C (the operational
@@ -170,10 +228,12 @@ export function buildOperationalEnvBase(opts) {
 export function buildBrokerEnv(inv) {
     const targetCwd = inv.env['CRTR_NODE_CWD'] ?? process.cwd();
     const targetProfileId = inv.env['CRTR_PROFILE_ID'] || null;
+    const operational = buildOperationalEnvBase({ targetCwd, targetProfileId });
     return {
-        ...buildOperationalEnvBase({ targetCwd, targetProfileId }),
+        ...operational,
         ...readProfileEnvVars(targetProfileId),
         ...inv.env,
+        [ADMITTED_HOST_PATH_ENV]: operational[ADMITTED_HOST_PATH_ENV],
         [FRONT_DOOR_ENV]: '1',
     };
 }

package/dist/core/runtime/spawn.js

@@ -401,15 +401,15 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                     // have bound view.sock yet. Hand the attach pane CRTR_ATTACH_WAIT_MS so
                     // it self-polls the socket until it accepts instead of connecting once,
                     // finding a cold socket, and closing the pane instantly — the exact
-                    // mechanism bootRoot uses. Mark this as the initial auto-opened child
-                    // viewer too, so whip_mode can greet it without firing on ordinary
-                    // focus/attach paths. No pre-wait in this CLI subprocess.
+                    // mechanism bootRoot uses. A child with a kickoff prompt marks its
+                    // initial viewer for whip_mode; ordinary focus/attach paths stay
+                    // silent. No pre-wait in this CLI subprocess.
                     const viewer = openViewerWindow(meta.node_id, parentViewer.session ?? '', {
                         name: fullName(meta),
                         cwd: opts.cwd,
                         besidePane: parentViewer.pane,
                         waitForBroker: true,
-                        initialWhip: true,
+                        initialWhip: hasKickoff,
                     });
                     if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
                         session = viewer.session;

package/dist/core/runtime/stop-guard.d.ts

@@ -2,8 +2,8 @@ export { STALL_REPROMPT } from '../../shared/generated-context.js';
 export interface StopSignals {
     /** Did the node call `push --final` (finish) this turn? */
     pushedFinal: boolean;
-    /** Did the node call `crtr ask` (escalate to the human) this turn? */
-    askedHuman: boolean;
+    /** Did the node call `crtr ask` (escalate to the user) this turn? */
+    requestedHumanReply: boolean;
 }
 export type StopAction = {
     action: 'allow';

package/dist/core/runtime/stop-guard.js

@@ -37,7 +37,7 @@ function formatInvalidStructuredOutputReprompt(error) {
         `1. Remove the invalid file (the output-schema.json in your node directory has been corrupted)\n` +
         `2. Fix the corruption if you know the original request schema\n\n` +
         `After resolving the file, retry the submission. ` +
-        `If this is unexpected, escalate to the human using \`crtr human ask\`.`);
+        `If this is unexpected, escalate to the user using \`crtr human send\`.`);
 }
 /** Decide what to do when a node stops. crtrd supplies every current-canvas
  * fact; the broker contributes only whether its Pi-owned background job registry
@@ -45,7 +45,7 @@ function formatInvalidStructuredOutputReprompt(error) {
 export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBackgroundBashJobs(contextDir(nodeId)).length > 0) {
     if (signals.pushedFinal)
         return { action: 'allow', reason: 'finished' };
-    if (signals.askedHuman)
+    if (signals.requestedHumanReply)
         return { action: 'allow', reason: 'escalated' };
     // A pending structured-output request overrides every stored-state dormancy
     // path: a post-final one-off follow-up still owes `submit` before it may stop.

package/dist/core/runtime/stop-signals.d.ts

@@ -1,6 +1,6 @@
 export interface StopSignals {
     pushedFinal: boolean;
-    askedHuman: boolean;
+    requestedHumanReply: boolean;
 }
 export type StopSignal = keyof StopSignals;
 /** Record a successful command outcome for this broker process. The stophook

package/dist/core/runtime/stop-signals.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { jobDir } from '../canvas/paths.js';
-const SIGNALS = ['pushedFinal', 'askedHuman'];
+const SIGNALS = ['pushedFinal', 'requestedHumanReply'];
 function signalPath(nodeId, signal) {
     return join(jobDir(nodeId), `.${signal}`);
 }
@@ -24,7 +24,7 @@ export function markStopSignal(nodeId, signal) {
 /** Consume command outcomes from this broker's just-settled turn. Markers from
  * an earlier crashed broker are discarded rather than bleeding into its successor. */
 export function consumeStopSignals(nodeId) {
-    const signals = { pushedFinal: false, askedHuman: false };
+    const signals = { pushedFinal: false, requestedHumanReply: false };
     for (const signal of SIGNALS) {
         const path = signalPath(nodeId, signal);
         if (!existsSync(path))

package/dist/core/runtime/tmux-bindings.js

@@ -522,7 +522,7 @@ function restoreWrappedBinding(wrapper) {
 // not the sealed generation that installed it. The neighboring `crtr surface node cycle` builders
 // share that property.
 export function inboxToggleTmuxCommand() {
-    return ['run-shell', '-b', 'crtr human inbox toggle --quiet --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"'];
+    return ['run-shell', '-b', 'crtr surface inbox --quiet --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"'];
 }
 function actionCommand(id) {
     switch (id) {

package/dist/core/session-model/session-state.d.ts

@@ -24,9 +24,10 @@ export interface SessionState {
     /** Live context occupancy in prompt tokens: seeded from the snapshot's
      *  contextUsage, then tracked off each assistant `message_end`. */
     contextTokens: number | undefined;
-    /** Queued steering + follow-up messages, from `queue_update`. A fresh broker
-     *  with an empty queue emits no `queue_update`, so every welcome resets this
-     *  rather than leaving a dead broker's rows on screen. */
+    /** Queued steering + follow-up messages: seeded from `welcome.snapshot.queued`
+     *  and tracked off `queue_update`. Every welcome REPLACES this — the attaching
+     *  broker's own queue is the whole truth, so a dead broker's rows never survive
+     *  and a client attaching mid-queue still sees what is waiting. */
     queued: Array<{
         text: string;
     }>;

package/dist/core/session-model/session-state.js

@@ -48,7 +48,7 @@ export function applySnapshot(frame) {
         agentDir: frame.agentDir,
         engine: snapshot.state,
         contextTokens: contextUsage?.tokens ?? undefined,
-        queued: [],
+        queued: snapshotQueued(snapshot),
         display: {
             statuses: { ...display.statuses },
             widgets: Object.fromEntries(Object.entries(display.widgets).map(([k, w]) => [k, { lines: [...w.lines], placement: w.placement }])),
@@ -140,6 +140,19 @@ export function reduce(state, frame) {
             return state;
     }
 }
+/** The queue a `welcome` reports, composed exactly as `queue_update` composes
+ *  it. Absent on a snapshot from a broker generation older than the field, and
+ *  on an offline node (no engine, so no queue) — both mean nothing is waiting. */
+function snapshotQueued(snapshot) {
+    const queued = snapshot.queued;
+    if (typeof queued !== 'object' || queued === null)
+        return [];
+    const { steering, followUp } = queued;
+    return [...texts(steering), ...texts(followUp)].map((text) => ({ text }));
+}
+function texts(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
 /** Apply a partial patch to pi's state, preserving reference identity when the
  *  patch changes nothing (and when no welcome has seeded `engine` yet). */
 function patchEngine(state, patch) {

package/dist/core/user-settings.d.ts

@@ -147,10 +147,40 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             setFromString: (config: ScopeConfig, raw: string) => string | null;
         };
     };
+    page_surface: {
+        surface: "settings";
+        setting: {
+            key: "page_surface";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
     whip_messages: {
         surface: "specialized";
         owner: string;
     };
+    whip_message_mode: {
+        surface: "settings";
+        setting: {
+            key: "whip_message_mode";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "random" | "go faster";
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
     mouse_mode_default: {
         surface: "settings";
         setting: {
@@ -196,10 +226,10 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             setFromString: (config: ScopeConfig, raw: string) => string | null;
         };
     };
-    html_pages: {
+    bash_tool_purpose: {
         surface: "settings";
         setting: {
-            key: "html_pages";
+            key: "bash_tool_purpose";
             label: string;
             description: string;
             valueConstraint: string;
@@ -292,6 +322,10 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
         surface: "specialized";
         owner: string;
     };
+    bin: {
+        surface: "specialized";
+        owner: string;
+    };
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export declare const SCOPE_CONFIG_KEYS: (keyof ScopeConfig)[];

package/dist/core/user-settings.js

@@ -1,4 +1,4 @@
-import { CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS } from '../types.js';
+import { CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES } from '../types.js';
 function cycleChoice(choices, current, delta) {
     const index = choices.indexOf(current);
     const start = index >= 0 ? index : 0;
@@ -158,7 +158,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
             valueConstraint: 'true|false',
             applies: 'Applies on the next turn end.',
             group: 'display',
-            order: 40,
+            order: 41,
             format: (config) => config.completion_bell ? 'on' : 'off',
             cycle: (config) => { config.completion_bell = !config.completion_bell; },
             setFromString: (config, raw) => {
@@ -176,7 +176,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
         setting: {
             key: 'whip_mode',
             label: 'Whip mode',
-            description: 'Play the whip animation when you send a prompt and when an automatically opened child viewer starts.',
+            description: 'Play the whip animation when you send a prompt and when a viewer opens for an agent with an initial prompt.',
             valueConstraint: 'true|false',
             applies: 'Applies on the next attach.',
             group: 'display',
@@ -192,7 +192,48 @@ export const CONFIG_SETTINGS_COVERAGE = {
             },
         },
     },
+    page_surface: {
+        surface: 'settings',
+        setting: {
+            key: 'page_surface',
+            label: 'Page human surface',
+            description: 'Prompt agents to use JSX pages by default for structured or interactive content shown to you.',
+            valueConstraint: 'true|false',
+            applies: 'Applies when human command help is assembled.',
+            group: 'display',
+            order: 37,
+            format: (config) => config.page_surface ? 'on' : 'off',
+            cycle: (config) => { config.page_surface = !config.page_surface; },
+            setFromString: (config, raw) => {
+                const value = booleanFromString(raw, 'page_surface');
+                if (typeof value === 'string')
+                    return value;
+                config.page_surface = value;
+                return null;
+            },
+        },
+    },
     whip_messages: { surface: 'specialized', owner: 'sys config set whip_messages' },
+    whip_message_mode: {
+        surface: 'settings',
+        setting: {
+            key: 'whip_message_mode',
+            label: 'Whip message',
+            description: 'What the whip action sends: a random line from whip_messages, or the fixed “Go faster”.',
+            valueConstraint: WHIP_MESSAGE_MODES.join('|'),
+            applies: 'Applies on the next attach.',
+            group: 'display',
+            order: 40,
+            format: (config) => config.whip_message_mode === 'go-faster' ? 'go faster' : 'random',
+            cycle: (config, delta) => { config.whip_message_mode = cycleChoice(WHIP_MESSAGE_MODES, config.whip_message_mode, delta); },
+            setFromString: (config, raw) => {
+                if (!WHIP_MESSAGE_MODES.includes(raw))
+                    return `whip_message_mode must be one of: ${WHIP_MESSAGE_MODES.join('|')}`;
+                config.whip_message_mode = raw;
+                return null;
+            },
+        },
+    },
     mouse_mode_default: {
         surface: 'settings',
         setting: {
@@ -254,23 +295,23 @@ export const CONFIG_SETTINGS_COVERAGE = {
             },
         },
     },
-    html_pages: {
+    bash_tool_purpose: {
         surface: 'settings',
         setting: {
-            key: 'html_pages',
-            label: 'HTML pages',
-            description: 'Teach agent help the HTML page-authoring dialect. Off keeps page authoring Markdown-only.',
+            key: 'bash_tool_purpose',
+            label: 'Bash purpose field',
+            description: 'Expose the optional purpose label to agents in the bash tool schema. Off removes the field without disabling the bash valve.',
             valueConstraint: 'true|false',
-            applies: 'Applies on the next help request.',
+            applies: 'Applies on the next node session.',
             group: 'display',
-            order: 70,
-            format: (config) => config.html_pages ? 'on' : 'off',
-            cycle: (config) => { config.html_pages = !config.html_pages; },
+            order: 25,
+            format: (config) => config.bash_tool_purpose ? 'on' : 'off',
+            cycle: (config) => { config.bash_tool_purpose = !config.bash_tool_purpose; },
             setFromString: (config, raw) => {
-                const value = booleanFromString(raw, 'html_pages');
+                const value = booleanFromString(raw, 'bash_tool_purpose');
                 if (typeof value === 'string')
                     return value;
-                config.html_pages = value;
+                config.bash_tool_purpose = value;
                 return null;
             },
         },
@@ -344,9 +385,10 @@ export const CONFIG_SETTINGS_COVERAGE = {
     modelRoutes: { surface: 'specialized', owner: 'Models route declarations' },
     modelRouting: { surface: 'specialized', owner: 'Models route declarations' },
     kinds: { surface: 'specialized', owner: 'Models tab and kind registry' },
-    page_components: { surface: 'specialized', owner: 'Page component catalog: product-registered page slot kinds' },
+    page_components: { surface: 'specialized', owner: 'Page component catalog: product-registered page component kinds' },
     remoteCanvas: { surface: 'specialized', owner: 'canvas config commands' },
     spawnEnv: { surface: 'specialized', owner: 'spawn environment allow-list' },
+    bin: { surface: 'specialized', owner: 'bare-binary contributions on every node PATH' },
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export const SCOPE_CONFIG_KEYS = Object.keys(CONFIG_SETTINGS_COVERAGE);

package/dist/core/worktree.d.ts

@@ -1,4 +1,3 @@
-import { type GitResult, type GitSyncOptions } from './git.js';
 import { type NodeMeta, type ManagedWorktree } from './canvas/index.js';
 export interface WorktreeCommandResult {
     ok: boolean;
@@ -23,32 +22,24 @@ export interface CloseManagedWorktreeResult {
     branch: string;
     worktree_path: string;
     landed_sha: string;
-    /** False when the landing happened but the worktree checkout could not be
-     *  removed automatically afterward — the close still counts as done (state is
-     *  closed, push-final is unblocked); `worktree_remove_error` carries the
-     *  manual cleanup note. */
+    /** Always false for a live caller: cleanup is deliberately pending until
+     * the caller exits and the reported manual command can safely remove it. */
     worktree_removed: boolean;
     worktree_remove_error?: string;
-    /** False when the landing happened but the local branch could not be deleted
-     *  afterward — same non-fatal treatment as worktree_removed. */
+    /** Always false while the pending-cleanup checkout has this branch checked out. */
     branch_deleted: boolean;
     branch_delete_error?: string;
 }
 export declare function closeManagedWorktree(nodeId: string): CloseManagedWorktreeResult;
-type WorktreeCleanupRunner = (args: string[], cwd: string, options: GitSyncOptions) => GitResult;
-/** Test seam for the bounded post-land cleanup regression. */
-export declare function setWorktreeCleanupRunnerForTest(runner?: WorktreeCleanupRunner): void;
 /** Recovery guidance for a vanished checkout whose refs do not prove that its
  * work is delivered. This deliberately never recommends `worktree close`:
  * that command cannot operate on the absent checkout. */
 export declare function missingWorktreeRecoveryHint(wt: ManagedWorktree): string;
 interface CleanEmptyProof {
-    /** The branch's HEAD SHA at the moment this was proven clean-and-contained
-     *  — the exact value the destructive delete must be conditioned on. */
+    /** The branch's HEAD SHA at the moment this was proven clean and contained
+     * in the current base. */
     branchSha: string;
-    /** The base branch tip the proof was made against; re-resolved and
-     *  re-checked immediately before the destructive delete, since the proof
-     *  and the delete are two different points in time. */
+    /** The current base tip, retained for race diagnostics. */
     baseSha: string;
 }
 /** Fix B's shared "nothing to land" test — the SAME clean-worktree definition
@@ -58,20 +49,11 @@ interface CleanEmptyProof {
  *  be a git-ancestor of (or equal to) the CURRENT tip of its recorded base
  *  branch — i.e. landing it would be a pure no-op. Any ambiguity (missing
  *  path, mid-rebase, wrong branch, an unresolvable base, or a real ancestry
- *  divergence) returns null: this function only ever proves "safe to drop"
+ *  divergence) returns null: this function only ever proves a no-op land
  *  when a live git check establishes it, never on a heuristic guess, so real
- *  unlanded work always falls through to the existing explicit-close guard.
- *  This proof is NOT itself the safety boundary — it only decides whether
- *  auto-drop is even attempted. `autoDropCleanManagedWorktreeLocked` below
- *  re-proves containment against the LIVE base immediately before the
- *  destructive delete, refuses outright if the checkout cannot be removed,
- *  and conditions the delete itself on BOTH `branchSha` and that same live
- *  base SHA via `bestEffortDeleteBranchWithBaseProof`'s atomic multi-ref
- *  transaction — those checks, not this one, are what close the TOCTOU gap.
- *  Exported (alongside
- *  `autoDropCleanManagedWorktreeLocked`) purely so regression tests can
- *  inject a race in the window between proving and cleanup; production code
- *  must always go through `autoDropCleanManagedWorktree`. */
+ *  unlanded work always falls through to the explicit-close guard. The locked
+ *  path re-checks this predicate before recording deferred cleanup; production
+ *  code must always go through `autoDropCleanManagedWorktree`. */
 export declare function proveCleanEmptyManagedWorktree(wt: ManagedWorktree): CleanEmptyProof | null;
 export interface AutoDroppedWorktree {
     node_id: string;
@@ -82,22 +64,10 @@ export interface AutoDroppedWorktree {
     branch_deleted: boolean;
     branch_delete_error?: string;
 }
-/** Exported (see `proveCleanEmptyManagedWorktree`'s doc) so regression tests
- *  can call it directly with a proof captured before injecting a race.
- *  Returns null — persisting NO state change — when the immediate base
- *  re-verification, the checkout removal, or the atomic base+branch delete
- *  refuses: the caller (`autoDropCleanManagedWorktree`, and `push final`
- *  above it) then falls through to the existing `open_managed_worktree`
- *  guard exactly as if this worktree had never looked droppable. In every
- *  refusal case the branch, and every commit reachable from it, is
- *  unconditionally preserved — that is the actual safety property this
- *  function guarantees. A checkout-removal refusal in particular must be
- *  treated as a full refusal, not a partial success: if the checkout cannot
- *  be removed (e.g. a file reappeared after the clean predicate ran), the
- *  branch is still checked out somewhere, so this function must never reach
- *  the ref-deletion transaction or mutate managed-worktree state — both the
- *  branch and the live checkout stay fully recoverable and the caller's
- *  `open_managed_worktree` guard fires. */
+/** Re-check a clean auto-drop before closing its record. `push final` runs
+ * inside the owner broker, so it has the same destructive-cwd boundary as
+ * explicit close: removal and branch deletion are deferred until that owner
+ * has exited. */
 export declare function autoDropCleanManagedWorktreeLocked(nodeId: string, wt: ManagedWorktree, proof: CleanEmptyProof): AutoDroppedWorktree | null;
 /** `push final`'s escape hatch: a managed worktree that has
  *  nothing to land is auto-dropped instead of blocking on an explicit
@@ -106,7 +76,7 @@ export declare function autoDropCleanManagedWorktreeLocked(nodeId: string, wt: M
  *  that never had anything to close in the first place (a read-only
  *  review node). Returns null and changes nothing when the worktree is not
  *  PROVABLY empty-and-clean by `proveCleanEmptyManagedWorktree`, OR when a
- *  concurrent mutation invalidates that proof before the destructive delete
+ *  concurrent mutation invalidates that proof before the record is closed
  *  (see `autoDropCleanManagedWorktreeLocked`); the caller's existing
  *  `open_managed_worktree` guard then still applies unchanged — real
  *  commits, real uncommitted changes, and a lost race all require the