@north-light/crouter 0.3.303 → 0.3.305

package/dist/commands/__tests__/seam/daemon-status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/seam/daemon-status.test.js

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+test('daemon status reports its failed probe without telling the operator to stop a live process', () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-daemon-status-'));
+    const pidfile = join(home, 'crtrd.pid');
+    const owner = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1_000)'], { stdio: 'ignore' });
+    try {
+        assert.ok(owner.pid !== undefined, 'fixture process has a pid');
+        writeFileSync(pidfile, String(owner.pid));
+        const result = spawnSync(process.execPath, [join(process.cwd(), 'dist', 'cli.js'), '--json', 'sys', 'daemon', 'status'], {
+            encoding: 'utf8',
+            env: { ...process.env, CRTR_HOME: home, CRTR_PIDFILE: pidfile, CRTR_NO_DAEMON_AUTOSTART: '1' },
+            timeout: 10_000,
+        });
+        assert.equal(result.status, 0, result.stderr);
+        const output = JSON.parse(result.stdout);
+        assert.deepEqual({ running: output.running, serving: output.serving }, { running: true, serving: false });
+        assert.match(output.probe_error ?? '', /ENOENT|ECONNREFUSED/);
+        assert.equal(output.next, undefined, 'a single failed health probe is not a reason to tell the operator to stop the owner');
+    }
+    finally {
+        owner.kill('SIGKILL');
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/commands/api-client.d.ts

@@ -38,9 +38,9 @@ export declare function readColdStartDiagnostic(): string | undefined;
  *  default: on a cold socket the injected `onColdSocket` hook fires
  *  `ensureDaemon()` (spawns crtrd detached via the branded host), then the
  *  client polls `/healthz` to a bounded deadline and retries once (the poll
- *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable — or
- *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
- *  §8). This is the ONLY CLI reference to `ensureDaemon`.
+ *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable, the
+ *  client surfaces the final observed transport failure. This is the ONLY CLI
+ *  reference to `ensureDaemon`.
  *
  *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
  *  returns immediately, so the client's OWN `/healthz` poll is the only

package/dist/commands/api-client.js

@@ -104,9 +104,9 @@ export function readColdStartDiagnostic() {
  *  default: on a cold socket the injected `onColdSocket` hook fires
  *  `ensureDaemon()` (spawns crtrd detached via the branded host), then the
  *  client polls `/healthz` to a bounded deadline and retries once (the poll
- *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable — or
- *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
- *  §8). This is the ONLY CLI reference to `ensureDaemon`.
+ *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable, the
+ *  client surfaces the final observed transport failure. This is the ONLY CLI
+ *  reference to `ensureDaemon`.
  *
  *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
  *  returns immediately, so the client's OWN `/healthz` poll is the only

package/dist/commands/memory/read.js

@@ -22,7 +22,8 @@ async function fetchSubject(nodeId) {
     if (nodeId === undefined)
         return null;
     try {
-        return await CrtrClient.forLocalSocket({ autostart: false }).nodeSubject(nodeId);
+        // This optional gate lookup must not hold a memory read while a daemon is unavailable: an absent subject simply skips gated docs.
+        return await CrtrClient.forLocalSocket({ autostart: false, coldStartPollWindowMs: 0 }).nodeSubject(nodeId);
     }
     catch {
         return null;

package/dist/commands/node/bash.js

@@ -117,7 +117,7 @@ const nodeBashKill = defineLeaf({
     tier: 'hidden',
     help: {
         name: 'node bash kill',
-        summary: 'terminate a background bash job’s process group and tell the owning node it was canceled',
+        summary: 'best-effort stop a background bash job and tell the owning node it was canceled',
         params: [
             { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
@@ -125,11 +125,11 @@ const nodeBashKill = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
-            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when at least one observed supervisor-tree process received SIGTERM.' },
         ],
         outputKind: 'object',
         effects: [
-            'Sends SIGTERM (then SIGKILL) to the job’s whole process group, stopping the command and anything it forked.',
+            'Snapshots the supervisor’s observable process tree, sends SIGTERM then SIGKILL to those processes, and cannot stop a descendant that detached and reparented before the snapshot.',
             'Records the job’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was stopped — which steers that node mid-turn.',
         ],
     },
@@ -159,8 +159,8 @@ const nodeBashKill = defineLeaf({
         if (stopped.kind === 'not-stoppable') {
             throw new InputError({
                 error: 'not_stoppable',
-                message: `job ${jobId} recorded no process group`,
-                next: `It started before crtr persisted one. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
+                message: `job ${jobId} recorded no trusted process identity`,
+                next: `It started before crtr persisted its supervisor identity. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
             });
         }
         await cliClient().sendMessage(node.node_id, {
@@ -169,7 +169,7 @@ const nodeBashKill = defineLeaf({
         });
         return { node_id: node.node_id, signaled: stopped.signaled };
     },
-    render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+    render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (no observed job process was still running)'}.`,
 });
 const nodeBashExtend = defineLeaf({
     name: 'extend',

package/dist/commands/node/create.js

@@ -82,8 +82,9 @@ function nodeNewParams() {
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
         { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
-        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent resident root with no parent or subscription. Mutually exclusive with --worktree.' },
+        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent root with no parent or subscription. Mutually exclusive with --worktree.' },
         { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Pass it ONLY when the user will open this node’s viewer pane and work with it back and forth; a child that only other nodes message stays terminal. Applies to managed children and roots; roots default to resident.' },
+        { kind: 'flag', name: 'terminal', type: 'bool', required: false, constraint: 'Birth the node as terminal: it finalizes when its work is done and leaves nothing wakeable behind. Only meaningful with --root, whose default is resident; managed children are already terminal. Pass it for bounded programmatic work no one will open a viewer on. Mutually exclusive with --resident.' },
         { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
         { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
         {
@@ -190,6 +191,10 @@ async function runNodeCreation(input) {
     const parent = input['parent'];
     const root = input['root'] === true;
     const resident = input['resident'] === true;
+    const terminal = input['terminal'] === true;
+    if (resident && terminal) {
+        throw new InputError({ error: 'lifecycle_conflict', message: '--resident and --terminal cannot both be passed', field: 'terminal', next: 'Pass the one birth lifecycle you want, or neither to take the default (resident for --root, terminal for a managed child).' });
+    }
     const worktreeBaseRaw = input['worktree'];
     if (worktreeBaseRaw !== undefined && worktreeBaseRaw.trim() === '') {
         throw new InputError({ error: 'worktree_base_required', message: '--worktree requires a base branch', field: 'worktree', next: 'Pass an existing local branch that landing can fast-forward.' });
@@ -257,6 +262,7 @@ async function runNodeCreation(input) {
         ...(root ? { root: true } : { parent: parentId ?? null }),
         ...(creator !== undefined ? { creator } : {}),
         ...(resident ? { root_lifecycle: 'resident' } : {}),
+        ...(terminal ? { root_lifecycle: 'terminal' } : {}),
         ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
         ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),
         ...(modelSpec !== undefined ? { model: modelSpec } : {}),

package/dist/commands/node/message.js

@@ -38,7 +38,7 @@ async function resolveMsgTarget(input, hasBody) {
 }
 function messageOutput() {
     return [
-        { name: 'revived', type: 'boolean', required: false, constraint: 'True when the target was revived.' },
+        { name: 'revived', type: 'boolean', required: false, constraint: 'True when this request synchronously revived the target; ordinary durable delivery to an active or idle dormant target queues lifecycle revival instead.' },
         { name: 'guidance', type: 'string', required: true, constraint: 'Immediate action confirmation.' },
     ];
 }
@@ -67,7 +67,7 @@ function messageRequestParams() {
         { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.', positionalStdinConflict: missingMessageTargetForBody },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
-        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier may revive a dormant target, because the request must be answered; deferred is rejected for that reason.' },
+        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier queues lifecycle revival for an active or idle dormant target because the request must be answered; deferred is rejected for that reason.' },
         { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers with \`crtr push result\` (or declines with \`crtr push result --decline "<reason>" --code <token>\`), then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
         { kind: 'flag', name: 'reopen', type: 'bool', required: false, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
@@ -125,7 +125,7 @@ const nodeMessageSend = defineLeaf({
         params: messageSendParams(),
         output: messageOutput(),
         outputKind: 'object',
-        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery may revive a dormant target; deferred waits for its next natural cycle.', '--reopen commits the target resident and clears any finalization latch before delivery, allowing it to take a new mandate; it is valid for live, parked, and finalized targets. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
+        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery queues lifecycle revival for an active or idle dormant target; deferred waits for its next natural cycle.', '--reopen commits the target resident and clears any finalization latch before delivery, allowing it to take a new mandate; it is valid for live, parked, and finalized targets. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
     },
     run: (input) => runMessageEngine(input),
     render: (r) => String(r['guidance']),

package/dist/commands/node/wait.js

@@ -46,7 +46,7 @@ function deadlineHeredoc(body, nodeId) {
     const lines = new Set(body.split('\n'));
     while (lines.has(delimiter))
         delimiter = `CRTR_DEADLINE_${++suffix}`;
-    return `crtr cron cancel "$CRTR_CRON_ID" && crtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
+    return `crtr cron cancel "$CRTR_CRON_ID"\ncrtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
 }
 const nodeWaitDeadline = defineLeaf({
     name: 'deadline',

package/dist/commands/node-worktree.js

@@ -85,7 +85,8 @@ const worktreeClose = defineLeaf({
             { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'Always false for an active caller: its checkout remains intact rather than being removed beneath the node.' },
             { name: 'worktree_remove_error', type: 'string', required: true, constraint: 'The named deferred-cleanup state and safe manual follow-up after the caller exits.' },
             { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'False while the deferred-cleanup checkout still has this branch checked out.' },
-            { name: 'branch_delete_error', type: 'string', required: true, constraint: 'The safe branch-cleanup follow-up after the checkout is removed.' }
+            { name: 'branch_delete_error', type: 'string', required: true, constraint: 'The safe branch-cleanup follow-up after the checkout is removed.' },
+            { name: 'base_checkout_stash', type: 'string', required: false, constraint: 'Present when conflicting base-checkout changes were retained in a stash; names the exact stash SHA and command required to recover them.' }
         ],
         outputKind: 'object',
         effects: [
@@ -116,6 +117,9 @@ const worktreeClose = defineLeaf({
         if (r['branch_deleted'] === false) {
             notes.push(String(r['branch_delete_error'] ?? `local branch ${branch} could not be deleted automatically.`));
         }
+        if (typeof r['base_checkout_stash'] === 'string') {
+            notes.push(`Warning: ${r['base_checkout_stash']}`);
+        }
         if (notes.length > 0)
             return `${base} Note: ${notes.join(' ')}`;
         return base;

package/dist/commands/sys/daemon.js

@@ -8,7 +8,7 @@
 // This subtree starts, checks, and stops the daemon process.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
-import { isDaemonServing, spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
+import { probeDaemonServing, spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
 import { isDaemonRunning, readPidfile, isPidAlive } from '../../daemon/pidfile.js';
 import { cliClient } from '../api-client.js';
 // daemon start
@@ -26,7 +26,7 @@ const daemonStart = defineLeaf({
             { name: 'existing_pid', type: 'number', required: false, constraint: 'PID of the already-running daemon (when started=false).' },
             { name: 'running', type: 'boolean', required: false, constraint: 'True only when a live pidfile owner does not serve its Unix API socket.' },
             { name: 'serving', type: 'boolean', required: false, constraint: 'False only when a live pidfile owner does not answer /healthz.' },
-            { name: 'next', type: 'string', required: false, constraint: 'Recovery instruction when running=true and serving=false.' },
+            { name: 'probe_error', type: 'string', required: false, constraint: 'The final /healthz probe failure when a live owner missed readiness.' },
         ],
         outputKind: 'object',
         effects: [
@@ -50,9 +50,9 @@ const daemonStatus = defineLeaf({
         params: [],
         output: [
             { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon pidfile owner is alive.' },
-            { name: 'serving', type: 'boolean', required: false, constraint: 'True when the live daemon answers /healthz; false when it does not.' },
+            { name: 'serving', type: 'boolean', required: false, constraint: 'True when the live daemon answers /healthz; false when one probe does not.' },
             { name: 'pid', type: 'number', required: false, constraint: 'PID of the running daemon.' },
-            { name: 'next', type: 'string', required: false, constraint: 'Recovery instruction when running=true and serving=false.' },
+            { name: 'probe_error', type: 'string', required: false, constraint: 'The failed /healthz observation when the live owner did not answer.' },
         ],
         outputKind: 'object',
         effects: ['Read-only: reads the pidfile, probes the pid, and requests /healthz without autostart.'],
@@ -62,15 +62,13 @@ const daemonStatus = defineLeaf({
         const running = pid !== null && isPidAlive(pid);
         if (!running)
             return { running: false };
-        const serving = await isDaemonServing();
-        return serving
-            ? { running: true, serving: true, pid }
-            : {
-                running: true,
-                serving: false,
-                pid,
-                next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
-            };
+        try {
+            await probeDaemonServing();
+            return { running: true, serving: true, pid };
+        }
+        catch (error) {
+            return { running: true, serving: false, pid, probe_error: error.message };
+        }
     },
 });
 // daemon restart

package/dist/core/__tests__/broker-stream-watchdog-floor.test.js

@@ -23,8 +23,6 @@ function projectionFor(session, generation) {
         notifyTurnAccepted: () => undefined,
         emitStartupMilestone: () => undefined,
         formatModelSpec: () => null,
-        refreshIntent: async () => false,
-        onRefreshIntentError: () => undefined,
     });
 }
 test('agent_start arms the provider watchdog before another engine event arrives', (t) => {

package/dist/core/__tests__/daemon-boot.test.js

@@ -294,7 +294,7 @@ test('verifyDaemonStartup throws after its tiny startup window expires', async (
         sleepMs: (ms) => {
             now += ms;
         },
-    }), /did not become ready within 25ms/);
+    }), /has no live pidfile owner/);
 });
 // REGRESSION (bug #102): the verifier polls with a real async sleep, NOT a
 // synchronous Atomics.wait, so the event loop stays free to dispatch the spawned

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -35,6 +35,7 @@ import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { DefaultResourceLoader, getAgentDir } from '@earendil-works/pi-coding-agent';
 import { MANAGED_PROVIDER_COOLING_DIAGNOSTIC } from '../../runtime/managed-provider-cooling.js';
+import { PROVIDER_FAILURE_DIAGNOSTIC } from '../../provider-failure.js';
 import registerCanvasBashValve, { createValveOperations } from '../../../pi-extensions/canvas-bash-valve.js';
 /** Test seams for prompt-scoped failures before session_start. The one-shot
  *  variant records its first failure per node so the next cycling retry can
@@ -1085,6 +1086,18 @@ class FakeSession {
                 // before the stophook sees agent_end while the run is active; the
                 // subscriber receives agent_settled after it clears.
                 this.streaming = true;
+                const diagnostics = [
+                    ...(cmd.deadline === undefined ? [] : [{
+                            type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
+                            timestamp: Date.now(),
+                            details: { rateLimitedUntil: cmd.deadline },
+                        }]),
+                    ...(cmd.providerFailure === undefined ? [] : [{
+                            type: PROVIDER_FAILURE_DIAGNOSTIC,
+                            timestamp: Date.now(),
+                            details: cmd.providerFailure,
+                        }]),
+                ];
                 const stopMessages = [
                     {
                         role: 'assistant',
@@ -1093,21 +1106,7 @@ class FakeSession {
                         // turn; the stophook classifies it for the active-fault marker.
                         // Forward it so a test can drive a CONNECTION stall faithfully.
                         ...(cmd.errorMessage === undefined ? {} : { errorMessage: cmd.errorMessage }),
-                        // A managed-provider cooling terminal carries the earliest pool
-                        // deadline as a typed diagnostic that survives verbatim into
-                        // agent_end.messages; the stophook reads it (extractCoolingDeadline)
-                        // to stamp retry.nextAt. Attached only when a test drives `deadline`.
-                        ...(cmd.deadline === undefined
-                            ? {}
-                            : {
-                                diagnostics: [
-                                    {
-                                        type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
-                                        timestamp: Date.now(),
-                                        details: { rateLimitedUntil: cmd.deadline },
-                                    },
-                                ],
-                            }),
+                        ...(diagnostics.length === 0 ? {} : { diagnostics }),
                         content: [{ type: 'text', text: cmd.text ?? '' }],
                     },
                 ];

package/dist/core/__tests__/helpers/harness.d.ts

@@ -101,6 +101,8 @@ export interface Harness {
     inbox(nodeId: string): InboxEntry[];
     injected(nodeId: string): Injected[];
     fakeCmd(nodeId: string, cmd: Record<string, unknown>): void;
+    /** Stop only this harness's API server to exercise a broker daemon-read failure. */
+    stopApiServer(): Promise<void>;
     dialogResults(nodeId: string): {
         resolved: unknown;
         ms: number;

package/dist/core/__tests__/helpers/harness.js

@@ -637,6 +637,15 @@ export async function createHarness(opts = {}) {
         fakeCmd(nodeId, cmd) {
             sendCmd(nodeId, cmd);
         },
+        async stopApiServer() {
+            try {
+                apiServerProc.kill('SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+            await waitFor(() => apiServerProc.exitCode === null ? null : true, { label: 'harness API server exit' });
+        },
         dialogResults(nodeId) {
             return readLines(join(nodeDir(nodeId), 'fake-pi.dialog.jsonl'))
                 .map((l) => {

package/dist/core/__tests__/integration/tmux-surface.test.js

@@ -275,3 +275,56 @@ test('tmux installer reads pair-array manifests and replaces owned pairs', (t) =
         isolatedTmux(socket, ['kill-server']);
     }
 });
+// Regression: a passthrough wrapper survives the user re-sourcing their own tmux
+// config over it. Crouter wraps an occupied root key and fingerprints the result;
+// every `source-file` (and every fresh tmux server) re-installs the user's own
+// bind-key line over that wrapper. Reading the mismatch as a deliberate rebind
+// relinquished the key permanently, so the attach viewer silently stopped
+// receiving its own scroll keys and no reconciliation ever restored them.
+test('tmux passthrough re-wraps a re-sourced config but yields to a real rebind', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-passthrough-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, '-f', '/dev/null', 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socket = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' }).stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    process.env['TMUX'] = `${socket},1,0`;
+    const userBinding = ['bind-key', '-T', 'root', 'C-k', 'copy-mode', '-e'];
+    const bindings = resolveKeybindings({ 'crtr.attach.scroll.up': ['ctrl+k'] });
+    const passthrough = ['crtr.attach.scroll.up'];
+    try {
+        isolatedTmux(socket, userBinding);
+        const original = tmuxBinding(socket, 'root', 'C-k');
+        assert.match(original ?? '', /copy-mode/);
+        const wrapped = installTmuxBindings(bindings, passthrough);
+        assert.equal(wrapped.ok, true, JSON.stringify(wrapped.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'C-k') ?? '', /@crtr_attach/, 'occupied key should be wrapped');
+        // The user reloads their tmux config: their own line lands over the wrapper.
+        isolatedTmux(socket, userBinding);
+        assert.equal(tmuxBinding(socket, 'root', 'C-k'), original);
+        const resourced = installTmuxBindings(bindings, passthrough);
+        assert.equal(resourced.ok, true, JSON.stringify(resourced.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'C-k') ?? '', /@crtr_attach/, 're-sourced config should be re-wrapped, not relinquished');
+        // A line matching neither the wrapper nor the recorded original is a real
+        // rebind and stays the user's, here and on every later reconciliation.
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'C-k', 'display-message', 'user-owned']);
+        for (const pass of ['first', 'second']) {
+            const rebound = installTmuxBindings(bindings, passthrough);
+            assert.equal(rebound.ok, true, JSON.stringify(rebound.diagnostics));
+            const live = tmuxBinding(socket, 'root', 'C-k') ?? '';
+            assert.match(live, /user-owned/, `${pass} reconciliation should leave a real rebind alone`);
+            assert.doesNotMatch(live, /@crtr_attach/);
+        }
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});

package/dist/core/__tests__/integration/worktree-land.test.js

@@ -10,6 +10,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { gitSync } from '../../git.js';
 import { createManagedWorktree, closeManagedWorktree, managedWorktreePath, rollbackManagedWorktree } from '../../worktree.js';
+import { closeManagedWorktreeAsync } from '../../worktree-close.js';
 import { reconcileManagedWorktree } from '../../worktree-sweep.js';
 import { createNode, getNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
@@ -223,6 +224,55 @@ test('closeManagedWorktree fast-forwards local main to the worktree tip without
     const originMainAfter = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
     assert.equal(originMainAfter, originMainBefore, 'origin/main must not move — landing is local-only');
 });
+test('async close leaves an upstream-contained tip and a diverged local base byte-for-byte unchanged (#958)', async () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-contained-close-'));
+    const remote = mkdtempSync(join(tmpdir(), 'crtr-worktree-contained-close-remote-'));
+    try {
+        run(['init', '-b', 'main'], repo);
+        run(['config', 'user.email', 'test@example.com'], repo);
+        run(['config', 'user.name', 'Test'], repo);
+        writeFileSync(join(repo, 'README.md'), 'initial\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'initial'], repo);
+        run(['init', '--bare'], remote);
+        run(['remote', 'add', 'origin', remote], repo);
+        run(['push', '-u', 'origin', 'main'], repo);
+        const nodeId = 'wt-contained-diverged-base';
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+        writeFileSync(join(wt.path, 'delivered.txt'), 'already delivered\n');
+        run(['add', '.'], wt.path);
+        run(['commit', '-m', 'delivered work'], wt.path);
+        const deliveredHead = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+        run(['push', 'origin', `${wt.branch}:main`], wt.path);
+        run(['fetch', 'origin'], repo);
+        writeFileSync(join(repo, 'local-only.txt'), 'must not receive a replay\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'independent local base work'], repo);
+        const before = {
+            childHead: gitSync(['rev-parse', 'HEAD'], wt.path).stdout,
+            baseRef: gitSync(['rev-parse', 'refs/heads/main'], repo).stdout,
+            baseHead: gitSync(['rev-parse', 'HEAD'], repo).stdout,
+            status: gitSync(['status', '--porcelain=v1'], repo).stdout,
+            worktree: gitSync(['worktree', 'list', '--porcelain'], repo).stdout,
+            index: readFileSync(join(repo, '.git', 'index')),
+        };
+        const result = await closeManagedWorktreeAsync(nodeId);
+        assert.equal(result.landed_sha, deliveredHead);
+        assert.deepEqual({
+            childHead: gitSync(['rev-parse', 'HEAD'], wt.path).stdout,
+            baseRef: gitSync(['rev-parse', 'refs/heads/main'], repo).stdout,
+            baseHead: gitSync(['rev-parse', 'HEAD'], repo).stdout,
+            status: gitSync(['status', '--porcelain=v1'], repo).stdout,
+            worktree: gitSync(['worktree', 'list', '--porcelain'], repo).stdout,
+            index: readFileSync(join(repo, '.git', 'index')),
+        }, before, 'a delivered child must not rebase or move the divergent local base');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(remote, { recursive: true, force: true });
+    }
+});
 test('custom local base is recorded and fast-forwarded without touching main or origin', () => {
     const nodeId = 'wt-custom-base';
     run(['branch', 'feature/custom-base'], sourceDir);