@north-light/crouter 0.3.188 → 0.3.190

package/dist/core/__tests__/extension-abort.test.d.ts

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

package/dist/core/__tests__/extension-abort.test.js

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { abortSessionFromExtension, runRefreshAbort } from '../runtime/broker/extension-abort.js';
+test('refresh extension abort clears Pi follow-ups before abort while an ordinary abort preserves them', () => {
+    const events = [];
+    const session = {
+        clearQueue: () => { events.push('clear'); },
+        abort: async () => { events.push('abort'); },
+    };
+    abortSessionFromExtension(session);
+    assert.deepEqual(events, ['abort'], 'ordinary extension abort leaves queued messages in the current conversation');
+    events.length = 0;
+    runRefreshAbort(() => abortSessionFromExtension(session));
+    assert.deepEqual(events, ['clear', 'abort'], 'refresh removes queued messages before stopping the discarded conversation');
+    events.length = 0;
+    abortSessionFromExtension(session);
+    assert.deepEqual(events, ['abort'], 'the refresh scope does not leak into a later critical abort');
+});

package/dist/core/__tests__/serial/worktree.test.js

@@ -434,6 +434,89 @@ test('autoDropCleanManagedWorktree drops a clean, zero-commit worktree', async (
 });
 // The same real-commit case close already protects: a worktree with actual
 // unlanded work must NEVER be auto-dropped by push-final.
