@north-light/crouter 0.3.275 → 0.3.276

package/dist/core/worktree.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join, resolve } from 'node:path';
-import { gitSync } from './git.js';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { gitAsync, gitSync } from './git.js';
 import { crtrHome } from './canvas/paths.js';
 import { isPidAlive } from './canvas/pid.js';
 import { getNode, updateNode } from './canvas/index.js';
@@ -44,7 +44,27 @@ export function openManagedWorktreeForNode(nodeId) {
     return wt?.state === 'open' ? wt : null;
 }
 function repoRootFor(cwd) {
-    return runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd pointing inside a git repository.');
+    const result = gitSync(['rev-parse', '--show-toplevel'], cwd);
+    if (result.status !== 0) {
+        const detail = (result.stderr.trim() || result.stdout.trim()).trim();
+        throw new WorktreeError('not_git_repo', `cwd ${cwd} is not a git repository`, 'Pass --cwd <real repo> pointing inside a git repository.', detail);
+    }
+    return result.stdout.trim();
+}
+function isManagedWorktreeBase(repoRoot) {
+    const path = relative(canonicalPath(managedWorktreesRoot()), canonicalPath(repoRoot));
+    return path !== '' && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+function recordedBranchExists(cwd, branch) {
+    const ref = `refs/heads/${branch}`;
+    const exists = gitSync(['show-ref', '--verify', '--quiet', ref], cwd);
+    if (exists.status === 0)
+        return true;
+    if (exists.status === 1 && exists.executionFailed !== true)
+        return false;
+    const stderr = exists.stderr.trim() || '<empty>';
+    const execution = exists.processError === undefined ? '' : `\nprocess error: ${exists.processError}`;
+    throw new WorktreeError('recorded_branch_inspection_failed', `could not inspect recorded branch '${branch}' (git show-ref exited with status ${exists.status})`, 'Inspect the repository and its Git metadata, then retry.', `status: ${exists.status}\nstderr: ${stderr}${execution}`);
 }
 function resolveLandableBase(repoRoot, baseRef) {
     const ref = `refs/heads/${baseRef}`;
@@ -142,6 +162,43 @@ function registeredWorktree(repoRoot, path, branch) {
     }
     return false;
 }
+function proveBranchContained(cwd, baseRef, branchSha) {
+    const candidates = [];
+    const localBaseRef = `refs/heads/${baseRef}`;
+    const localBase = gitSync(['rev-parse', '--verify', '--quiet', localBaseRef], cwd);
+    if (localBase.status === 0)
+        candidates.push({ ref: localBaseRef, sha: localBase.stdout.trim() });
+    const upstream = gitSync(['rev-parse', '--symbolic-full-name', '--verify', `${baseRef}@{upstream}`], cwd);
+    const upstreamRef = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/') ? upstream.stdout.trim() : `refs/remotes/origin/${baseRef}`;
+    const upstreamSha = gitSync(['rev-parse', '--verify', '--quiet', upstreamRef], cwd);
+    if (upstreamSha.status === 0)
+        candidates.push({ ref: upstreamRef, sha: upstreamSha.stdout.trim() });
+    if (candidates.length === 0)
+        return null;
+    for (const c of candidates) {
+        if (gitSync(['merge-base', '--is-ancestor', branchSha, c.sha], cwd).status === 0)
+            return { containingRef: c.ref, containingSha: c.sha };
+    }
+    for (const c of candidates) {
+        const cherry = gitSync(['cherry', c.sha, branchSha], cwd);
+        if (cherry.status !== 0)
+            continue;
+        const lines = cherry.stdout.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+        if (lines.every((l) => l.startsWith('-')))
+            return { containingRef: c.ref, containingSha: c.sha };
+    }
+    for (const c of candidates) {
+        const candidateTree = gitSync(['rev-parse', '--verify', `${c.sha}^{tree}`], cwd);
+        if (candidateTree.status !== 0)
+            continue;
+        const merged = gitSync(['merge-tree', '--write-tree', c.sha, branchSha], cwd);
+        if (merged.status !== 0)
+            continue;
+        if (merged.stdout.split('\n')[0]?.trim() === candidateTree.stdout.trim())
+            return { containingRef: c.ref, containingSha: c.sha };
+    }
+    return null;
+}
 /** Undo a creation attempt, but only resources whose recorded path, branch,
  * and original base still prove they belong to that attempt. */
 function rollbackManagedWorktreeLocked(wt, pathWasAbsent) {
@@ -235,6 +292,9 @@ function seedManagedWorktreeExclude(repoRoot) {
 }
 export function createManagedWorktree(cwd, nodeId, baseRef = 'main') {
     const repoRoot = repoRootFor(cwd);
+    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.');
+    }
     return withRepositoryWorktreeLock(repoRoot, () => {
         const baseSha = resolveLandableBase(repoRoot, baseRef);
         const path = managedWorktreePath(nodeId);
@@ -386,6 +446,67 @@ function deferredCleanupResult(wt) {
         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}.`,
     };
 }
+/** The disposal path for `close` when the recorded `crtr/*` branch is gone:
+ *  ordinary PR work moved this checkout onto a real branch. This never lands
+ *  or rebases that branch — it belongs to a workflow crouter does not own —
+ *  and never deletes it. It only AUTHORIZES the daemon sweep to remove the
+ *  checkout later, once this node's own broker has exited, and only after
+ *  proving the branch's content is already delivered. Runs after the caller
+ *  already proved the checkout clean and not mid-rebase. */
+function closeBranchMovedWorktree(nodeId, wt, actualBranch) {
+    if (registeredWorktree(wt.repo_root, wt.path, actualBranch) !== true) {
+        throw new WorktreeError('wrong_branch', `managed worktree's recorded branch ${wt.branch} no longer exists, and its checkout at ${wt.path} is not registered to ${actualBranch} either`, `Inspect ${wt.path} and its git worktree registration, then ask the user with \`crtr human send\` if you are unsure how to proceed.`);
+    }
+    const actualSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+    const proof = proveBranchContained(wt.path, wt.base_ref, actualSha);
+    if (proof === null) {
+        throw new WorktreeError('branch_moved_unlanded', `managed worktree's recorded branch ${wt.branch} no longer exists; its checkout is now on ${actualBranch} at ${actualSha}, which carries content local base branch '${wt.base_ref}' does not yet contain`, `Land or push ${actualBranch} through its own workflow (merge its PR, or fast-forward '${wt.base_ref}' to include it) before closing, or ask the user with \`crtr human send\` if you are unsure how ${actualBranch} should be delivered.`);
+    }
+    const commonDir = commonGitDir(wt.repo_root);
+    // Recheck identity immediately before writing the authorization: nothing
+    // about the checkout may have moved between the proof above and this write.
+    const stillRegistered = registeredWorktree(wt.repo_root, wt.path, actualBranch) === true;
+    const stillOnBranch = currentBranch(wt.path) === actualBranch;
+    const stillAtSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.') === actualSha;
+    if (!stillRegistered || !stillOnBranch || !stillAtSha) {
+        throw new WorktreeError('wrong_branch', `managed worktree at ${wt.path} changed while closing`, `Inspect ${wt.path}, then rerun \`crtr node worktree close\`.`);
+    }
+    const disposal = { observed_branch: actualBranch, observed_sha: actualSha, common_dir: commonDir, authorized: new Date().toISOString() };
+    persistClosedWorktreeState(nodeId, { ...wt, disposal }, 'pending');
+    const remove = `git -C ${shellQuote(wt.repo_root)} worktree remove ${shellQuote(wt.path)}`;
+    return {
+        node_id: nodeId,
+        branch: actualBranch,
+        worktree_path: wt.path,
+        // Nothing was rebased or fast-forwarded here: `${actualBranch}`'s content
+        // was already proven contained in `${proof.containingRef}` at `${proof.containingSha}`.
+        landed_sha: actualSha,
+        worktree_removed: false,
+        worktree_remove_error: `cleanup pending: the caller checkout at ${wt.path} remains intact. After its node exits, run \`${remove}\` after confirming it is safe to delete.`,
+        branch_deleted: false,
+        branch_delete_error: `${actualBranch} is not a crtr-managed branch and will never be deleted automatically; it is preserved once the checkout above is removed.`,
+    };
+}
+/** Word the `no_managed_worktree` refusal from the record's ACTUAL state
+ *  rather than a blanket "no worktree". A `closed`/`cleanup: pending` record
+ *  still has its checkout on disk, scheduled for the daemon sweep to finish —
+ *  that is not lost ownership, and three separate reports (#849, #862, #872)
+ *  were misdiagnosed because the old wording read as if it were. */
+function noManagedWorktreeMessage(nodeId, verb) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (wt == null)
+        return { message: `node ${nodeId} has no managed worktree`, next: `Nothing to ${verb} for this node.` };
+    if (wt.state === 'abandoned') {
+        const branch = wt.abandoned?.branch ?? wt.branch;
+        return { message: `node ${nodeId}'s managed worktree was already abandoned`, next: `Nothing to ${verb} for this node; its work was retained on branch ${branch}.` };
+    }
+    if (wt.state === 'closed') {
+        return wt.cleanup === 'complete'
+            ? { message: `node ${nodeId}'s managed worktree is already closed and its cleanup is complete`, next: `Nothing to ${verb} for this node.` }
+            : { message: `node ${nodeId}'s managed worktree is already closed; this is not lost ownership — its checkout at ${wt.path} is scheduled for automatic cleanup once that is safe`, next: `Nothing to ${verb} for this node. The daemon sweep finishes removing ${wt.path} on its own; inspect it directly only if it still needs manual attention.` };
+    }
+    return { message: `node ${nodeId} has no open managed worktree`, next: `Nothing to ${verb} for this node.` };
+}
 function closeManagedWorktreeLocked(nodeId) {
     const node = getNode(nodeId);
     if (node === null) {
@@ -393,7 +514,8 @@ function closeManagedWorktreeLocked(nodeId) {
     }
     const wt = openManagedWorktreeForNode(nodeId);
     if (wt === null) {
-        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to close for this node.');
+        const { message, next } = noManagedWorktreeMessage(nodeId, 'close');
+        throw new WorktreeError('no_managed_worktree', message, next);
     }
     if (!existsSync(wt.path)) {
         const proof = proveAbsentPathManagedWorktree(wt);
@@ -427,7 +549,16 @@ function closeManagedWorktreeLocked(nodeId) {
     const branch = currentBranch(wt.path);
     if (branch !== wt.branch) {
         const found = branch === 'HEAD' ? 'detached HEAD' : branch;
-        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the user with \`crtr human send\` if you are unsure why it changed, then rerun \`crtr node worktree close\`.`);
+        const recordedRefExists = recordedBranchExists(wt.path, wt.branch);
+        if (recordedRefExists || branch === 'HEAD') {
+            throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, recordedRefExists
+                ? `Check out ${wt.branch} in ${wt.path} before closing, or ask the user with \`crtr human send\` if you are unsure why it changed, then rerun \`crtr node worktree close\`.`
+                : `The recorded branch ${wt.branch} no longer exists, and ${wt.path} is in detached HEAD, so there is no branch to preserve. Check out or create a branch there before closing, or ask the user with \`crtr human send\` if you are unsure how to proceed.`);
+        }
+        // The recorded crtr/* branch is gone: ordinary PR work moved this checkout
+        // onto a real branch. The checkout is already proven clean and not
+        // mid-rebase (both checked above), so disposal may proceed.
+        return closeBranchMovedWorktree(nodeId, wt, branch);
     }
     let baseSha;
     try {
@@ -527,16 +658,45 @@ export function closeManagedWorktree(nodeId) {
 const ABANDON_AUTHOR_NAME = 'crtr-abandon';
 const ABANDON_AUTHOR_EMAIL = 'crtr-abandon@localhost';
 const ABANDON_SUBJECT = 'crtr-abandon';
-function persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by) {
+function persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by, branch = wt.branch) {
     updateNode(nodeId, {
         cwd: wt.repo_root,
         managed_worktree: {
             ...wt,
             state: 'abandoned',
-            abandoned: { branch: wt.branch, tip_sha: tipSha, at, by },
+            abandoned: { branch, tip_sha: tipSha, at, by },
         },
     });
 }
+/** The disposal path for `abandon` when the recorded `crtr/*` branch is gone:
+ *  ordinary PR work moved this checkout onto a real branch. Abandon never
+ *  lands that branch and — unlike the ordinary path above — never invents a
+ *  commit on it: a synthetic `crtr-abandon` marker on someone's real PR
+ *  branch is not a trade this code may make on their behalf. So this
+ *  requires the checkout already clean and not mid-operation, then removes
+ *  only the checkout and preserves the actual branch and its commits exactly
+ *  as they stand. The caller already confirmed the node is not running. */
+function abandonBranchMovedWorktree(nodeId, wt, actualBranch, by) {
+    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 abandon\`.`);
+    }
+    const dirty = statusPorcelain(wt.path);
+    if (dirty !== '') {
+        throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `The recorded branch ${wt.branch} no longer exists; its checkout is now on ${actualBranch} with uncommitted changes crtr will not commit on your behalf. Commit or stash them in ${wt.path}, then rerun \`crtr node worktree abandon\`.`);
+    }
+    if (registeredWorktree(wt.repo_root, wt.path, actualBranch) !== true) {
+        throw new WorktreeError('wrong_branch', `managed worktree's recorded branch ${wt.branch} no longer exists, and its checkout at ${wt.path} is not registered to ${actualBranch} either`, `Inspect ${wt.path} and its git worktree registration, then ask the user with \`crtr human send\` if you are unsure how to proceed.`);
+    }
+    const actualSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the worktree manually, then retry.');
+    // Recheck identity immediately before the destructive step.
+    if (registeredWorktree(wt.repo_root, wt.path, actualBranch) !== true || currentBranch(wt.path) !== actualBranch) {
+        throw new WorktreeError('wrong_branch', `managed worktree at ${wt.path} changed while abandoning`, `Inspect ${wt.path}, then rerun \`crtr node worktree abandon\`.`);
+    }
+    runGit(wt.repo_root, ['worktree', 'remove', wt.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+    const at = new Date().toISOString();
+    persistAbandonedWorktreeState(nodeId, wt, actualSha, at, by, actualBranch);
+    return { node_id: nodeId, branch: actualBranch, tip_sha: actualSha, worktree_path: wt.path, branch_deleted: false };
+}
 function createAbandonMarker(wt, parentSha, nodeId, at) {
     const treeSha = runGit(wt.repo_root, ['rev-parse', `${parentSha}^{tree}`], 'abandon_tree_failed', 'Inspect the branch manually, then retry.');
     const markerSha = runGit(wt.repo_root, ['-c', `user.name=${ABANDON_AUTHOR_NAME}`, '-c', `user.email=${ABANDON_AUTHOR_EMAIL}`, 'commit-tree', treeSha, '-p', parentSha, '-m', ABANDON_SUBJECT, '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the branch manually, then retry.');
@@ -550,7 +710,8 @@ function abandonManagedWorktreeLocked(nodeId, by) {
     }
     const wt = openManagedWorktreeForNode(nodeId);
     if (wt === null) {
-        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+        const { message, next } = noManagedWorktreeMessage(nodeId, 'abandon');
+        throw new WorktreeError('no_managed_worktree', message, next);
     }
     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.');
@@ -558,8 +719,17 @@ function abandonManagedWorktreeLocked(nodeId, by) {
     if (!existsSync(wt.path)) {
         throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, missingWorktreeRecoveryHint(wt));
     }
-    if (currentBranch(wt.path) !== wt.branch) {
-        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch})`, `Check out ${wt.branch} in ${wt.path}, then rerun \`crtr node worktree abandon\`.`);
+    const actualBranch = currentBranch(wt.path);
+    if (actualBranch !== wt.branch) {
+        const recordedRefExists = recordedBranchExists(wt.path, wt.branch);
+        if (recordedRefExists || actualBranch === 'HEAD') {
+            throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}${actualBranch === 'HEAD' ? ', found detached HEAD' : ''})`, recordedRefExists
+                ? `Check out ${wt.branch} in ${wt.path}, then rerun \`crtr node worktree abandon\`.`
+                : `The recorded branch ${wt.branch} no longer exists, and ${wt.path} is in detached HEAD, so there is no branch to preserve. Check out or create a branch there, then rerun \`crtr node worktree abandon\`.`);
+        }
+        // The recorded crtr/* branch is gone: ordinary PR work moved this checkout
+        // onto a real branch.
+        return abandonBranchMovedWorktree(nodeId, wt, actualBranch, by);
     }
     const at = new Date().toISOString();
     const clean = proveCleanEmptyManagedWorktree(wt);
@@ -575,6 +745,15 @@ function abandonManagedWorktreeLocked(nodeId, by) {
         persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by);
         return { node_id: nodeId, branch: wt.branch, tip_sha: tipSha, worktree_path: wt.path, branch_deleted: false };
     }
+    // A clean branch with committed work already has its complete history. The
+    // abandon record supplies the disposition; an empty provenance commit would
+    // only move the local branch away from an already-pushed tip.
+    if (!isRebaseInProgress(wt.path) && statusPorcelain(wt.path) === '') {
+        runGit(wt.repo_root, ['worktree', 'remove', wt.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+        const tipSha = runGit(wt.repo_root, ['rev-parse', `refs/heads/${wt.branch}`], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+        persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by);
+        return { node_id: nodeId, branch: wt.branch, tip_sha: tipSha, worktree_path: wt.path, branch_deleted: false };
+    }
     runGit(wt.path, ['add', '--all'], 'abandon_stage_failed', 'Inspect the worktree manually, then retry.');
     runGit(wt.path, ['-c', `user.name=${ABANDON_AUTHOR_NAME}`, '-c', `user.email=${ABANDON_AUTHOR_EMAIL}`, 'commit', '--allow-empty', '-m', ABANDON_SUBJECT, '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the worktree manually, then retry.');
     runGit(wt.repo_root, ['worktree', 'remove', wt.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
@@ -775,6 +954,39 @@ export function autoDropCleanManagedWorktreeLocked(nodeId, wt, proof) {
  *  `open_managed_worktree` guard then still applies unchanged — real
  *  commits, real uncommitted changes, and a lost race all require the
  *  explicit path. */
+function cleanCurrentBranchTip(wt) {
+    if (wt.state !== 'open' || !existsSync(wt.path) || isRebaseInProgress(wt.path))
+        return null;
+    const branch = gitSync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
+    if (branch.status !== 0 || branch.stdout.trim() !== wt.branch)
+        return null;
+    const status = gitSync(['status', '--porcelain'], wt.path);
+    if (status.status !== 0 || status.stdout.trim() !== '')
+        return null;
+    const head = gitSync(['rev-parse', 'HEAD'], wt.path);
+    return head.status === 0 ? head.stdout.trim() : null;
+}
+export async function branchIsPushedAtCurrentTip(wt) {
+    const initialTip = cleanCurrentBranchTip(wt);
+    if (initialTip === null)
+        return false;
+    // A cached origin/<branch> can be stale in either direction. Query origin's
+    // branch ref directly and require exact-tip equality: a remote that has an
+    // older commit would still leave newer local work stranded at finalization.
+    // This runs asynchronously with a bounded, non-interactive Git invocation so
+    // an unreachable remote never stalls crtrd's event loop.
+    const ssh = process.env['GIT_SSH_COMMAND'] ?? process.env['GIT_SSH'] ?? 'ssh';
+    const remote = await gitAsync(['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${wt.branch}`], wt.path, undefined, { timeoutMs: 10_000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: `${ssh} -o BatchMode=yes` } });
+    if (remote.status !== 0)
+        return false;
+    const expectedRef = `refs/heads/${wt.branch}`;
+    const matchingLine = remote.stdout.split('\n').find((line) => line.endsWith(`\t${expectedRef}`));
+    if (matchingLine?.slice(0, matchingLine.indexOf('\t')) !== initialTip)
+        return false;
+    // The remote proof is useful only if the local checkout is still the exact
+    // clean tip it inspected when finalization begins.
+    return cleanCurrentBranchTip(wt) === initialTip;
+}
 export function autoDropCleanManagedWorktree(nodeId) {
     const wt = openManagedWorktreeForNode(nodeId);
     if (wt === null)

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

@@ -170,12 +170,13 @@ function handleArm(ctx) {
         ? requireUtcIso(req.expires_at, 'expires_at')
         : null;
     const envJson = typeof req.env_json === 'string' && req.env_json !== '' ? requireEnvJson(req.env_json) : null;
-    const onOutput = requireEnum(req.on_output, 'on_output', ['silent', 'on-failure', 'always', 'on-change'], 'on-failure');
-    const overlap = requireEnum(req.overlap, 'overlap', ['skip', 'queue', 'replace'], 'skip');
-    const tier = requireEnum(req.tier, 'tier', ['normal', 'urgent', 'critical'], 'normal');
     // Sink: required by the delivering dispositions, meaningless otherwise —
-    // progressive disclosure via the error that names the need.
+    // progressive disclosure via the error that names the need. A node sink is
+    // polling its recipient, so unchanged stdout must not wake it again by default.
     const rawSink = typeof req.sink === 'string' && req.sink.trim() !== '' ? req.sink.trim() : null;
+    const onOutput = requireEnum(req.on_output, 'on_output', ['silent', 'on-failure', 'always', 'on-change'], rawSink?.startsWith('node:') ? 'on-change' : 'on-failure');
+    const overlap = requireEnum(req.overlap, 'overlap', ['skip', 'queue', 'replace'], 'skip');
+    const tier = requireEnum(req.tier, 'tier', ['normal', 'urgent', 'critical'], 'normal');
     const delivers = onOutput === 'always' || onOutput === 'on-change';
     if (delivers && rawSink === null) {
         throw new InputError({

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

@@ -232,6 +232,11 @@ async function handleMessage(ctx) {
         };
         return { status: 201, body };
     }
+    // Interactive delivery has the same finalization doorway as durable mail:
+    // a live broker remains reachable briefly after its final claim, but must not
+    // accept a mandate it cannot finalize. `--reopen` is the deliberate exception.
+    if (req.delivery === 'interactive' && !req.reopen)
+        assertNotFinalized(id);
     // An interactive reopen commits before even choosing its engine-or-inbox
     // route. A live transport race then falls back with this same committed state.
     let reopenCommitted = false;

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

@@ -141,6 +141,8 @@ function buildRecipe(req, parent, cwd) {
         recipe.worktree = true;
     if (typeof req.worktree === 'string')
         recipe.worktreeBase = req.worktree;
+    if (req.worktree !== undefined)
+        recipe.worktreeCwd = resolve(req.pin_cwd ?? req.cwd ?? cwd);
     if (req.fork_from !== undefined)
         recipe.forkFrom = req.fork_from;
     if (req.model !== undefined)

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

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { push, FinalizationError } from '../../../core/feed/feed.js';
-import { autoDropCleanManagedWorktree, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
+import { autoDropCleanManagedWorktree, branchIsPushedAtCurrentTip, 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';
@@ -51,14 +51,19 @@ async function handlePush(ctx) {
     // `final` with an OPEN managed worktree, BEFORE the push/transition (spec
     // §6.2 — worktree fs ops are server-side). A provably-clean, zero-commit
     // worktree is auto-dropped so a read-only or already-landed node
-    // can finish without an explicit `node worktree close`; any real unlanded
-    // work instead blocks with the parity `open_managed_worktree` error,
+    // can finish without an explicit `node worktree close`; a clean worktree
+    // whose exact tip is already on origin can also finish while retaining its
+    // branch and checkout. Any work that is neither locally landed nor remotely
+    // retained instead blocks with the parity `open_managed_worktree` error,
     // round-tripped via CrtrError.details so the CLI renders the same InputError
     // (next-hint included) it surfaced before B-5 re-homed this to the server.
     let autoDroppedPath;
     if (req.tier === 'final' && hasOpenManagedWorktree(getNode(id))) {
         const dropped = autoDropCleanManagedWorktree(id);
-        if (dropped === null) {
+        if (dropped !== null) {
+            autoDroppedPath = dropped.worktree_path;
+        }
+        else if (!(await branchIsPushedAtCurrentTip(getNode(id).managed_worktree))) {
             // Thrown as InputError so `toErrorBody` round-trips the FULL structured
             // payload (code + message + next) into `ApiError.details`, and the CLI's
             // shared `apiErrorToCliError` reconstructs it byte-for-byte — no
@@ -70,11 +75,10 @@ async function handlePush(ctx) {
                     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`.';
+                        : 'Commit the remaining work in the worktree, push its branch to origin at its current tip, then rerun `crtr push final`; or run `crtr node worktree close` to land it locally.';
                 })(),
             });
         }
-        autoDroppedPath = dropped.worktree_path;
     }
     const result = await pushOrRethrow(id, req);
     const transitioned = req.tier === 'final' && before !== undefined
@@ -100,7 +104,7 @@ async function pushOrRethrow(id, req) {
             throw new InputError({
                 error: 'already_finalized',
                 message: 'This node already submitted its canonical final result.',
-                next: 'Do not push another final from this node.',
+                next: 'Push an update with the new information, then stop.',
             });
         }
         if (err instanceof FinalizationError && err.code === 'finalization_forbidden') {

package/dist/types.d.ts

@@ -97,7 +97,7 @@ export interface PluginManifest {
     commands?: string;
     /** Plugin-root-relative path to a declarative hook manifest (`hooks.json`).
      *  Must be declared together with `hookExecutable`; hooks are trusted local
-     *  code and are unavailable to endpoint archive plugins. */
+     *  code. */
     hooks?: string;
     /** Plugin-root-relative executable that dispatches declarations in `hooks`.
      *  Must be a regular file with a POSIX executable permission bit. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.275",
+  "version": "0.3.276",
   "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.275",
+  "version": "0.3.276",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.275",
+      "version": "0.3.276",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {