@north-light/crouter 0.3.303 → 0.3.305

package/dist/core/runtime/kickoff.js

@@ -99,6 +99,12 @@ export function listContextDir(nodeId) {
         return [];
     return readdirSync(dir).sort();
 }
+/** A retained report proves this node has already done work. It must restart
+ * from current context, never by replaying its birth mandate. */
+export function hasRetainedReports(nodeId) {
+    const dir = reportsDir(nodeId);
+    return existsSync(dir) && readdirSync(dir).some((file) => file.endsWith('.md'));
+}
 /** Capture revive bearings for `meta`: read the pending yield note, advance the
  *  feed cursor past unread reports, and capture external persona framing.
  *  Revive paths call it once, then pass the result to the pure kickoff builder. */
@@ -113,9 +119,23 @@ export function drainBearings(meta) {
     let unreadDigest = null;
     if (entries.length > 0) {
         writeCursor(nodeId, entries.at(-1).entry_id);
-        // The launch-argv seam carries one message, so a mixed batch's split parts
-        // join back into this block's body; the kickoff is one whole envelope.
-        unreadDigest = coalesce(entries).map((delivery) => delivery.text).join('\n\n');
+        // The launch argv carries one message. Keep coalescing card-free runs, but
+        // start a new batch at each entry with cards. A batch's cards are therefore
+        // directly ahead of its coalesced text, so they cannot leap an earlier body.
+        const cardsFor = (entry) => {
+            const cards = entry.data?.['cards'];
+            return Array.isArray(cards) ? cards.filter((card) => typeof card === 'string') : [];
+        };
+        const segments = [];
+        for (const entry of entries) {
+            if (cardsFor(entry).length > 0 || segments.length === 0)
+                segments.push([]);
+            segments.at(-1).push(entry);
+        }
+        unreadDigest = segments.map((segment) => [
+            ...cardsFor(segment[0]),
+            coalesce(segment).map((delivery) => delivery.text).join('\n\n'),
+        ].join('\n\n')).join('\n\n');
     }
     const drift = personaDrift(nodeId);
     const driftGuidance = drift?.guidance === undefined || drift.guidance === ''
@@ -261,7 +281,7 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
     // (audit 2026-06-09, Bug 4: mq45b6ch-9ecc2f03), whose only mandate on disk IS
     // the goal. Surface the goal then. When a roadmap exists it stays the sole
     // source of truth (the goal is usually stale by comparison) — unchanged.
-    if (!hasRoadmapBody) {
+    if (!hasRoadmapBody && !hasRetainedReports(nodeId)) {
         const goal = readGoal(nodeId);
         if (goal !== null && goal.trim() !== '') {
             parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);

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

@@ -25,14 +25,14 @@ export declare function commitReopen(nodeId: string, expectedFinalReport: string
  * unlatched node is valid here — it still becomes resident. Writing lifecycle
  * first leaves a failed latch CAS with the canonical-final pointer intact.
  * Both writes finish before either delivery channel begins. */
-export declare function commitReopenResident(nodeId: string): void;
+export declare function commitReopenResident(nodeId: string, expectedFinalReport?: string): string | null;
 /** Convenience wrapper for a doorway with NO intervening fallible step between
  *  the gate check and the reopen clear (`node lifecycle revive` has nothing
  *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
  *  clears in one call.
  *
  *  - `reopen` false + latched → throws `node_finalized`.
- *  - `reopen` true + latched → CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + latched → makes the node resident and CAS-clears the latch (side effect) and returns.
  *  - `reopen` true + not latched → throws `not_finalized`.
  *  - `reopen` false + not latched → no-op (the common case). */
 export declare function assertReopenGate(nodeId: string, reopen: boolean): void;

package/dist/core/runtime/reopen.js

@@ -104,7 +104,7 @@ export function commitReopen(nodeId, expectedFinalReport) {
  * unlatched node is valid here — it still becomes resident. Writing lifecycle
  * first leaves a failed latch CAS with the canonical-final pointer intact.
  * Both writes finish before either delivery channel begins. */
-export function commitReopenResident(nodeId) {
+export function commitReopenResident(nodeId, expectedFinalReport) {
     const finalReport = currentFinalReport(nodeId);
     updateNode(nodeId, { lifecycle: 'resident' });
     // A reopened node that is still parked in a terminal status has to come back
@@ -116,7 +116,8 @@ export function commitReopenResident(nodeId) {
         transition(nodeId, 'revive');
     }
     if (finalReport !== null)
-        commitReopen(nodeId, finalReport);
+        commitReopen(nodeId, expectedFinalReport ?? finalReport);
+    return finalReport;
 }
 /** Convenience wrapper for a doorway with NO intervening fallible step between
  *  the gate check and the reopen clear (`node lifecycle revive` has nothing
@@ -124,12 +125,13 @@ export function commitReopenResident(nodeId) {
  *  clears in one call.
  *
  *  - `reopen` false + latched → throws `node_finalized`.
- *  - `reopen` true + latched → CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + latched → makes the node resident and CAS-clears the latch (side effect) and returns.
  *  - `reopen` true + not latched → throws `not_finalized`.
  *  - `reopen` false + not latched → no-op (the common case). */
 export function assertReopenGate(nodeId, reopen) {
     if (reopen) {
-        commitReopen(nodeId, assertFinalizedForReopen(nodeId));
+        const expectedFinalReport = assertFinalizedForReopen(nodeId);
+        commitReopenResident(nodeId, expectedFinalReport);
         return;
     }
     assertNotFinalized(nodeId);

package/dist/core/runtime/revive.js

@@ -31,7 +31,7 @@ import { isParked, transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
 import { InputError } from '../io.js';
 import { buildPiArgv } from './launch.js';
-import { buildReviveKickoff, drainBearings, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
+import { buildReviveKickoff, drainBearings, hasRetainedReports, readGoal, readYieldMessage, RUNTIME_RESTART_CONTINUATION } from './kickoff.js';
 import { readRoadmap } from './roadmap.js';
 import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { headlessBrokerHost } from './host.js';
@@ -105,7 +105,7 @@ function resumableSessionArgs(nodeId, meta, resume) {
 }
 // Return type
 /** A relaunch that has NO transcript to resume or branch from, and no durable
- *  work state on disk (no roadmap, no yield note), is not a revive at all — the
+ *  work state on disk (no roadmap, yield note, or retained report), is not a revive at all — the
  *  node never got a conversation off the ground, so there is no "previous
  *  in-memory context" that was lost. pi does not write a `.jsonl` until the
  *  first turn, so an idle node the user never messaged is the common case: it
@@ -116,7 +116,7 @@ function resumableSessionArgs(nodeId, meta, resume) {
  *  a BIRTH instead: replay the spawn mandate when it has one, or boot with no
  *  prompt at all and leave it sitting exactly where it was. */
 function isUnstartedBirth(nodeId) {
-    return readRoadmap(nodeId) === null && readYieldMessage(nodeId) === null;
+    return readRoadmap(nodeId) === null && readYieldMessage(nodeId) === null && !hasRetainedReports(nodeId);
 }
 /** Whether a fresh context window would have anything on disk to stand on: a
  *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse

package/dist/core/runtime/spawn.js

@@ -15,7 +15,7 @@ import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId
 import { resolveProfileOperand } from '../profiles/manifest.js';
 import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
-import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
+import { createManagedWorktreeAsync, rollbackManagedWorktreeAsync } from '../worktree-mutation-async.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
 import { appendSituationalContext, formatSituationalProse } from './situational-context.js';
@@ -25,7 +25,6 @@ import { encodeKickoffOrigin, KICKOFF_ORIGIN_ENV } from './stamp/protocol.js';
 import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid, setFrozen } from '../canvas/index.js';
 import { boundFleet, brokerThresholdsForDaemon } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
-import { jobDir } from '../canvas/paths.js';
 import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
 import { transition } from './lifecycle.js';
@@ -259,7 +258,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     let spawnCwd = opts.cwd;
     try {
         if (wantsWorktree) {
-            managedWorktree = createManagedWorktree(opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase);
+            managedWorktree = await createManagedWorktreeAsync(opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase);
             spawnCwd = managedWorktree.path;
         }
         // Spine: a managed child reports up to its spawner (has a manager); an
@@ -409,7 +408,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         if (placed.pid === null) {
             const error = new Error(`broker host returned no pid for ${meta.node_id}`);
             transition(meta.node_id, 'crash', { reason: 'launch_failed', outcome: launchFailureOutcome(error) });
-            throw brokerLaunchFailed(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`, `Inspect the broker log for the underlying cause (${jobDir(meta.node_id)}/broker.log) and verify the pi engine can start in this environment.`);
+            throw brokerLaunchFailed(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`, `Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then verify the pi engine can start in this environment.`);
         }
         recordPid(meta.node_id, placed.pid);
         // A root created through `node new --root` must accept viewers before the
@@ -425,7 +424,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 ? `the root broker ${meta.node_id} could not start — ${why}`
                 : `the root broker ${meta.node_id} never bound its view socket — it was not started.`, why !== null
                 ? 'Resolve the cause named above, then retry.'
-                : `The broker engine exited before binding its view socket. Inspect ${jobDir(meta.node_id)}/broker.log for the underlying cause (a missing dependency, model auth, or a crash), then retry.`);
+                : `The broker engine exited before binding its view socket. Inspect canonical event diagnostics with \`crtr sys logs --node ${meta.node_id}\`, then retry.`);
         }
         // A --root opens NO viewer from here. spawnChild runs daemon-side only, and
         // the daemon is paneless by construction (manage.ts strips TMUX/TMUX_PANE
@@ -484,7 +483,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // worktree — the node stays alive (crashed, if the launch itself failed)
         // with its worktree intact rather than pinned to a deleted path.
         if (managedWorktree !== undefined && nodeId !== undefined && getNode(nodeId) === null) {
-            rollbackManagedWorktree(managedWorktree);
+            await rollbackManagedWorktreeAsync(managedWorktree);
         }
         throw err;
     }

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

@@ -586,14 +586,25 @@ function reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
         }
     }
     // Restore every wrapper crouter still owns before the ordinary binding sweep.
-    // A live line that differs from the fingerprint is a user's later rebind: it
-    // is protected from this and every later reconciliation until they toggle the
-    // passthrough preference off and on again.
+    // A live line that matches neither the fingerprint nor the original crouter
+    // recorded is a user's later rebind: it is protected from this and every later
+    // reconciliation until they toggle the passthrough preference off and on again.
+    //
+    // A live line equal to the ORIGINAL is not a rebind. It is the user's own tmux
+    // config re-sourced over the wrapper, which every `source-file` and every fresh
+    // tmux server does. Relinquishing there disarmed passthrough silently and
+    // permanently for anyone whose config binds a key crouter wraps, so that case
+    // falls through with nothing to restore — the wrap pass below re-reads the live
+    // line as the original and wraps it again. It also releases a key already stuck
+    // relinquished: matching the recorded original is proof the user did not rebind
+    // it to something of their own.
     const protectedRootKeys = new Set();
     const wrappers = [];
     for (const prior of manifest.wrappers) {
         const desired = desiredWrappers.get(prior.key);
         const live = bindingAt(ROOT_TABLE, prior.key);
+        if (live !== null && live === prior.original)
+            continue;
         if (prior.state === 'relinquished' || live !== prior.wrapper) {
             protectedRootKeys.add(prior.key);
             if (desired !== undefined) {

package/dist/core/termrender/version.d.ts

@@ -1 +1 @@
-export declare const TERMRENDER_VERSION = "4.12.11";
+export declare const TERMRENDER_VERSION = "4.12.12";

package/dist/core/termrender/version.js

@@ -1 +1 @@
-export const TERMRENDER_VERSION = '4.12.11';
+export const TERMRENDER_VERSION = '4.12.12';

package/dist/core/worktree-close.d.ts

@@ -0,0 +1,4 @@
+import { type CloseManagedWorktreeResult } from './worktree.js';
+/** Async daemon executor for explicit close. The lock wait and every Git
+ * subprocess yield to the daemon event loop. */
+export declare function closeManagedWorktreeAsync(nodeId: string): Promise<CloseManagedWorktreeResult>;

package/dist/core/worktree-close.js

@@ -0,0 +1,228 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getNode, updateNode } from './canvas/index.js';
+import { withExclusiveDirectoryLockAsync } from './exclusive-lock.js';
+import { gitAsync } from './git.js';
+import { proveBranchContained } from './worktree-containment.js';
+import { concludeAbsentManagedWorktreeAsync } from './worktree-mutation-async.js';
+import { parseStatusPorcelain, planLandIntoCheckout } from './worktree-landing.js';
+import { WORKTREE_LOCK_WAIT_MS, checkoutPathForBranchInList, missingWorktreeRecoveryHint, persistClosedWorktreeState, samePath, worktreeLockPathForCommonDir, WorktreeError } from './worktree.js';
+import { shellQuote } from '../shared/shell-quote.js';
+function detailOf(result) {
+    return (result.stderr.trim() || result.stdout.trim()).trim();
+}
+async function runGit(cwd, args, code, next) {
+    const result = await gitAsync(args, cwd);
+    if (result.status !== 0)
+        throw new WorktreeError(code, `git ${args.join(' ')} failed`, next, detailOf(result));
+    return result.stdout.trim();
+}
+async function commonGitDir(cwd) {
+    const output = await runGit(cwd, ['rev-parse', '--git-common-dir'], 'git_common_dir_failed', 'Inspect the repository git metadata, then retry.');
+    return realpathSync(resolve(cwd, output));
+}
+async function resolveLandableBase(cwd, baseRef) {
+    const ref = `refs/heads/${baseRef}`;
+    const exists = await gitAsync(['show-ref', '--verify', '--quiet', ref], cwd);
+    if (exists.status === 1 && exists.executionFailed !== true) {
+        throw new WorktreeError('missing_base_branch', `managed worktree base '${baseRef}' does not name an existing local branch`, 'The base must be a local branch that landing can fast-forward — freshen your local branch from origin first (rebase-not-merge), then base on it.');
+    }
+    if (exists.status !== 0) {
+        const execution = exists.processError === undefined ? '' : `\nprocess error: ${exists.processError}`;
+        throw new WorktreeError('base_branch_inspection_failed', `could not inspect local base branch '${baseRef}' (git show-ref exited with status ${exists.status})`, 'Inspect the repository and its Git metadata, then retry.', `status: ${exists.status}\nstderr: ${exists.stderr.trim() || '<empty>'}${execution}`);
+    }
+    return runGit(cwd, ['rev-parse', '--verify', ref], 'base_branch_resolve_failed', 'Inspect the local base branch, then retry.');
+}
+async function rebaseInProgress(cwd) {
+    for (const path of ['rebase-merge', 'rebase-apply']) {
+        const gitPath = await runGit(cwd, ['rev-parse', '--git-path', path], 'git_path_failed', 'Inspect the worktree manually, then retry.');
+        if (existsSync(gitPath))
+            return true;
+    }
+    return false;
+}
+async function registeredWorktree(cwd, path, branch) {
+    const list = await gitAsync(['worktree', 'list', '--porcelain'], cwd);
+    if (list.status !== 0)
+        return false;
+    let current = null;
+    for (const line of list.stdout.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (current !== null && samePath(current, path) && line === `branch refs/heads/${branch}`)
+            return true;
+    }
+    return false;
+}
+function deferredCleanupResult(wt) {
+    return {
+        worktree_removed: false,
+        worktree_remove_error: `cleanup pending: the caller checkout at ${wt.path} remains intact. After its node exits, run \`git -C ${shellQuote(wt.repo_root)} worktree remove ${shellQuote(wt.path)}\` after confirming it is safe to delete.`,
+        branch_deleted: false,
+        branch_delete_error: `cleanup pending: local branch ${wt.branch} remains checked out at ${wt.path}; delete it only after that checkout is removed and its landed commit is still contained in ${wt.base_ref}.`,
+    };
+}
+function recordBlockedLandIntent(nodeId, blocked) {
+    const current = getNode(nodeId)?.managed_worktree;
+    if (current === undefined || current === null || current.state !== 'open')
+        return;
+    const { sweep: _sweep, ...retained } = current;
+    updateNode(nodeId, { managed_worktree: { ...retained, land_intent: { at: new Date().toISOString(), blocked } } });
+}
+async function dropStashIfStillTip(cwd, stashSha) {
+    const tip = await gitAsync(['rev-parse', '--verify', '--quiet', 'refs/stash'], cwd);
+    if (tip.status === 0 && tip.stdout.trim() === stashSha)
+        await gitAsync(['stash', 'drop'], cwd);
+}
+async function landIntoBaseCheckout(baseCheckout, branch, baseSha, landedSha) {
+    const status = await gitAsync(['status', '--porcelain'], baseCheckout);
+    if (status.status !== 0)
+        return { ok: false, detail: detailOf(status) };
+    const diff = await gitAsync(['diff', '--name-only', baseSha, landedSha], baseCheckout);
+    if (diff.status !== 0)
+        return { ok: false, detail: detailOf(diff) };
+    const incoming = diff.stdout.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    const plan = planLandIntoCheckout(parseStatusPorcelain(status.stdout), incoming);
+    if (plan.kind === 'refuse')
+        return { ok: false, detail: `untracked files in ${baseCheckout} would be overwritten by the incoming commits: ${plan.collisions.join(', ')}` };
+    const merge = async () => {
+        const result = await gitAsync(['merge', '--ff-only', landedSha], baseCheckout);
+        return result.status === 0 ? { ok: true } : { ok: false, detail: detailOf(result) };
+    };
+    if (plan.kind === 'direct')
+        return merge();
+    const before = await gitAsync(['rev-parse', '--verify', '--quiet', 'refs/stash'], baseCheckout);
+    const beforeSha = before.status === 0 ? before.stdout.trim() : null;
+    const pushed = await gitAsync(['stash', 'push', '--message', `crtr landing ${branch}`], baseCheckout);
+    if (pushed.status !== 0)
+        return { ok: false, detail: detailOf(pushed) };
+    const after = await gitAsync(['rev-parse', '--verify', '--quiet', 'refs/stash'], baseCheckout);
+    const stashSha = after.status === 0 ? after.stdout.trim() : null;
+    if (stashSha === null || stashSha === beforeSha)
+        return merge();
+    const recovery = `local changes from ${baseCheckout} are retained in stash ${stashSha}; recover them with \`git -C ${shellQuote(baseCheckout)} stash apply ${stashSha}\` and resolve any conflict.`;
+    const landed = await merge();
+    if (!landed.ok) {
+        if ((await gitAsync(['stash', 'apply', stashSha], baseCheckout)).status === 0) {
+            await dropStashIfStillTip(baseCheckout, stashSha);
+            return landed;
+        }
+        return { ok: false, detail: `${landed.detail}\n${recovery}` };
+    }
+    if ((await gitAsync(['stash', 'apply', stashSha], baseCheckout)).status === 0) {
+        await dropStashIfStillTip(baseCheckout, stashSha);
+        return { ok: true };
+    }
+    await gitAsync(['reset', '--hard', landedSha], baseCheckout);
+    return { ok: true, stash: `the shared base checkout was reset to landed commit ${landedSha} because local changes conflicted with it. ${recovery}` };
+}
+async function closeLocked(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new WorktreeError('unknown_node', `unknown node: ${nodeId}`, 'Run this from a live node, or pass a real node id once that command supports it.');
+    const wt = node?.managed_worktree?.state === 'open' ? node.managed_worktree : null;
+    if (wt === null)
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to close for this node.');
+    if (!existsSync(wt.path))
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, missingWorktreeRecoveryHint(wt));
+    if (await rebaseInProgress(wt.path))
+        throw new WorktreeError('rebase_in_progress', 'this managed worktree is mid-rebase', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`.`);
+    const status = await runGit(wt.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+    if (status !== '')
+        throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit the work in ${wt.path}, then rerun \`crtr node worktree close\`.`);
+    const branch = await runGit(wt.path, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+    const head = await runGit(wt.path, ['rev-parse', 'HEAD'], 'landed_sha_failed', 'Inspect the worktree checkout manually, then rerun `crtr node worktree close`.');
+    if (branch !== wt.branch) {
+        const recorded = await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], wt.path);
+        if (recorded.status === 0 || branch === 'HEAD' || !(await registeredWorktree(wt.repo_root, wt.path, branch))) {
+            throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${branch === 'HEAD' ? 'detached HEAD' : branch})`, `Inspect ${wt.path}, then rerun \`crtr node worktree close\`.`);
+        }
+        if (await proveBranchContained(wt.path, wt, head) === null) {
+            throw new WorktreeError('branch_moved_unlanded', `managed worktree's recorded branch ${wt.branch} no longer exists; its checkout is now on ${branch} at ${head}, which carries content local base branch '${wt.base_ref}' does not yet contain`, `Land or push ${branch} through its own workflow before closing.`);
+        }
+        const commonDir = await commonGitDir(wt.path);
+        if (!(await registeredWorktree(wt.repo_root, wt.path, branch)) || (await runGit(wt.path, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.')) !== branch || (await runGit(wt.path, ['rev-parse', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.')) !== head) {
+            throw new WorktreeError('wrong_branch', `managed worktree at ${wt.path} changed while closing`, `Inspect ${wt.path}, then rerun \`crtr node worktree close\`.`);
+        }
+        persistClosedWorktreeState(nodeId, { ...wt, disposal: { observed_branch: branch, observed_sha: head, common_dir: commonDir, authorized: new Date().toISOString() } }, 'pending');
+        return { node_id: nodeId, branch, worktree_path: wt.path, landed_sha: head, ...deferredCleanupResult(wt), branch_delete_error: `${branch} is not a crtr-managed branch and will never be deleted automatically; it is preserved once the checkout above is removed.` };
+    }
+    // Decide whether landing remains before resolving a destination. A diverged
+    // local base cannot replay history that the recorded upstream already has.
+    if (await proveBranchContained(wt.path, wt, head) !== null) {
+        persistClosedWorktreeState(nodeId, wt, 'pending');
+        return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, landed_sha: head, ...deferredCleanupResult(wt) };
+    }
+    let baseSha;
+    try {
+        baseSha = await resolveLandableBase(wt.path, wt.base_ref);
+    }
+    catch (error) {
+        if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch' || head !== wt.base_sha)
+            throw error;
+        persistClosedWorktreeState(nodeId, wt, 'pending');
+        return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, landed_sha: wt.base_sha, ...deferredCleanupResult(wt) };
+    }
+    const rebase = await gitAsync(['rebase', baseSha], wt.path);
+    if (rebase.status !== 0)
+        throw new WorktreeError('rebase_failed', `rebase onto local base branch '${wt.base_ref}' did not complete`, `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`.`, detailOf(rebase));
+    const landedSha = await runGit(wt.path, ['rev-parse', 'HEAD'], 'landed_sha_failed', 'Inspect the worktree checkout manually, then rerun `crtr node worktree close`.');
+    const blocked = (message, next, detail) => {
+        recordBlockedLandIntent(nodeId, message);
+        return new WorktreeError('land_base_failed', message, next, detail);
+    };
+    const fastForward = await gitAsync(['merge-base', '--is-ancestor', baseSha, landedSha], wt.path);
+    if (fastForward.status !== 0)
+        throw blocked(`rebased worktree is not a fast-forward of local base branch '${wt.base_ref}'`, 'Ask the user how to land this managed worktree.', detailOf(fastForward));
+    const list = await runGit(wt.path, ['worktree', 'list', '--porcelain'], 'worktree_list_failed', 'Inspect the repository worktrees manually, then retry.');
+    const baseCheckout = checkoutPathForBranchInList(list, wt.base_ref);
+    let stashNote;
+    if (baseCheckout !== null) {
+        const checkoutHead = await gitAsync(['rev-parse', 'HEAD'], baseCheckout);
+        if (checkoutHead.status !== 0 || checkoutHead.stdout.trim() !== baseSha)
+            throw blocked(`local base branch '${wt.base_ref}' changed while this worktree was closing`, `Reconcile the base checkout at ${baseCheckout}, then rerun \`crtr node worktree close\`.`, checkoutHead.status !== 0 ? detailOf(checkoutHead) : `expected ${baseSha}, found ${checkoutHead.stdout.trim()}`);
+        const landed = await landIntoBaseCheckout(baseCheckout, wt.branch, baseSha, landedSha);
+        if (!landed.ok)
+            throw blocked(`could not fast-forward local base branch '${wt.base_ref}' to this worktree`, `Local base branch '${wt.base_ref}' is checked out at ${baseCheckout} in a state that blocks a fast-forward.`, landed.detail);
+        stashNote = landed.stash;
+    }
+    else {
+        const update = await gitAsync(['update-ref', `refs/heads/${wt.base_ref}`, landedSha, baseSha], wt.path);
+        if (update.status !== 0)
+            throw blocked(`could not fast-forward local base branch '${wt.base_ref}' to this worktree`, 'Ask the user how to land this managed worktree.', detailOf(update));
+    }
+    persistClosedWorktreeState(nodeId, wt, 'pending');
+    return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, landed_sha: landedSha, ...deferredCleanupResult(wt), ...(stashNote === undefined ? {} : { base_checkout_stash: stashNote }) };
+}
+/** Async daemon executor for explicit close. The lock wait and every Git
+ * subprocess yield to the daemon event loop. */
+export async function closeManagedWorktreeAsync(nodeId) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open')
+        return closeLocked(nodeId);
+    if (!existsSync(wt.path)) {
+        const conclusion = await concludeAbsentManagedWorktreeAsync(nodeId);
+        if (conclusion !== null) {
+            return {
+                node_id: nodeId,
+                branch: conclusion.dropped.branch,
+                worktree_path: conclusion.dropped.worktree_path,
+                landed_sha: conclusion.landedSha,
+                worktree_removed: true,
+                branch_deleted: conclusion.dropped.branch_deleted,
+                ...(conclusion.dropped.branch_delete_error === undefined ? {} : { branch_delete_error: conclusion.dropped.branch_delete_error }),
+            };
+        }
+    }
+    const current = getNode(nodeId)?.managed_worktree;
+    if (current === undefined || current === null || current.state !== 'open')
+        return closeLocked(nodeId);
+    const cwd = existsSync(current.path) ? current.path : current.repo_root;
+    const commonDir = await commonGitDir(cwd);
+    return withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), () => closeLocked(nodeId), {
+        // Leave room for the API handler to serialize the typed refusal before its
+        // 30s client socket deadline.
+        timeoutMs: Math.min(WORKTREE_LOCK_WAIT_MS, 25_000),
+        timeoutError: () => new WorktreeError('worktree_lock_timeout', `timed out waiting to create a managed worktree in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.'),
+    });
+}

package/dist/core/worktree-containment.d.ts

@@ -0,0 +1,14 @@
+import type { ManagedWorktree } from './canvas/index.js';
+export interface BranchContainmentProof {
+    containingRef: string;
+    containingSha: string;
+}
+/** Resolve the base branch's configured upstream, or its origin fallback. */
+export declare function upstreamTip(cwd: string, baseRef: string): Promise<{
+    ref: string;
+    sha: string;
+} | null>;
+/** Prove that a recorded base or its upstream already carries a branch's
+ * committed content. This is the one decision point for explicit close and
+ * sweep cleanup: destination resolution happens only when this returns null. */
+export declare function proveBranchContained(cwd: string, wt: Pick<ManagedWorktree, 'base_ref'>, branchSha: string): Promise<BranchContainmentProof | null>;

package/dist/core/worktree-containment.js

@@ -0,0 +1,48 @@
+import { gitAsync } from './git.js';
+async function revParseRef(cwd, ref) {
+    const result = await gitAsync(['rev-parse', '--verify', '--quiet', ref], cwd);
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/** Resolve the base branch's configured upstream, or its origin fallback. */
+export async function upstreamTip(cwd, baseRef) {
+    const upstream = await gitAsync(['rev-parse', '--symbolic-full-name', '--verify', `${baseRef}@{upstream}`], cwd);
+    const ref = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/')
+        ? upstream.stdout.trim()
+        : `refs/remotes/origin/${baseRef}`;
+    const sha = await revParseRef(cwd, ref);
+    return sha === null ? null : { ref, sha };
+}
+/** Prove that a recorded base or its upstream already carries a branch's
+ * committed content. This is the one decision point for explicit close and
+ * sweep cleanup: destination resolution happens only when this returns null. */
+export async function proveBranchContained(cwd, wt, branchSha) {
+    const candidates = [];
+    const localBaseRef = `refs/heads/${wt.base_ref}`;
+    const localBase = await revParseRef(cwd, localBaseRef);
+    if (localBase !== null)
+        candidates.push({ ref: localBaseRef, sha: localBase });
+    const upstream = await upstreamTip(cwd, wt.base_ref);
+    if (upstream !== null)
+        candidates.push(upstream);
+    for (const candidate of candidates) {
+        if ((await gitAsync(['merge-base', '--is-ancestor', branchSha, candidate.sha], cwd)).status === 0)
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    for (const candidate of candidates) {
+        const cherry = await gitAsync(['cherry', candidate.sha, branchSha], cwd);
+        if (cherry.status !== 0)
+            continue;
+        const lines = cherry.stdout.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+        if (lines.every((line) => line.startsWith('-')))
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    for (const candidate of candidates) {
+        const candidateTree = await revParseRef(cwd, `${candidate.sha}^{tree}`);
+        if (candidateTree === null)
+            continue;
+        const merged = await gitAsync(['merge-tree', '--write-tree', candidate.sha, branchSha], cwd);
+        if (merged.status === 0 && merged.stdout.split('\n')[0]?.trim() === candidateTree)
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    return null;
+}

package/dist/core/worktree-mutation-async.d.ts

@@ -0,0 +1,13 @@
+import { type ManagedWorktree } from './canvas/index.js';
+import { type AbandonManagedWorktreeResult, type AutoDroppedWorktree } from './worktree.js';
+export declare function rollbackManagedWorktreeAsync(wt: ManagedWorktree): Promise<void>;
+export declare function createManagedWorktreeAsync(cwd: string, nodeId: string, baseRef?: string): Promise<ManagedWorktree>;
+export interface AbsentWorktreeConclusion {
+    dropped: AutoDroppedWorktree;
+    landedSha: string;
+}
+/** Conclude an absent checkout only from the same branch-delivery proof used by
+ * push-final and explicit close. */
+export declare function concludeAbsentManagedWorktreeAsync(nodeId: string): Promise<AbsentWorktreeConclusion | null>;
+export declare function autoDropCleanManagedWorktreeAsync(nodeId: string): Promise<AutoDroppedWorktree | null>;
+export declare function abandonManagedWorktreeAsync(nodeId: string, by: string): Promise<AbandonManagedWorktreeResult>;