@north-light/crouter 0.3.302 → 0.3.304

package/dist/core/worktree-mutation-async.js

@@ -0,0 +1,281 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { getNode, updateNode } from './canvas/index.js';
+import { isPidAlive } from './canvas/pid.js';
+import { CONFIG_FILE, CRTR_DIR_NAME, STATE_FILE } from '../types.js';
+import { withExclusiveDirectoryLockAsync } from './exclusive-lock.js';
+import { gitAsync } from './git.js';
+import { WORKTREE_LOCK_WAIT_MS, checkoutPathForBranchInList, isManagedWorktreeBase, managedWorktreePath, persistClosedWorktreeState, worktreeLockPathForCommonDir, WorktreeError } from './worktree.js';
+import { proveBranchContained } from './worktree-containment.js';
+import { refDeleteTransactionStdin } from './worktree-landing.js';
+const LOCK_WAIT_MS = Math.min(WORKTREE_LOCK_WAIT_MS, 25_000);
+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) {
+    return realpathSync(resolve(cwd, await runGit(cwd, ['rev-parse', '--git-common-dir'], 'git_common_dir_failed', 'Inspect the repository git metadata, then retry.')));
+}
+async function withRepositoryLock(cwd, action) {
+    const commonDir = await commonGitDir(cwd);
+    return withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), action, {
+        timeoutMs: LOCK_WAIT_MS,
+        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.'),
+    });
+}
+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)
+        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>'}`);
+    return runGit(cwd, ['rev-parse', '--verify', ref], 'base_branch_resolve_failed', 'Inspect the local base branch, then retry.');
+}
+function seedExclude(repoRoot, commonDir) {
+    try {
+        const path = join(commonDir, 'info', 'exclude');
+        mkdirSync(dirname(path), { recursive: true });
+        let current = '';
+        try {
+            current = readFileSync(path, 'utf8');
+        }
+        catch { /* first write */ }
+        const patterns = [`/${CRTR_DIR_NAME}/${CONFIG_FILE}`, `/${CRTR_DIR_NAME}/${STATE_FILE}`];
+        if (patterns.every((pattern) => current.split('\n').map((line) => line.trim()).includes(pattern)))
+            return;
+        writeFileSync(path, `${current}${current !== '' && !current.endsWith('\n') ? '\n' : ''}# crtr: exclude crtr's own untracked project-scope bookkeeping (auto-added at managed-worktree creation)\n${patterns.filter((pattern) => !current.split('\n').map((line) => line.trim()).includes(pattern)).join('\n')}\n`);
+    }
+    catch { /* cosmetic only */ }
+}
+export async function rollbackManagedWorktreeAsync(wt) {
+    await withRepositoryLock(wt.repo_root, async () => {
+        const branch = await gitAsync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], wt.repo_root);
+        if (branch.status !== 0 || branch.stdout.trim() !== wt.base_sha)
+            return;
+        const list = await gitAsync(['worktree', 'list', '--porcelain'], wt.repo_root);
+        if (list.status !== 0)
+            return;
+        if (list.stdout.split('\n').some((line) => line.trim() === `branch refs/heads/${wt.branch}`)) {
+            if ((await gitAsync(['worktree', 'remove', '--force', wt.path], wt.repo_root)).status !== 0)
+                return;
+        }
+        else if (existsSync(wt.path)) {
+            try {
+                rmSync(wt.path, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+        }
+        await gitAsync(['update-ref', '-d', `refs/heads/${wt.branch}`, wt.base_sha], wt.repo_root);
+    });
+}
+export async function createManagedWorktreeAsync(cwd, nodeId, baseRef = 'main') {
+    const repoRoot = await runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd <real repo> pointing inside a git repository.');
+    if (isManagedWorktreeBase(repoRoot)) {
+        throw new WorktreeError('managed_worktree_base', `cwd ${repoRoot} is a managed worktree and cannot be used as a managed worktree base`, 'Pass --cwd <real repo> pointing at the repository’s primary checkout.');
+    }
+    const commonDir = await commonGitDir(repoRoot);
+    return withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => {
+        const baseSha = await resolveLandableBase(repoRoot, baseRef);
+        const path = managedWorktreePath(nodeId);
+        const branch = `crtr/${nodeId}`;
+        if (existsSync(path))
+            throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
+        if ((await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], repoRoot)).status === 0)
+            throw new WorktreeError('worktree_branch_exists', `managed worktree branch already exists: ${branch}`, 'Remove the stale branch or choose a fresh node id.');
+        const wt = { state: 'open', path, branch, repo_root: repoRoot, base_ref: baseRef, base_sha: baseSha, created: new Date().toISOString() };
+        await runGit(repoRoot, ['branch', branch, baseSha], 'worktree_branch_create_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+        const added = await gitAsync(['worktree', 'add', path, branch], repoRoot);
+        if (added.status !== 0) {
+            await gitAsync(['update-ref', '-d', `refs/heads/${branch}`, baseSha], repoRoot);
+            throw new WorktreeError('worktree_add_failed', 'git worktree add failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.', detailOf(added));
+        }
+        seedExclude(repoRoot, commonDir);
+        return wt;
+    }, { timeoutMs: LOCK_WAIT_MS, 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.') });
+}
+async function cleanTip(wt) {
+    if (wt.state !== 'open' || !existsSync(wt.path))
+        return null;
+    const branch = await gitAsync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
+    const status = await gitAsync(['status', '--porcelain'], wt.path);
+    const head = await gitAsync(['rev-parse', 'HEAD'], wt.path);
+    if (branch.status !== 0 || branch.stdout.trim() !== wt.branch || status.status !== 0 || status.stdout.trim() !== '' || head.status !== 0)
+        return null;
+    const gitPath = await gitAsync(['rev-parse', '--git-path', 'rebase-merge'], wt.path);
+    if (gitPath.status !== 0 || existsSync(gitPath.stdout.trim()))
+        return null;
+    return head.stdout.trim();
+}
+async function containedInLocalBase(wt, head) {
+    try {
+        const base = await resolveLandableBase(wt.path, wt.base_ref);
+        return (await gitAsync(['merge-base', '--is-ancestor', head, base], wt.path)).status === 0;
+    }
+    catch (error) {
+        if (error instanceof WorktreeError && error.code === 'missing_base_branch' && head === wt.base_sha)
+            return true;
+        throw error;
+    }
+}
+function deferred(wt) {
+    return { node_id: '', branch: wt.branch, worktree_path: wt.path, worktree_removed: false, worktree_remove_error: `cleanup pending: the caller checkout at ${wt.path} remains intact.`, branch_deleted: false, branch_delete_error: `cleanup pending: local branch ${wt.branch} remains checked out at ${wt.path}.` };
+}
+/** A missing checkout can be concluded only when its branch is already gone,
+ * or the recorded base or its upstream contains the branch and it has no other
+ * checkout. */
+async function proveAbsentPathManagedWorktree(wt) {
+    if (wt.state !== 'open' || existsSync(wt.path))
+        return null;
+    const branchRef = `refs/heads/${wt.branch}`;
+    const branchExists = await gitAsync(['show-ref', '--verify', '--quiet', branchRef], wt.repo_root);
+    if (branchExists.status === 1 && branchExists.executionFailed !== true)
+        return { branchSha: null };
+    if (branchExists.status !== 0)
+        return null;
+    const branch = await gitAsync(['rev-parse', '--verify', branchRef], wt.repo_root);
+    if (branch.status !== 0)
+        return null;
+    const branchSha = branch.stdout.trim();
+    const worktreeList = await gitAsync(['worktree', 'list', '--porcelain'], wt.repo_root);
+    if (worktreeList.status !== 0 || checkoutPathForBranchInList(worktreeList.stdout, wt.branch) !== null)
+        return null;
+    const containment = await proveBranchContained(wt.repo_root, wt, branchSha);
+    return containment === null ? null : { branchSha, containment };
+}
+async function autoDropAbsentPathManagedWorktreeLocked(nodeId, wt, proof) {
+    if (existsSync(wt.path))
+        return null;
+    if (proof.branchSha === null) {
+        persistClosedWorktreeState(nodeId, wt, 'complete');
+        return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: true };
+    }
+    if (proof.containment === undefined)
+        return null;
+    // `update-ref` bypasses Git's checked-out-branch protection. A person can
+    // add a worktree after the list above, so the delivered branch stays intact:
+    // its containment proof concludes this node without risking that checkout.
+    persistClosedWorktreeState(nodeId, wt, 'complete');
+    return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: false, branch_delete_error: `local branch ${wt.branch} is delivered but retained because its checkout status can change outside crtr's repository lock.` };
+}
+/** Conclude an absent checkout only from the same branch-delivery proof used by
+ * push-final and explicit close. */
+export async function concludeAbsentManagedWorktreeAsync(nodeId) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open' || existsSync(wt.path))
+        return null;
+    if (await proveAbsentPathManagedWorktree(wt) === null)
+        return null;
+    return withRepositoryLock(wt.repo_root, async () => {
+        const locked = getNode(nodeId)?.managed_worktree;
+        if (locked === undefined || locked === null || locked.state !== 'open')
+            return null;
+        const proof = await proveAbsentPathManagedWorktree(locked);
+        if (proof === null)
+            return null;
+        const dropped = await autoDropAbsentPathManagedWorktreeLocked(nodeId, locked, proof);
+        return dropped === null ? null : { dropped, landedSha: proof.branchSha ?? locked.base_sha };
+    });
+}
+export async function autoDropCleanManagedWorktreeAsync(nodeId) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open')
+        return null;
+    if (!existsSync(wt.path))
+        return (await concludeAbsentManagedWorktreeAsync(nodeId))?.dropped ?? null;
+    const initial = await cleanTip(wt);
+    if (initial === null || !(await containedInLocalBase(wt, initial)))
+        return null;
+    return withRepositoryLock(wt.path, async () => {
+        const locked = getNode(nodeId)?.managed_worktree;
+        if (locked === undefined || locked === null || locked.state !== 'open')
+            return null;
+        const head = await cleanTip(locked);
+        if (head === null || head !== initial || !(await containedInLocalBase(locked, head)))
+            return null;
+        persistClosedWorktreeState(nodeId, locked, 'pending');
+        return { ...deferred(locked), node_id: nodeId };
+    });
+}
+async function rebaseInProgress(cwd) {
+    for (const path of ['rebase-merge', 'rebase-apply']) {
+        const result = await gitAsync(['rev-parse', '--git-path', path], cwd);
+        if (result.status !== 0 || existsSync(result.stdout.trim()))
+            return true;
+    }
+    return false;
+}
+function persistAbandoned(nodeId, wt, tip, at, by, branch = wt.branch) {
+    updateNode(nodeId, { cwd: wt.repo_root, managed_worktree: { ...wt, state: 'abandoned', abandoned: { branch, tip_sha: tip, at, by } } });
+}
+export async function abandonManagedWorktreeAsync(nodeId, by) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open')
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+    return withRepositoryLock(wt.path, async () => {
+        const node = getNode(nodeId);
+        const current = node?.managed_worktree;
+        if (node === null || current === undefined || current === null || current.state !== 'open')
+            throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+        if (node.status === 'active' || node.status === 'idle' || isPidAlive(node.pi_pid))
+            throw new WorktreeError('node_running', `node ${nodeId} is still running`, 'Stop the node before abandoning its managed worktree.');
+        if (!existsSync(current.path))
+            throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${current.path}`, 'Inspect the branch and worktree registration, then retry.');
+        const branch = await runGit(current.path, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+        const recorded = await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${current.branch}`], current.path);
+        if (branch !== current.branch) {
+            if (recorded.status === 0 || branch === 'HEAD')
+                throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${current.branch}, found ${branch === 'HEAD' ? 'detached HEAD' : branch})`, `Inspect ${current.path}, then rerun \`crtr node worktree abandon\`.`);
+            if (await rebaseInProgress(current.path) || (await runGit(current.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.')) !== '')
+                throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit or stash them in ${current.path}, then rerun \`crtr node worktree abandon\`.`);
+            const tip = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the worktree manually, then retry.');
+            await runGit(current.repo_root, ['worktree', 'remove', current.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+            const at = new Date().toISOString();
+            persistAbandoned(nodeId, current, tip, at, by, branch);
+            return { node_id: nodeId, branch, tip_sha: tip, worktree_path: current.path, branch_deleted: false };
+        }
+        const head = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+        let cleanBase = null;
+        try {
+            const base = await resolveLandableBase(current.path, current.base_ref);
+            if ((await gitAsync(['merge-base', '--is-ancestor', head, base], current.path)).status === 0)
+                cleanBase = base;
+        }
+        catch (error) {
+            if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch' || head !== current.base_sha)
+                throw error;
+            cleanBase = current.base_sha;
+        }
+        const at = new Date().toISOString();
+        const status = await runGit(current.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+        if (cleanBase !== null && head === current.base_sha) {
+            const tree = await runGit(current.repo_root, ['rev-parse', `${head}^{tree}`], 'abandon_tree_failed', 'Inspect the branch manually, then retry.');
+            const marker = await runGit(current.repo_root, ['-c', 'user.name=crtr-abandon', '-c', 'user.email=crtr-abandon@localhost', 'commit-tree', tree, '-p', head, '-m', 'crtr-abandon', '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the branch manually, then retry.');
+            await runGit(current.repo_root, ['update-ref', `refs/heads/${current.branch}`, marker, head], 'abandon_marker_failed', 'The branch changed while abandon was starting; inspect the worktree, then retry.');
+            await runGit(current.repo_root, ['worktree', 'remove', current.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+            const deleted = await gitAsync(['update-ref', '--stdin'], current.repo_root, refDeleteTransactionStdin(current.branch, marker, `refs/heads/${current.base_ref}`, cleanBase));
+            if (deleted.status === 0) {
+                persistClosedWorktreeState(nodeId, current, 'complete');
+                return { node_id: nodeId, branch: current.branch, tip_sha: marker, worktree_path: current.path, branch_deleted: true };
+            }
+            persistAbandoned(nodeId, current, marker, at, by);
+            return { node_id: nodeId, branch: current.branch, tip_sha: marker, worktree_path: current.path, branch_deleted: false };
+        }
+        if (!await rebaseInProgress(current.path) && status === '') {
+            await runGit(current.repo_root, ['worktree', 'remove', current.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+            persistAbandoned(nodeId, current, head, at, by);
+            return { node_id: nodeId, branch: current.branch, tip_sha: head, worktree_path: current.path, branch_deleted: false };
+        }
+        await runGit(current.path, ['add', '--all'], 'abandon_stage_failed', 'Inspect the worktree manually, then retry.');
+        await runGit(current.path, ['-c', 'user.name=crtr-abandon', '-c', 'user.email=crtr-abandon@localhost', 'commit', '--allow-empty', '-m', 'crtr-abandon', '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the worktree manually, then retry.');
+        const tip = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+        await runGit(current.repo_root, ['worktree', 'remove', current.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+        persistAbandoned(nodeId, current, tip, at, by);
+        return { node_id: nodeId, branch: current.branch, tip_sha: tip, worktree_path: current.path, branch_deleted: false };
+    });
+}

package/dist/core/worktree-sweep.js

@@ -21,6 +21,7 @@ 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, upstreamTip } from './worktree-containment.js';
 import { parseStatusPorcelain, planLandIntoCheckout, refDeleteTransactionStdin } from './worktree-landing.js';
 import { WORKTREE_LOCK_WAIT_MS, checkoutPathForBranchInList, persistClosedWorktreeState, samePath, worktreeLockPathForCommonDir } from './worktree.js';
 /** Escalating recheck interval, in minutes, indexed by consecutive refusal. The
@@ -101,95 +102,32 @@ function registeredCheckoutPath(porcelain, path, branch) {
     }
     return null;
 }
-/** Refs that could prove delivery: the recorded local base, and the base's
- *  upstream (a branch delivered by push rather than by a local land). */
-async function containmentCandidates(cwd, wt) {
-    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 gitAsync(['rev-parse', '--symbolic-full-name', '--verify', `${wt.base_ref}@{upstream}`], cwd);
-    const upstreamRef = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/')
-        ? upstream.stdout.trim()
-        : `refs/remotes/origin/${wt.base_ref}`;
-    const upstreamSha = await revParseRef(cwd, upstreamRef);
-    if (upstreamSha !== null)
-        candidates.push({ ref: upstreamRef, sha: upstreamSha });
-    return candidates;
-}
-/** Does removing this branch lose content the candidate does not already have?
- *
- *  The invariant is about CONTENT, not history. A rebase rewrites every SHA, so
- *  a fully-landed branch can look diverged; a squash-merge leaves no matching
- *  commit at all. An ancestry-only proof would refuse exactly the cases this
- *  sweep exists to clean up, so three layers run in increasing cost, and any one
- *  of them is sufficient:
- *
- *  1. ancestry     — the tip is already reachable from the candidate.
- *  2. patch identity — every commit not in the candidate by SHA has a
- *                      patch-equivalent commit there (`git cherry`). The rebase case.
- *  3. content no-op  — merging the branch in would change nothing. The
- *                      squash-merge case, and most remaining "looks bad but isn't" states.
- *
- *  Only when all three fail does the branch genuinely carry unlanded content.
- *  Every layer fails CLOSED: a Git version without `merge-tree --write-tree`, an
- *  unreadable object, any non-zero exit — none of them prove anything, so the
- *  branch survives. */
-async function proveContained(cwd, wt, branchSha) {
-    const candidates = await containmentCandidates(cwd, wt);
-    if (candidates.length === 0)
-        return null;
-    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, layer: 'ancestry' };
-        }
-    }
-    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((l) => l.trim()).filter((l) => l !== '');
-        if (lines.every((line) => line.startsWith('-'))) {
-            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'patch_identity' };
-        }
-    }
-    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)
-            continue; // conflict, or a Git too old for this flag
-        if (merged.stdout.split('\n')[0]?.trim() === candidateTree) {
-            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'content_noop' };
-        }
-    }
-    return null;
-}
+// Content containment is shared with explicit close. A delivered branch is
+// never rebased onto a local base merely because that base later diverged.
 // Change detection
-/** Base tip, branch tip, and checkout state as they are right now. A pass that
- *  reads the same three values as the refusal that preceded it can stop there:
- *  nothing that decided the refusal has moved. An unreadable checkout records
- *  `null`, which never compares equal, so uncertainty always re-proves. */
+/** Base, upstream, and branch tips plus checkout state as they are right now.
+ *  A pass that reads the same values as the refusal that preceded it can stop
+ *  there: nothing that decided the refusal has moved. An unreadable checkout
+ *  records `null`, which never compares equal, so uncertainty always re-proves. */
 async function observe(wt) {
     const present = existsSync(wt.path);
     const cwd = present ? wt.path : wt.repo_root;
     const base = await revParseRef(cwd, `refs/heads/${wt.base_ref}`);
+    const upstream = await upstreamTip(cwd, wt.base_ref);
     const branch = await revParseRef(cwd, `refs/heads/${wt.branch}`);
     if (!present)
-        return { base, branch, checkout: 'absent' };
+        return { base, upstream: upstream?.sha ?? null, branch, checkout: 'absent' };
     const head = await gitAsync(['rev-parse', 'HEAD'], wt.path);
     const status = await gitAsync(['status', '--porcelain'], wt.path);
     const checkout = head.status !== 0 || status.status !== 0
         ? null
         : createHash('sha256').update(`${head.stdout.trim()}\n${status.stdout}`).digest('hex');
-    return { base, branch, checkout };
+    return { base, upstream: upstream?.sha ?? null, branch, checkout };
 }
 function sameObservation(a, b) {
     if (a.checkout === null || b.checkout === null)
         return false;
-    return a.base === b.base && a.branch === b.branch && a.checkout === b.checkout;
+    return a.base === b.base && a.upstream === b.upstream && a.branch === b.branch && a.checkout === b.checkout;
 }
 // Recording an unfinished pass
 /** Persist why this pass did not finish, with the fingerprint it decided
@@ -336,13 +274,13 @@ export async function reconcileManagedWorktree(nodeId, guard, now = Date.now())
         return { status: 'skipped', reason: 'already_reconciled' };
     const cwd = existsSync(wt.path) ? wt.path : wt.repo_root;
     if (!existsSync(cwd)) {
-        return persistComplete(nodeId, wt, guard);
+        return finish(nodeId, wt, { status: 'refused', reason: 'repo_unavailable', detail: `neither the recorded checkout nor repository root exists, so ${wt.branch} cannot be proved absent` }, { base: null, upstream: null, branch: null, checkout: null }, now, guard);
     }
     const commonDir = await commonGitDirAsync(cwd);
     if (commonDir === null) {
-        return finish(nodeId, wt, { status: 'failed', reason: 'git_dir_unreadable', detail: `could not resolve the git common dir from ${cwd}` }, { base: null, branch: null, checkout: null }, now, guard);
+        return finish(nodeId, wt, { status: 'failed', reason: 'git_dir_unreadable', detail: `could not resolve the git common dir from ${cwd}` }, { base: null, upstream: null, branch: null, checkout: null }, now, guard);
     }
-    let observed = { base: null, branch: null, checkout: null };
+    let observed = { base: null, upstream: null, branch: null, checkout: null };
     let outcome;
     try {
         outcome = await withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => {
@@ -412,7 +350,7 @@ async function concludeAbsentCheckout(nodeId, wt, observed, guard) {
     if (elsewhere !== null) {
         return { status: 'refused', reason: 'branch_checked_out_elsewhere', detail: `${wt.branch} is checked out at ${elsewhere}` };
     }
-    const proof = await proveContained(admin, wt, observed.branch);
+    const proof = await proveBranchContained(admin, wt, observed.branch);
     if (proof === null) {
         return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries content no base or upstream ref contains; its checkout is already gone, so the branch is the only copy` };
     }
@@ -477,7 +415,7 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
         // is preserved, never deleted, unlike the ordinary path below.
         return persistComplete(nodeId, wt, guard);
     }
-    let proof = await proveContained(wt.path, wt, branchSha);
+    let proof = await proveBranchContained(wt.path, wt, branchSha);
     let stash;
     if (proof === null && wt.land_intent !== undefined) {
         const landed = await finishBlockedLand(wt, list.stdout, guard);
@@ -485,7 +423,7 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
             return landed.ineligible === true ? NODE_REVIVED : { status: 'refused', reason: 'land_blocked', detail: landed.detail };
         branchSha = landed.landedSha;
         stash = landed.stash;
-        proof = await proveContained(wt.path, wt, branchSha);
+        proof = await proveBranchContained(wt.path, wt, branchSha);
     }
     if (proof === null) {
         return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries commits its base does not contain, and this node never asked to land them` };

package/dist/core/worktree.d.ts

@@ -14,6 +14,7 @@ export declare function managedWorktreesRoot(): string;
 export declare function managedWorktreePath(nodeId: string): string;
 export declare function hasOpenManagedWorktree(node: NodeMeta | null | undefined): boolean;
 export declare function openManagedWorktreeForNode(nodeId: string): ManagedWorktree | null;
+export declare function isManagedWorktreeBase(repoRoot: string): boolean;
 /** 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

package/dist/core/worktree.js

@@ -51,7 +51,7 @@ function repoRootFor(cwd) {
     }
     return result.stdout.trim();
 }
-function isManagedWorktreeBase(repoRoot) {
+export function isManagedWorktreeBase(repoRoot) {
     const path = relative(canonicalPath(managedWorktreesRoot()), canonicalPath(repoRoot));
     return path !== '' && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path);
 }

package/dist/daemon/__tests__/integration/api-startup-readiness.test.js

@@ -49,15 +49,17 @@ test('a Unix socket bind failure rejects readiness and releases daemon ownership
         assert.equal(existsSync(pidfile), false, 'failed readiness removes the pidfile mirror');
         assert.equal(existsSync(socketPath), true, 'the pre-existing directory was never mistaken for a serving socket');
         assert.match(readFileSync(join(canvasHome, 'crtrd.log'), 'utf8'), /api\.server\.failed/, 'the bind failure is recorded for cold-start diagnostics');
+        rmSync(socketPath, { recursive: true, force: true });
         writeFileSync(pidfile, String(process.pid));
-        assert.deepEqual(await spawnDaemon(), {
-            started: false,
-            existing_pid: process.pid,
-            running: true,
-            serving: false,
-            next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
-        }, 'start distinguishes a live non-serving pidfile owner from a serving daemon');
-        rmSync(pidfile, { force: true });
+        try {
+            const result = await spawnDaemon();
+            assert.deepEqual({ started: result.started, existing_pid: result.existing_pid, running: result.running, serving: result.serving }, { started: false, existing_pid: process.pid, running: true, serving: false }, 'a live owner with an unavailable socket remains in place');
+            assert.match(result.probe_error ?? '', /ENOENT|ECONNREFUSED/, 'the result retains the actual failed probe');
+            process.kill(process.pid, 0);
+        }
+        finally {
+            rmSync(pidfile, { force: true });
+        }
         const retryClaim = claimDaemonOwnership('post-api-bind-failure');
         assert.equal(retryClaim.claimed, true, 'failed readiness releases the authoritative ownership claim');
         if (retryClaim.claimed) {

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -26,7 +26,7 @@
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import WebSocket from 'ws';
@@ -133,6 +133,45 @@ test('A2: POST /nodes boots a live broker; GET /nodes/{id} shows active + live p
     assert.ok(meta?.pi_pid != null && isPidAlive(meta.pi_pid), 'row records a live broker pid');
     assert.ok(existsSync(h.brokerSock(id)), 'view.sock exists for the live broker');
 });
+function installBlockedStartHook(nodeId) {
+    const root = join(h.agentHome, '.crouter', 'plugins', `blocked-start-${nodeId}`);
+    const started = join(root, 'started');
+    const release = join(root, 'release');
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name: `blocked-start-${nodeId}`,
+        version: '0.1.0',
+        description: 'message acknowledgment fixture',
+        hooks: 'hooks.json',
+        hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'block', description: 'block target launch', effects: ['waits for test release'] }],
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { existsSync, writeFileSync } = require('node:fs');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  if (request.node.id !== ${JSON.stringify(nodeId)}) {
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+    return;
+  }
+  writeFileSync(${JSON.stringify(started)}, 'started');
+  const timer = setInterval(() => {
+    if (!existsSync(${JSON.stringify(release)})) return;
+    clearInterval(timer);
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+  }, 10);
+});
+`);
+    chmodSync(executable, 0o755);
+    return { started, release };
+}
 // A3 — POST .../messages appends inbox.jsonl; POST .../reports {tier:'final'}
 //      writes the report, notifies subscribers, transitions the row
 test('A3: messages append inbox.jsonl; final report writes + notifies subscriber + transitions row', async () => {
@@ -153,6 +192,36 @@ test('A3: messages append inbox.jsonl; final report writes + notifies subscriber
     assert.equal(h.node(B)?.status, 'done', 'row status is done after final');
     await assert.rejects(() => client.pushReport(B, { tier: 'final', delivery_tier: 'deferred', body: 'invalid tiered final' }), (error) => error instanceof ApiError && error.code === 'usage' && error.message === 'delivery_tier is only valid for update reports', 'the API rejects a delivery tier on final before it can alter final delivery');
 });
+test('A3b: a durable send acknowledges while the lifecycle tick is blocked launching its idle target', async () => {
+    const target = h.fabricateBrokerNode({ lifecycle: 'resident', status: 'idle', intent: 'idle-release' });
+    const hook = installBlockedStartHook(target);
+    const inboxFile = inboxPath(target);
+    const before = countLines(inboxFile);
+    const sending = client.sendMessage(target, { body: 'wake after durable acknowledgment' });
+    let tick;
+    try {
+        await h.waitFor(() => countLines(inboxFile) === before + 1, { label: 'durable inbox append' });
+        assert.equal(h.node(target)?.cycles ?? 0, 0, 'the send has not launched the target');
+        tick = h.tick();
+        await h.waitFor(() => existsSync(hook.started), { label: 'blocked lifecycle launch' });
+        const acknowledged = await Promise.race([
+            sending,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('durable send waited for recipient launch')), 500)),
+        ]);
+        assert.equal(acknowledged.delivered, true, 'the API acknowledges the durable append');
+        assert.equal(acknowledged.revived, false, 'the response honestly reports no synchronous revive');
+        assert.equal(countLines(inboxFile), before + 1, 'exactly one inbox entry is durable while launch is blocked');
+        writeFileSync(hook.release, 'release');
+        await tick;
+        assert.equal(h.node(target)?.cycles, 1, 'the one queued entry drove lifecycle revival');
+        assert.equal(countLines(inboxFile), before + 1, 'revival did not append a second inbox entry');
+    }
+    finally {
+        if (!existsSync(hook.release))
+            writeFileSync(hook.release, 'release');
+        await tick;
+    }
+});
 // A4 — WS attach reconstructs the same settled broker snapshot as a direct
 //      ViewSocketClient; ?revive=0 on a dormant node → 409 without launching a broker
 test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketClient snapshot', async () => {

package/dist/daemon/api/handlers/bash-jobs.js

@@ -59,7 +59,7 @@ async function handleStop(ctx) {
         throw new ApiError(404, 'job_not_found', `background job ${jobId} for ${nodeId} is no longer running`, { log_path: stopped.logPath });
     }
     if (stopped.kind === 'not-stoppable') {
-        throw new ApiError(409, 'job_not_stoppable', `job ${jobId} recorded no process group`, { log_path: stopped.logPath });
+        throw new ApiError(409, 'job_not_stoppable', `job ${jobId} recorded no trusted process identity`, { log_path: stopped.logPath });
     }
     // Match `crtr node bash kill`: retire the job, then send an urgent durable
     // notice to the owning node. The terminal path sends that notice through the

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

@@ -16,6 +16,7 @@ import { appendSituationalContext, formatSituationalProse } from '../../../core/
 import { formatDataCard } from '../../../shared/generated-context.js';
 import { hasNoNaturalCycle } from '../../../core/runtime/revive-all.js';
 import { recordPendingParkActivity } from '../../park-pending.js';
+import { wantsExecution } from '../../reconcilers/node-lifecycle/wants-execution.js';
 import { hasFreshGroundState } from '../../../core/runtime/revive.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -355,13 +356,14 @@ async function handleMessage(ctx) {
     // owes a thaw; consume its deadline when that durable future wake arrives.
     if (entry.tier !== 'deferred' || meta.frozen_at !== null)
         cancelCronsOnWake(id);
-    // A wake-capable tier revives a dormant target so its inbox-watcher delivers
-    // this; deferred never wakes — it rides the target's next natural cycle. The
-    // APPENDED entry's tier decides, because a terminal target's deferred was
-    // already raised to a wake-capable tier by the append.
+    // A wake-capable entry for an active or idle target is admitted by the
+    // lifecycle tick. Reopen delivery preserves this handler's synchronous wake
+    // authority; a terminal-lifecycle row also needs it because it has no later
+    // natural cycle to consume the entry.
     let revived = false;
     let frozen = false;
-    if (entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
+    const needsSynchronousWake = req.reopen || current.lifecycle === 'terminal' || !wantsExecution(current);
+    if (needsSynchronousWake && entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
         try {
             // The entry is already durable, so a wake denied for capacity is only
             // delayed: the row freezes and the tick relaunches it — at which point