+// #671 also makes the explicit close terminal: once the checkout was safely
+// removed after remote delivery, close concludes the record rather than
+// sending the node to a recovery command that cannot address an absent path.
+test('closeManagedWorktree concludes an absent checkout whose branch is delivered to its base upstream (#671)', () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-671-close-'));
+    const remote = mkdtempSync(join(tmpdir(), 'crtr-worktree-671-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'), 'hello\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'init'], repo);
+        run(['init', '--bare'], remote);
+        run(['remote', 'add', 'origin', remote], repo);
+        run(['push', '-u', 'origin', 'main'], repo);
+        const nodeId = 'wt-671-close';
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+        writeFileSync(join(wt.path, 'delivered.txt'), 'delivered remotely\n');
+        run(['add', '.'], wt.path);
+        run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'delivered remotely'], wt.path);
+        const deliveredSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+        run(['push', 'origin', `${wt.branch}:main`], wt.path);
+        run(['fetch', 'origin'], repo);
+        run(['worktree', 'remove', wt.path], repo);
+        const result = closeManagedWorktree(nodeId);
+        assert.equal(result.landed_sha, deliveredSha, 'close reports the already-delivered branch tip');
+        assert.equal(result.worktree_removed, true, 'the absent path is already removed');
+        assert.equal(result.branch_deleted, true, 'the redundant local branch is deleted with upstream proof');
+        assert.equal(getNode(nodeId)?.managed_worktree?.state, 'closed');
+        assert.equal(getNode(nodeId)?.cwd, wt.repo_root, 'the closed record repoints revive to the durable base checkout');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(remote, { recursive: true, force: true });
+    }
+});
+// #671 review finding (Major): the recorded path being absent does not mean
+// the branch has no live checkout — `git worktree move` can relocate it
+// elsewhere. The branch must never be low-level-deleted while still checked
+// out somewhere, even when its tip is already contained in the base upstream.
+test('closeManagedWorktree refuses when the recorded path is absent but the branch is checked out elsewhere with uncommitted work', () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-671-moved-'));
+    const remote = mkdtempSync(join(tmpdir(), 'crtr-worktree-671-moved-remote-'));
+    const movedPath = mkdtempSync(join(tmpdir(), 'crtr-worktree-671-moved-dest-'));
+    rmSync(movedPath, { recursive: true, force: true });
+    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'), 'hello\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'init'], repo);
+        run(['init', '--bare'], remote);
+        run(['remote', 'add', 'origin', remote], repo);
+        run(['push', '-u', 'origin', 'main'], repo);
+        const nodeId = 'wt-671-moved';
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+        writeFileSync(join(wt.path, 'delivered.txt'), 'delivered remotely\n');
+        run(['add', '.'], wt.path);
+        run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'delivered remotely'], wt.path);
+        run(['push', 'origin', `${wt.branch}:main`], wt.path);
+        run(['fetch', 'origin'], repo);
+        // Relocate the checkout — the recorded `wt.path` is now absent, but the
+        // branch is still live at `movedPath`, and unrelated new work is added
+        // there AFTER the move, so it is not reachable from origin/main.
+        run(['worktree', 'move', wt.path, movedPath], repo);
+        assert.equal(existsSync(wt.path), false, 'the recorded path must actually be absent for this test to be meaningful');
+        writeFileSync(join(movedPath, 'uncommitted-after-move.txt'), 'must not be lost\n');
+        assert.throws(() => closeManagedWorktree(nodeId), (error) => error instanceof Error && 'code' in error && error.code === 'worktree_missing', 'a branch still checked out elsewhere must never be concluded from the absent recorded path alone');
+        assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'the record must stay open — the branch has a live checkout with uncommitted work');
+        const refCheck = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], repo);
+        assert.equal(refCheck.status, 0, 'the branch must be preserved — it is still checked out');
+        assert.ok(existsSync(join(movedPath, 'uncommitted-after-move.txt')), 'the uncommitted work at the relocated checkout must remain intact');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(remote, { recursive: true, force: true });
+        rmSync(movedPath, { recursive: true, force: true });
+    }
+});
 test('autoDropCleanManagedWorktree refuses a worktree with a real commit ahead of base', async () => {
     const { autoDropCleanManagedWorktree } = await import('../../worktree.js');
     const nodeId = 'wt-auto-drop-real-work';

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

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

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

@@ -0,0 +1,23 @@
+// ExtensionContext.abort() reaches the broker through AgentSession's bound
+// abortHandler. A refresh-yield is the one extension abort that must also clear
+// Pi's queued steering/follow-up messages: those messages remain durable in the
+// canvas inbox while intent='refresh', and the fresh kickoff replays them.
+// Other aborts (notably a critical inbox entry) leave queues intact because the
+// current conversation still owns those already-handed-off messages.
+let refreshAbortScope = false;
+/** Mark one synchronous ExtensionContext.abort() call as a refresh boundary. */
+export function runRefreshAbort(abort) {
+    refreshAbortScope = true;
+    try {
+        abort();
+    }
+    finally {
+        refreshAbortScope = false;
+    }
+}
+/** Bound into Pi's extension context by the broker for every session generation. */
+export function abortSessionFromExtension(session) {
+    if (refreshAbortScope)
+        session.clearQueue();
+    void session.abort();
+}

package/dist/core/runtime/broker/rebind.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { jobDir } from '../../canvas/paths.js';
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
+import { abortSessionFromExtension } from './extension-abort.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
 const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
@@ -52,7 +53,12 @@ export class RebindDriver {
             this.agentRunActiveValue = false;
             this.deps.onSessionRebind();
             this.deps.toolGroups.resetForSession();
-            await candidateSession.bindExtensions({ uiContext: this.deps.uiContext(), mode: 'rpc', shutdownHandler: () => this.requestShutdown() });
+            await candidateSession.bindExtensions({
+                uiContext: this.deps.uiContext(),
+                mode: 'rpc',
+                abortHandler: () => abortSessionFromExtension(candidateSession),
+                shutdownHandler: () => this.requestShutdown(),
+            });
             if (ticket !== this.latestRebindRequest)
                 return;
             this.removeInstalledSubscription();

package/dist/core/worktree.d.ts

@@ -38,6 +38,10 @@ export declare function closeManagedWorktree(nodeId: string): CloseManagedWorktr
 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. */

package/dist/core/worktree.js

@@ -59,8 +59,15 @@ function resolveLandableBase(repoRoot, baseRef) {
  *  if it is not checked out in any worktree. */
 function checkoutPathForBranch(repoRoot, branch) {
     const out = runGit(repoRoot, ['worktree', 'list', '--porcelain'], 'worktree_list_failed', 'Inspect the repository worktrees manually, then retry.');
+    return checkoutPathForBranchInList(out, branch);
+}
+/** Shared parse for a `git worktree list --porcelain` blob already in hand —
+ *  callers that must not throw on a read failure (an absent-path proof that
+ *  needs to fail closed rather than error) call `gitSync` themselves and pass
+ *  the output here instead of going through `checkoutPathForBranch`. */
+function checkoutPathForBranchInList(porcelain, branch) {
     let current = null;
-    for (const line of out.split('\n')) {
+    for (const line of porcelain.split('\n')) {
         if (line.startsWith('worktree '))
             current = line.slice('worktree '.length).trim();
         else if (line === `branch refs/heads/${branch}`)
@@ -256,7 +263,26 @@ function closeManagedWorktreeLocked(nodeId) {
         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}`, 'Ask the human with `crtr human ask` before changing node state; the checkout disappeared outside crouter.');
+        const proof = proveAbsentPathManagedWorktree(wt);
+        if (proof === null) {
+            throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, missingWorktreeRecoveryHint(wt));
+        }
+        const dropped = autoDropAbsentPathManagedWorktreeLocked(nodeId, wt, proof);
+        if (dropped === null) {
+            throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, missingWorktreeRecoveryHint(wt));
+        }
+        return {
+            node_id: nodeId,
+            branch: wt.branch,
+            worktree_path: wt.path,
+            // No local fast-forward happened in this recovery path. When the branch
+            // still exists, this is its remotely/local-base-delivered tip; when it
+            // was already deleted, the recorded creation base is the only durable
+            // SHA left to report through the established close result contract.
+            landed_sha: proof.branchSha ?? wt.base_sha,
+            worktree_removed: true,
+            branch_deleted: true,
+        };
     }
     if (isRebaseInProgress(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\`.`);
@@ -458,7 +484,13 @@ function bestEffortRemoveWorktreeCheckout(wt, options = {}) {
  *  simultaneously exactly what was proven, so a base rewrite can never leave
  *  a proven commit unreachable from any head. */
 function bestEffortDeleteBranchWithBaseProof(wt, branchSha, baseSha) {
-    const stdin = `verify refs/heads/${wt.base_ref} ${baseSha}\ndelete refs/heads/${wt.branch} ${branchSha}\n`;
+    return bestEffortDeleteBranchWithContainmentProof(wt, branchSha, `refs/heads/${wt.base_ref}`, baseSha);
+}
+/** Delete a source branch only while the ref that proved it already delivered
+ *  is still at the exact inspected SHA. `containingRef` can be the recorded
+ *  local base or that base's remote-tracking upstream. */
+function bestEffortDeleteBranchWithContainmentProof(wt, branchSha, containingRef, containingSha) {
+    const stdin = `verify ${containingRef} ${containingSha}\ndelete refs/heads/${wt.branch} ${branchSha}\n`;
     const transaction = gitSync(['update-ref', '--stdin'], wt.repo_root, stdin);
     const branchDeleted = transaction.status === 0;
     if (branchDeleted)
@@ -469,6 +501,80 @@ function bestEffortDeleteBranchWithBaseProof(wt, branchSha, baseSha) {
         branchDeleteError: `local branch ${wt.branch} could not be deleted automatically (${detail}); run \`git -C ${shellQuote(wt.repo_root)} branch -D ${shellQuote(wt.branch)}\` after confirming it is merged.`,
     };
 }
+/** A missing checkout can still be concluded, but only from refs: either the
+ * recorded local branch is already gone, or its tip is contained in the
+ * recorded base or that base's upstream. Filesystem absence alone proves
+ * nothing about commits. */
+function proveAbsentPathManagedWorktree(wt) {
+    if (wt.state !== 'open' || existsSync(wt.path))
+        return null;
+    const branchRef = `refs/heads/${wt.branch}`;
+    const branchExists = gitSync(['show-ref', '--verify', '--quiet', branchRef], wt.repo_root);
+    if (branchExists.status === 1)
+        return { branchSha: null };
+    if (branchExists.status !== 0)
+        return null;
+    const branch = gitSync(['rev-parse', '--verify', branchRef], wt.repo_root);
+    if (branch.status !== 0)
+        return null;
+    const branchSha = branch.stdout.trim();
+    // The recorded path being absent does NOT mean the branch has no live
+    // checkout: `git worktree move` (or a remove-then-re-add elsewhere) can
+    // relocate it to a different path while leaving `wt.path` gone. Deleting a
+    // branch that is still checked out somewhere else would bypass Git's own
+    // checked-out-branch protection and can abandon uncommitted work at that
+    // other path. Fail closed on any ambiguity from the inspection itself.
+    const worktreeList = gitSync(['worktree', 'list', '--porcelain'], wt.repo_root);
+    if (worktreeList.status !== 0)
+        return null;
+    if (checkoutPathForBranchInList(worktreeList.stdout, wt.branch) !== null)
+        return null;
+    const candidates = [];
+    const localBaseRef = `refs/heads/${wt.base_ref}`;
+    const localBaseExists = gitSync(['show-ref', '--verify', '--quiet', localBaseRef], wt.repo_root);
+    if (localBaseExists.status === 0) {
+        const localBase = gitSync(['rev-parse', '--verify', localBaseRef], wt.repo_root);
+        if (localBase.status !== 0)
+            return null;
+        candidates.push({ ref: localBaseRef, sha: localBase.stdout.trim() });
+    }
+    else if (localBaseExists.status !== 1) {
+        return null;
+    }
+    const upstream = gitSync(['rev-parse', '--symbolic-full-name', '--verify', `${wt.base_ref}@{upstream}`], wt.repo_root);
+    if (upstream.status === 0) {
+        const ref = upstream.stdout.trim();
+        const sha = gitSync(['rev-parse', '--verify', ref], wt.repo_root);
+        if (ref.startsWith('refs/') && sha.status === 0)
+            candidates.push({ ref, sha: sha.stdout.trim() });
+    }
+    else {
+        // Managed bases normally track origin. Retained records from before that
+        // configuration existed can still prove delivery through origin/<base>.
+        const ref = `refs/remotes/origin/${wt.base_ref}`;
+        const exists = gitSync(['show-ref', '--verify', '--quiet', ref], wt.repo_root);
+        if (exists.status === 0) {
+            const sha = gitSync(['rev-parse', '--verify', ref], wt.repo_root);
+            if (sha.status === 0)
+                candidates.push({ ref, sha: sha.stdout.trim() });
+        }
+        else if (exists.status !== 1) {
+            return null;
+        }
+    }
+    for (const candidate of candidates) {
+        if (gitSync(['merge-base', '--is-ancestor', branchSha, candidate.sha], wt.repo_root).status === 0) {
+            return { branchSha, containingRef: candidate.ref, containingSha: candidate.sha };
+        }
+    }
+    return null;
+}
+/** 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 function missingWorktreeRecoveryHint(wt) {
+    return `The recorded checkout path is gone, but crtr cannot prove ${wt.branch} is already delivered. Push or land ${wt.branch}, then rerun \`crtr push final\`; if you cannot establish what happened to the branch, ask the human with \`crtr human ask\`.`;
+}
 /** Fix B's shared "nothing to land" test — the SAME clean-worktree definition
  *  `close`'s own dirty check now naturally satisfies once `.git/info/exclude`
  *  hides crtr's own `.crouter/config.json`/`state.json` bookkeeping (Fix A),
@@ -519,6 +625,25 @@ export function proveCleanEmptyManagedWorktree(wt) {
         return null;
     return { branchSha, baseSha };
 }
+/** Conclude an absent-path record only after `proveAbsentPathManagedWorktree`
+ * has established the same no-unlanded-work property required by auto-drop.
+ * There is no checkout left to remove; persistClosedWorktreeState writes the
+ * closed record and repoints cwd exactly like the normal tombstone path. */
+function autoDropAbsentPathManagedWorktreeLocked(nodeId, wt, proof) {
+    if (existsSync(wt.path))
+        return null;
+    if (proof.branchSha === null) {
+        persistClosedWorktreeState(nodeId, wt);
+        return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: true };
+    }
+    if (proof.containingRef === undefined || proof.containingSha === undefined)
+        return null;
+    const { branchDeleted } = bestEffortDeleteBranchWithContainmentProof(wt, proof.branchSha, proof.containingRef, proof.containingSha);
+    if (!branchDeleted)
+        return null;
+    persistClosedWorktreeState(nodeId, wt);
+    return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: true };
+}
 /** 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
@@ -623,7 +748,8 @@ export function autoDropCleanManagedWorktree(nodeId) {
         return null;
     // A negative read-only preflight must fail before waiting on the repository
     // mutation lock: real unlanded work should reach push-final's guard promptly.
-    if (proveCleanEmptyManagedWorktree(wt) === null)
+    const pathAbsent = !existsSync(wt.path);
+    if (pathAbsent ? proveAbsentPathManagedWorktree(wt) === null : proveCleanEmptyManagedWorktree(wt) === null)
         return null;
     return withRepositoryWorktreeLock(wt.repo_root, () => {
         // Re-fetch inside the lock: state may have changed since the caller's
@@ -631,11 +757,13 @@ export function autoDropCleanManagedWorktree(nodeId) {
         const locked = openManagedWorktreeForNode(nodeId);
         if (locked === null)
             return null;
-        // The preflight only avoids needless lock contention. Re-prove the full
-        // predicate under the lock before any cleanup.
+        // Re-prove the matching predicate under the lock before any state or ref
+        // mutation. A path that reappeared follows the ordinary checkout path.
+        if (!existsSync(locked.path)) {
+            const proof = proveAbsentPathManagedWorktree(locked);
+            return proof === null ? null : autoDropAbsentPathManagedWorktreeLocked(nodeId, locked, proof);
+        }
         const proof = proveCleanEmptyManagedWorktree(locked);
-        if (proof === null)
-            return null;
-        return autoDropCleanManagedWorktreeLocked(nodeId, locked, proof);
+        return proof === null ? null : autoDropCleanManagedWorktreeLocked(nodeId, locked, proof);
     });
 }

package/dist/daemon/api/__tests__/seam/leaf-api-parity.test.js

@@ -198,6 +198,63 @@ test('auto-drop: `crtr push final` on a node with a CLEAN, zero-commit managed w
         rmSync(repo, { recursive: true, force: true });
     }
 });
+// #671: after a failed local close, a node may safely deliver its branch to
+// the base's upstream and remove its own clean checkout. The path is gone, so
+// only the remote-tracking ref can prove finalization will not discard work.
+test('`crtr push final` concludes an absent managed worktree whose branch is delivered to its base upstream (#671)', async () => {
+    const repo = initRepo();
+    const remote = mkdtempSync(join(tmpdir(), 'crtr-leafparity-remote-'));
+    try {
+        git(['init', '--bare'], remote);
+        git(['remote', 'add', 'origin', remote], repo);
+        git(['push', '-u', 'origin', 'main'], repo);
+        const id = 'wt-671-upstream-delivered';
+        const wt = createManagedWorktree(repo, id);
+        writeFileSync(join(wt.path, 'delivered.txt'), 'delivered remotely\n');
+        git(['add', '.'], wt.path);
+        git(['commit', '-m', 'delivered remotely'], wt.path);
+        const deliveredSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+        // This is the incident delivery route: origin/main contains the branch,
+        // while the local base remains deliberately untouched.
+        git(['push', 'origin', `${wt.branch}:main`], wt.path);
+        git(['fetch', 'origin'], repo);
+        assert.equal(gitSync(['merge-base', '--is-ancestor', deliveredSha, 'origin/main'], repo).status, 0, 'the remote-tracking upstream must prove delivery');
+        git(['worktree', 'remove', wt.path], repo);
+        assert.equal(existsSync(wt.path), false, 'the incident shape has no checkout path left');
+        createNode(worktreeNode(id, wt.path, wt));
+        const out = await runPushAs(id, 'final', 'delivered remotely and cleaned up');
+        assert.equal(out['worktree_auto_dropped'], true, 'the absent-path proof must unblock finalization');
+        assert.equal(getNode(id)?.managed_worktree?.state, 'closed', 'the record is tombstoned as closed');
+        assert.equal(getNode(id)?.cwd, wt.repo_root, 'the closed record repoints revive to the durable base checkout');
+        assert.equal(getNode(id)?.status, 'done', 'finalization completes after the proven drop');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(remote, { recursive: true, force: true });
+    }
+});
+test('`crtr push final` keeps an absent managed worktree open when its branch is not delivered (#671)', async () => {
+    const repo = initRepo();
+    try {
+        const id = 'wt-671-absent-unlanded';
+        const wt = createManagedWorktree(repo, id);
+        writeFileSync(join(wt.path, 'unlanded.txt'), 'must remain reachable\n');
+        git(['add', '.'], wt.path);
+        git(['commit', '-m', 'unlanded work'], wt.path);
+        git(['worktree', 'remove', wt.path], repo);
+        createNode(worktreeNode(id, wt.path, wt));
+        await assert.rejects(() => runPushAs(id, 'final', 'must block'), (e) => e instanceof InputError
+            && e.payload.error === 'open_managed_worktree'
+            && typeof e.payload.next === 'string'
+            && e.payload.next.includes(`Push or land ${wt.branch}`)
+            && !e.payload.next.includes('node worktree close'), 'an absent checkout with unlanded commits must remain blocked with a usable recovery path');
+        assert.equal(getNode(id)?.managed_worktree?.state, 'open', 'the ambiguous record must stay open');
+        assert.equal(gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], repo).status, 0, 'the unlanded branch must remain reachable');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
 // ---------------------------------------------------------------------------
 // `node worktree close` error parity — the SPECIFIC WorktreeError code + its
 // `next` remediation round-trip verbatim through the server → ApiError → the

package/dist/daemon/api/handlers/nodes.js

@@ -85,6 +85,15 @@ function parseCreateBody(body) {
     if (typeof b['kind'] !== 'string' || b['kind'].trim() === '') {
         throw usage('a node create requires a kind');
     }
+    const rootLifecycle = b['root_lifecycle'];
+    if (rootLifecycle !== undefined &&
+        rootLifecycle !== 'resident' &&
+        rootLifecycle !== 'terminal') {
+        throw usage("root_lifecycle must be 'resident' or 'terminal'");
+    }
+    if (rootLifecycle !== undefined && b['root'] !== true) {
+        throw usage('root_lifecycle is only valid with root: true');
+    }
     return b;
 }
 /** The directory a new node is pinned to. An explicit `pin_cwd` wins; else a
@@ -122,6 +131,9 @@ function buildRecipe(req, parent, cwd) {
         recipe.parent = parent;
     if (req.root === true)
         recipe.root = true;
+    if (req.root_lifecycle !== undefined) {
+        recipe.rootLifecycle = req.root_lifecycle;
+    }
     if (req.worktree === true || typeof req.worktree === 'string')
         recipe.worktree = true;
     if (typeof req.worktree === 'string')
@@ -143,7 +155,8 @@ function buildRecipe(req, parent, cwd) {
  *  kickoff, so anything that shapes the node AT BIRTH — a prompt to run, a
  *  forked conversation, a managed worktree, a caller-pinned node id, a spine
  *  parent — disqualifies it. `kind`, `mode`, `model`, `name`, `situational_context`
- *  and `output_schema` are all applied at claim time and so do not. */
+ *  and `output_schema` are all applied at claim time and so do not. A terminal
+ *  root is not warm-compatible: every spare is resident. */
 function warmRequestFor(req, cwd, profileId) {
     if (!warmPoolEnabled())
         return null;
@@ -151,6 +164,8 @@ function warmRequestFor(req, cwd, profileId) {
         return null;
     if (req.root !== true || req.parent != null)
         return null;
+    if (req.root_lifecycle === 'terminal')
+        return null;
     if ((req.prompt ?? '') !== '')
         return null;
     if (req.fork_from !== undefined || req.worktree !== undefined || req.node_id !== undefined)
@@ -210,7 +225,7 @@ export async function handleCreate(ctx, deps = {}) {
     const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd);
     const cwd = resolveNodeCwd(req, parent, profileId, contextCwd);
     const launch = buildLaunchSpec(req.kind, (req.mode ?? 'base'), {
-        lifecycle: req.root === true ? 'resident' : 'terminal',
+        lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
         hasManager: req.root !== true,
         ...(req.model !== undefined ? { model: req.model } : {}),
         cwd,

package/dist/daemon/api/handlers/reports.js

@@ -4,11 +4,11 @@
 // /nodes/{id}/reports` lists the node's stored report files.
 //
 // `{id}` is the REPORTING node (client-side = CRTR_NODE_ID).
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode } from '../../../index.js';
 import { push, FinalizationError } from '../../../core/feed/feed.js';
-import { autoDropCleanManagedWorktree, hasOpenManagedWorktree } from '../../../core/worktree.js';
+import { autoDropCleanManagedWorktree, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
 import { reportsDir } from '../../../core/canvas/paths.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -58,7 +58,12 @@ async function handlePush(ctx) {
             throw new InputError({
                 error: 'open_managed_worktree',
                 message: 'This node still owns an open managed worktree — `push final` is blocked until it is closed.',
-                next: 'Commit the remaining work in the worktree, run `crtr node worktree close`, then rerun `crtr push final`.',
+                next: (() => {
+                    const wt = getNode(id)?.managed_worktree;
+                    return wt !== null && wt !== undefined && wt.state === 'open' && !existsSync(wt.path)
+                        ? missingWorktreeRecoveryHint(wt)
+                        : 'Commit the remaining work in the worktree, run `crtr node worktree close`, then rerun `crtr push final`.';
+                })(),
             });
         }
         autoDroppedPath = dropped.worktree_path;

package/dist/pi-extensions/canvas-stophook.js

@@ -32,6 +32,7 @@ import { emitEvent } from '../core/events/emit.js';
 import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
 import { CONTEXT_NUDGE_CUSTOM_TYPE, formatContextNudge, formatPersonaTransition } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
+import { runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
  *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
@@ -479,11 +480,14 @@ export function registerCanvasStophook(pi) {
             touchBusy(nodeId); // wedge heartbeat: the tool returning is a sign of life
             clearFault(nodeId, { link: 'daemon→node' }); // a tool that was "stuck" just returned — the wedge notice was resolved
             if ((await brokerExtensionState(nodeId)).node.intent === 'refresh') {
-                // Stop this turn immediately so the large context does not keep running,
-                // but leave the broker alive through agent_settled. Only a successful
-                // daemon settle directive may request Pi shutdown.
+                // Stop this turn immediately so the large context does not keep running.
+                // The broker clears Pi's queued steering/follow-up messages inside this
+                // refresh scope; their durable inbox entries stay uncommitted and the
+                // fresh kickoff replays them. Leave the broker alive through
+                // agent_settled: only a successful daemon settle directive may request
+                // Pi shutdown.
                 try {
-                    ctx?.abort?.();
+                    runRefreshAbort(() => ctx?.abort?.());
                 }
                 catch { /* ignore */ }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.188",
+  "version": "0.3.190",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.188",
+  "version": "0.3.190",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.188",
+      "version": "0.3.190",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {