devlyn-cli 4.3.31 → 4.3.32

package/config/skills/_shared/task-complete.py

@@ -1480,17 +1480,24 @@ def cleanup_workspace(receipt, path, *, warnings):
             sync_surviving_directory(Path(receipt['common_gitdir']) / 'worktrees')
 
 
-def cleanup(receipt, path, pr, *, warnings=None):
-    warnings = [] if warnings is None else warnings
+def verify_delivery(receipt, path, pr):
+    """Evidence that the accepted source is delivered, checked before anything is removed."""
     if pr is not None:
         require(pr["state"] == "MERGED" and pr.get("mergedAt") and pr.get("mergeCommit", {}).get("oid"), "actual matching merge evidence is required")
     sha = receipt["publish_sha"]
-    branch_ref = "refs/heads/" + receipt["branch"]
     # The recovery ref keeps the accepted commit reachable, so squash and
     # rebase merges need only the merge commit on base.
     verify_custody(receipt, path)
     gref(receipt, "merge-base", "--is-ancestor", pr["mergeCommit"]["oid"] if pr else sha, remote_base(receipt))
     gref(receipt, "merge-base", "--is-ancestor", receipt["source_sha"], sha)
+    # The base was fetched through the remote's name, so that name must still bind the receipt's repository.
+    require(remote_url(receipt) == receipt["remote_url"], "remote changed during the delivery checks; retain resources")
+
+
+def remove_delivered(receipt, path, *, warnings=None):
+    warnings = [] if warnings is None else warnings
+    sha = receipt["publish_sha"]
+    branch_ref = "refs/heads/" + receipt["branch"]
     cleanup_workspace(receipt, path, warnings=warnings)
     checked_out = [p for p, row in registrations(receipt).items() if row.get("branch") == branch_ref]
     require(not checked_out, "task branch is still checked out at " + ", ".join(checked_out) + "; switch it off the task branch before cleanup")
@@ -1511,6 +1518,11 @@ def cleanup(receipt, path, pr, *, warnings=None):
     atomic_json(path, receipt)
 
 
+def cleanup(receipt, path, pr, *, warnings=None):
+    verify_delivery(receipt, path, pr)
+    remove_delivered(receipt, path, warnings=warnings)
+
+
 def resolve_receipt(path, *, operation_id=None):
     """Resolve a lost retirement reply without guessing between operations."""
     require(path.name == 'receipt.json' and path == path.resolve(), 'receipt locator must be nonsymlink and absolute')
@@ -1630,13 +1642,17 @@ def completion_result(receipt, path, status, *, warnings=None):
 
 
 def cleanup_delivered(receipt, path, pr, *, warnings=None):
+    # Missing evidence leaves delivery unrecorded; once it holds, a refused removal retains what it guards.
+    verify_delivery(receipt, path, pr)
     try:
-        cleanup(receipt, path, pr, warnings=warnings)
+        remove_delivered(receipt, path, warnings=warnings)
     except (CompletionError, OSError) as error:
-        managed_outage = storage_call('managed_receipt', receipt)
-        if not isinstance(error, (WritersUnobservable, WriterActive)) and not managed_outage:
+        if receipt.get('status') == 'COMPLETE':
+            # Every workspace and ref removal finished and only the final record write failed: the resume ends COMPLETE,
+            # or CLEANUP_PENDING while a scratch cleanup retained on its own remains.
             raise
-        reason = manual_removal(receipt, path, error) if managed_outage and isinstance(error, WritersUnobservable) else str(error)
+        managed = storage_call('managed_receipt', receipt)
+        reason = manual_removal(receipt, path, error) if managed and isinstance(error, WritersUnobservable) else str(error)
         receipt['workspace_cleanup'] = {'status': 'RETAINED', 'reason': reason, 'resume': receipt_resume('complete', path, receipt)}
         atomic_json(path, receipt)
 
@@ -1681,7 +1697,14 @@ def reconcile(common, allocated, anchor, *, exclude_receipts=(), warnings=None):
                 if storage_call("managed_receipt", receipt):
                     cleanup_delivered(receipt, path, pr, warnings=warnings)
                 else:
-                    cleanup(receipt, path, pr, warnings=warnings)
+                    try:
+                        cleanup(receipt, path, pr, warnings=warnings)
+                    except (CompletionError, OSError) as error:
+                        if "workspace_cleanup" in receipt:
+                            # A retained cleanup names its latest refusal, which may guard less than the first.
+                            receipt["workspace_cleanup"]["reason"] = str(error)
+                            atomic_json(path, receipt)
+                        raise
                 results.append(completion_result(receipt, path, "COMPLETE", warnings=warnings))
         except (Exception, SystemExit) as error:
             results.append({"receipt": str(path), "status": "RETAINED", "reason": str(error)})
@@ -1794,7 +1817,7 @@ def complete(args, *, warnings=None):
             inspect_workspace(receipt)
             verify_files(Path(receipt["worktree"]), receipt["files"])
             require(remote_head(receipt, receipt["branch"]) == receipt["publish_sha"], "remote head race before merge")
-            refused = None
+            refused = waits = None
             if not pr.get("autoMergeRequest"):
                 if not info["mergeCommitAllowed"]:
                     refused = "repository disallows merge commits"
@@ -1818,9 +1841,11 @@ def complete(args, *, warnings=None):
                                 break
                             if attempt < 9:
                                 time.sleep(2)
-                        if state not in {"CLEAN", "HAS_HOOKS", "UNSTABLE"}:
+                        if state in {"BLOCKED", "UNKNOWN"}:
+                            waits = state
+                        elif state not in {"CLEAN", "HAS_HOOKS", "UNSTABLE"}:
                             refused = "pull request is not mergeable: " + state
-                    if not refused:
+                    if not refused and not waits:
                         try:
                             gh(receipt, "pr", "merge", str(pr["number"]), *auto, "--merge", "--match-head-commit", receipt["publish_sha"])
                         except CompletionError as error:
@@ -1828,8 +1853,10 @@ def complete(args, *, warnings=None):
             pr = json.loads(gh(receipt, "pr", "view", str(pr["number"]), "--json", PR_FIELDS))
             validate_pr(receipt, pr)
             if pr["state"] != "MERGED":
-                # Merge only when the repository allows it; a refused request leaves the PR for a person.
-                return dict(result("PR"), merge_refused=refused) if refused and not pr.get("autoMergeRequest") else result("PENDING")
+                # Only a refusal leaves the PR for a person; merge_waits: the resume merges once the PR is mergeable.
+                if refused and not pr.get("autoMergeRequest"):
+                    return dict(result("PR"), merge_refused=refused)
+                return dict(result("PENDING"), **({"merge_waits": waits} if waits else {}))
         if pr:
             receipt["merge"] = pr
             atomic_json(path, receipt)
@@ -2089,6 +2116,9 @@ class CompletionTests(unittest.TestCase):
         self.bin.mkdir()
         self.data = self.root / "gh.json"
         self.data.write_text(json.dumps({"bare": str(self.bare)}), encoding="utf-8")
+        # A commit's detached automatic maintenance would still write into .git while a test reads the tree. A file, not
+        # GIT_CONFIG_COUNT: the storage suite reuses this fixture with a native helper that refuses that variable.
+        (self.root / "gitconfig").write_text("[maintenance]\n\tauto = false\n", encoding="utf-8")
         self.env = {**os.environ, "GIT_CONFIG_NOSYSTEM": "1", "GIT_CONFIG_GLOBAL": str(self.root / "gitconfig"),
                     "GIT_AUTHOR_NAME": "Fixture", "GIT_AUTHOR_EMAIL": "fixture@example.invalid",
                     "GIT_COMMITTER_NAME": "Fixture", "GIT_COMMITTER_EMAIL": "fixture@example.invalid",
@@ -2144,6 +2174,14 @@ class CompletionTests(unittest.TestCase):
                                   repository="test/project", base="main", remote="origin", worktree=str(worktree),
                                   local_base=None, from_receipt=None, start=None)
 
+    def test_fixture_commit_starts_no_automatic_maintenance(self):
+        # Its detached child would still write into .git while a test reads the tree or cleanup removes it.
+        trace = self.root / "trace.json"
+        self.env["GIT_TRACE2_EVENT"] = str(trace)
+        self.g("commit", "-q", "--allow-empty", "-m", "traced")
+        children = [line for line in trace.read_text(encoding="utf-8").splitlines() if '"event":"child_start"' in line]
+        self.assertEqual(children, [])
+
     def test_allocation_marks_exclusively_created_empty_target_before_checkout(self):
         # Prediction: persisted intent precedes exclusive creation and marking; real Git then populates that directory.
         from unittest.mock import patch
@@ -3118,7 +3156,7 @@ ctypes.CDLL(None).pthread_exit(None)
             error.storage_error = {'code': 'storage_unavailable'}
             raise error
         args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=True)
-        with patch.dict(os.environ, self.env), patch.dict(complete.__globals__, managed_registration=lambda receipt, **kwargs: {}, cleanup=outage):
+        with patch.dict(os.environ, self.env), patch.dict(complete.__globals__, managed_registration=lambda receipt, **kwargs: {}, remove_delivered=outage):
             result = complete(args)
         self.assertEqual((result['status'], result['delivery_status']), ('CLEANUP_PENDING', 'COMPLETE'))
         self.assertIn('complete --receipt', result['resume'])
@@ -3133,13 +3171,17 @@ ctypes.CDLL(None).pthread_exit(None)
         receipt.update(mode='managed', allocation='managed_owned', delivery='COMPLETE', writers_released=True,
                        storage={'decision': {'registration': {'fixture': True}}, 'request': {'operation_id': 'saved'}, 'result': {'closure_result': {'established_by': 'never_admitted', 'operation_id': 'saved'}}})
         atomic_json(self.receipt, receipt)
+        calls = []
         def outage(*args, **kwargs):
+            calls.append(args)
             error = CompletionError('authority offline during reconciliation')
             error.storage_error = {'code': 'storage_unavailable'}
             raise error
-        with patch.dict(os.environ, self.env), patch.dict(reconcile.__globals__, managed_registration=lambda receipt, **kwargs: {}, cleanup=outage):
+        with patch.dict(os.environ, self.env), patch.dict(reconcile.__globals__, managed_registration=lambda receipt, **kwargs: {}, remove_delivered=outage):
             [result] = reconcile(Path(receipt['common_gitdir']), self.receipt.with_name('other.json'), self.work)
+        self.assertEqual(len(calls), 1)
         self.assertEqual((result['status'], result['delivery_status']), ('CLEANUP_PENDING', 'COMPLETE'))
+        self.assertEqual(result['workspace_cleanup']['reason'], 'authority offline during reconciliation')
         self.assertIn('complete --receipt', result['resume'])
         self.assertTrue(self.task.exists())
 
@@ -3164,6 +3206,42 @@ ctypes.CDLL(None).pthread_exit(None)
         d = read_json(self.data)
         self.assertEqual((d["pushs"], d.get("creates", 0)), (0, 0))
 
+    def test_unchanged_failed_final_receipt_write_raises_and_resumes_to_complete(self):
+        # Prediction: every removal finished and only the final status-COMPLETE record write fails, so complete raises
+        # that error and the printed resume ends COMPLETE. Before: retained as CLEANUP_PENDING on a COMPLETE receipt,
+        # which every resume reported again.
+        from unittest.mock import patch
+        self.allocate(); self.accept(unchanged=True)
+        self.cli("accept", "--receipt", self.receipt, "--acceptance", self.acceptance)
+        real, failed = atomic_json, []
+        def final_write_fails(path, value):
+            real(path, value)
+            if value.get("status") == "COMPLETE" and "workspace_cleanup" not in value and not failed:
+                failed.append(path)
+                raise OSError(5, "fixture final receipt write failure")
+        args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=True)
+        with patch.dict(os.environ, self.env), patch.dict(complete.__globals__, atomic_json=final_write_fails):
+            with self.assertRaises(OSError):
+                complete(args)
+        self.assertFalse(self.task.exists())
+        result, _ = self.complete("--writers-stopped", acceptance=False)
+        self.assertEqual((result["status"], result["workspace_cleanup"]), ("COMPLETE", None))
+
+    def test_unchanged_removal_os_error_is_retained_with_delivery_complete(self):
+        # Prediction: an OSError raised while the workspace is removed (the records copy) is retained like a refusal:
+        # delivery COMPLETE, CLEANUP_PENDING naming the error, tree and task ref kept. Fails if only CompletionError is retained.
+        from unittest.mock import patch
+        self.allocate(); self.accept(unchanged=True)
+        args = argparse.Namespace(receipt=str(self.receipt), acceptance=str(self.acceptance), mode=None, local_only=False, writers_stopped=True)
+        with patch.dict(os.environ, self.env), \
+                patch.object(shutil, "copytree", side_effect=OSError(errno.ENOSPC, "fixture records copy failure")):
+            result = complete(args)
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("fixture records copy failure", result["workspace_cleanup"]["reason"])
+        self.assertEqual(read_json(self.receipt)["delivery"], "COMPLETE")
+        self.assertTrue(self.task.exists())
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+
     def test_unchanged_writer_retention_reconciles_on_allocate(self):
         # Prediction: the next allocation retries on-base delivery once writer observation succeeds.
         from unittest.mock import Mock, patch
@@ -3232,7 +3310,8 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual(self.complete(acceptance=False)[0]["status"], "COMPLETE")
 
     def test_merged_foreign_remote_head_records_merge_and_retains_ref(self):
-        # Prediction: merged PRs record merge evidence and reach cleanup's remote-ref retention guard.
+        # Prediction: merged PRs record merge evidence and reach cleanup's remote-ref retention guard, which keeps both
+        # task refs and leaves the merged delivery COMPLETE (CLEANUP_PENDING). Before: BLOCKED, delivery unrecorded.
         self.allocate(); self.accept()
         self.complete("--mode", "pr")
         self.run_cmd(["gh", "pr", "merge", "1", "--merge", "--match-head-commit", self.sha,
@@ -3240,11 +3319,113 @@ ctypes.CDLL(None).pthread_exit(None)
         self.g("commit", "--allow-empty", "-m", "foreign commit")
         foreign = self.g("rev-parse", "HEAD")
         self.g("push", "origin", "+" + foreign + ":refs/heads/task/fixture")
-        result, _ = self.complete("--writers-stopped", success=False)
-        self.assertEqual(result["status"], "BLOCKED")
-        self.assertIn("remote branch changed after merge; retain ref", result["reason"])
+        result, _ = self.complete("--writers-stopped")
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("remote branch changed after merge; retain ref", result["workspace_cleanup"]["reason"])
         self.assertEqual(read_json(self.receipt)["merge"], read_json(self.data)["prs"][0])
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], foreign)
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+
+    def test_merged_task_branch_checked_out_elsewhere_keeps_both_task_refs(self):
+        # Prediction: with the task branch also checked out in another worktree, the merged delivery is COMPLETE and
+        # reports CLEANUP_PENDING naming that worktree; neither task ref is deleted. Once that worktree leaves the branch,
+        # the printed resume deletes both. Before: BLOCKED, delivery unrecorded.
+        self.allocate(); self.accept()
+        self.complete("--mode", "pr", "--writers-stopped")
+        self.merge_pr()
+        other = self.root / "other"
+        self.g("worktree", "add", "--force", str(other), "task/fixture")
+        result, _ = self.complete()
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("task branch is still checked out at " + str(other), result["workspace_cleanup"]["reason"])
+        self.assertEqual(read_json(self.receipt)["delivery"], "COMPLETE")
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+        self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
+        self.g("switch", "--detach", work=other)
+        result, _ = self.cli(*shlex.split(result["resume"])[2:])
+        self.assertEqual((result["status"], result["workspace_cleanup"]), ("COMPLETE", None))
+        self.assertFalse(self.task.exists())
+        self.assertEqual(self.g("branch", "--list", "task/fixture"), "")
+        self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
+
+    def test_delivery_evidence_failure_blocks_with_delivery_unrecorded(self):
+        # Prediction: evidence is checked before any removal, so a PR view that is not merge evidence, or a changed
+        # custody manifest, stops completion BLOCKED with delivery left at PR and nothing removed. Unchanged on origin/main;
+        # fails if the evidence checks move inside the retention boundary.
+        self.allocate(); self.accept()
+        self.assertEqual(self.complete("--mode", "pr", "--writers-stopped")[0]["status"], "PR")
+        pr = read_json(self.data)["prs"][0]
+        manifest = self.receipt.parent / "manifest.json"
+        for case, reason in (("merge evidence", "actual matching merge evidence is required"),
+                             ("custody manifest", "custody manifest changed")):
+            with self.subTest(case=case):
+                if case == "merge evidence":
+                    self.configure(prs=[dict(pr, state="MERGED", mergedAt=None, mergeCommit=None)])
+                else:
+                    self.configure(prs=[pr])
+                    self.merge_pr()
+                    manifest.write_text("{}\n", encoding="utf-8")
+                result, r = self.complete(success=False)
+                self.assertEqual((r.returncode, result["status"]), (1, "BLOCKED"))
+                self.assertIn(reason, result["reason"])
+                receipt = read_json(self.receipt)
+                self.assertEqual((receipt["delivery"], receipt.get("status")), ("PR", None))
+                self.assertNotIn("workspace_cleanup", receipt)
+                self.assertTrue(self.task.exists())
+                self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+                self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
+
+    def test_managed_delivery_evidence_failure_raises_with_delivery_unrecorded(self):
+        # Prediction: a managed receipt's changed custody manifest also raises before any removal, delivery unrecorded.
+        # Before: retained as CLEANUP_PENDING with delivery COMPLETE.
+        from unittest.mock import patch
+        self.allocate(); self.accept(unchanged=True)
+        self.cli('accept', '--receipt', self.receipt, '--acceptance', self.acceptance)
+        receipt = read_json(self.receipt)
+        receipt.update(mode='managed', allocation='managed_owned', storage={'decision': {'registration': {'fixture': True}}, 'request': {'operation_id': 'saved'}, 'result': {
+            'closure_result': {'established_by': 'never_admitted', 'operation_id': 'saved'}}})
+        atomic_json(self.receipt, receipt)
+        (self.receipt.parent / 'manifest.json').write_text('{}\n', encoding='utf-8')
+        args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=True)
+        with patch.dict(os.environ, self.env), patch.dict(complete.__globals__, managed_registration=lambda receipt, **kwargs: {}):
+            with self.assertRaisesRegex(CompletionError, 'custody manifest changed'):
+                complete(args)
+        receipt = read_json(self.receipt)
+        self.assertEqual((receipt.get('delivery'), receipt.get('status')), (None, None))
+        self.assertNotIn('workspace_cleanup', receipt)
+        self.assertTrue(self.task.exists())
+
+    def test_remote_retargeted_during_delivery_checks_blocks_with_delivery_unrecorded(self):
+        # Prediction: origin is retargeted, after the first URL check, to another repository whose base holds the accepted
+        # commit, so both ancestry checks pass against it; the URL recheck after them stops completion BLOCKED with delivery
+        # unrecorded and nothing removed. Before: the tree was removed, the deletion-time URL refusal was retained and
+        # delivery was recorded COMPLETE for the receipt's repository, whose base lacks the commit.
+        from unittest.mock import patch
+        self.allocate(); self.accept()
+        fork = self.root / "fork.git"
+        self.run_cmd(["git", "clone", "--bare", "--quiet", str(self.bare), str(fork)])
+        self.g("push", str(fork), self.sha + ":refs/heads/main", work=self.task)
+        bare = ["git", "--git-dir", str(self.bare)]
+        base = self.run_cmd([*bare, "rev-parse", "refs/heads/main"]).stdout.strip()
+        real, retargeted = repo_policy, []
+        def retarget(receipt, **kwargs):
+            if not retargeted:
+                self.g("remote", "set-url", "origin", str(fork))
+                retargeted.append(str(fork))
+            return real(receipt, **kwargs)
+        args = argparse.Namespace(receipt=str(self.receipt), acceptance=str(self.acceptance), mode=None, local_only=False, writers_stopped=True)
+        with patch.dict(os.environ, self.env), patch.dict(complete.__globals__, repo_policy=retarget):
+            with self.assertRaisesRegex(CompletionError, "remote must unambiguously identify one GitHub repository"):
+                complete(args)
+        self.assertEqual(retargeted, [str(fork)])
+        receipt = read_json(self.receipt)
+        self.assertEqual((receipt.get("delivery"), receipt.get("status")), (None, None))
+        self.assertNotIn("workspace_cleanup", receipt)
+        self.assertTrue(self.task.exists())
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+        self.assertEqual(self.g("rev-parse", receipt["recovery_ref"]), self.sha)
+        self.assertEqual(self.run_cmd([*bare, "rev-parse", "refs/heads/main"]).stdout.strip(), base)
+        self.assertEqual(self.run_cmd([*bare, "for-each-ref", "refs/heads/task/"]).stdout, "")
 
     def test_unchanged_foreign_remote_head_retains_worktree(self):
         # Prediction: a foreign remote task head refuses completion before worktree removal.
@@ -3416,6 +3597,9 @@ ctypes.CDLL(None).pthread_exit(None)
 
     @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
     def test_nested_repository_or_worktree_retains_tree(self):
+        # Prediction: the first call merges; a nested worktree, then a nested repository, under an ignored path leaves the
+        # merged delivery COMPLETE (CLEANUP_PENDING) naming each, with the tree, the nested work and both task refs kept;
+        # once both are gone the printed resume removes everything. Before: BLOCKED, delivery unrecorded.
         self.allocate(); self.accept()
         _, r = self.cli("allocate", "--repo", self.work, "--task", "inner", "--branch", "task/inner", "--repository", "test/project",
                         "--base", "main", "--worktree", self.task / "ignored" / "inner", success=False)
@@ -3425,17 +3609,25 @@ ctypes.CDLL(None).pthread_exit(None)
         (nested / "product").write_text("unsaved nested work\n", encoding="utf-8")
         clone = self.task / "ignored" / "clone"
         self.run_cmd(["git", "init", "--initial-branch=main", str(clone)])
-        for remove in (lambda: self.g("worktree", "remove", "--force", str(nested)), lambda: shutil.rmtree(clone)):
-            _, r = self.complete("--mode", "auto", "--writers-stopped", success=False)
-            self.assertIn("nested repository or worktree", json.loads(r.stdout)["reason"])
+        for name, remove in (("ignored/nested/", lambda: self.g("worktree", "remove", "--force", str(nested))),
+                             ("ignored/clone/", lambda: shutil.rmtree(clone))):
+            result, _ = self.complete("--mode", "auto", "--writers-stopped")
+            self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+            self.assertIn("nested repository or worktree inside the task tree: ", result["workspace_cleanup"]["reason"])
+            self.assertIn(name, result["workspace_cleanup"]["reason"])
+            self.assertEqual(read_json(self.receipt)["delivery"], "COMPLETE")
             self.assertTrue(self.task.exists())
-            self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
+            self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+            self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
             if nested.exists():
                 self.assertEqual((nested / "product").read_text(encoding="utf-8"), "unsaved nested work\n")
             remove()
-        result, _ = self.complete("--mode", "auto", "--writers-stopped")
-        self.assertEqual(result["status"], "COMPLETE")
+        result, _ = self.cli(*shlex.split(result["resume"])[2:])
+        self.assertEqual((result["status"], result["workspace_cleanup"]), ("COMPLETE", None))
         self.assertFalse(self.task.exists())
+        self.assertEqual(self.g("branch", "--list", "task/fixture"), "")
+        self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
+        self.assertEqual(read_json(self.data)["merges"], 1)
 
     @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
     def test_default_mode_merges_when_possible_and_cleans(self):
@@ -3577,6 +3769,44 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
 
+    def test_reconcile_checks_delivery_evidence_before_cleanup(self):
+        # Prediction: a merged standalone receipt whose recovery ref moved gives a RETAINED reconcile row naming it, with
+        # the tree and both task refs kept. Fails if reconcile's standalone cleanup skips verify_delivery.
+        self.allocate(); self.accept()
+        self.complete("--mode", "pr", "--writers-stopped")
+        self.merge_pr()
+        receipt, task = self.receipt, self.task
+        saved = read_json(receipt)
+        self.g("update-ref", saved["recovery_ref"], saved["baseline"])
+        result = self.allocate("next")
+        self.assertEqual([(row["receipt"], row["status"]) for row in result["reconciled"]], [(str(receipt), "RETAINED")])
+        self.assertIn("recovery reachability changed", result["reconciled"][0]["reason"])
+        self.assertTrue(task.exists())
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+        self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
+
+    def test_reconcile_replaces_a_retained_reason_with_its_latest_refusal(self):
+        # Prediction: complete retains a merged delivery for a nested repository; once that is gone and the remote task
+        # branch has moved, the next allocation's reconcile removes the tree, keeps the task ref and replaces the receipt's
+        # reason with the remote-branch refusal. Before: the receipt still named the nested repository.
+        self.allocate(); self.accept()
+        clone = self.task / "ignored" / "clone"
+        self.run_cmd(["git", "init", "--initial-branch=main", str(clone)])
+        result, _ = self.complete("--mode", "auto", "--writers-stopped")
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("ignored/clone/", result["workspace_cleanup"]["reason"])
+        shutil.rmtree(clone)
+        self.g("commit", "--allow-empty", "-m", "foreign commit")
+        self.g("push", "origin", "+" + self.g("rev-parse", "HEAD") + ":refs/heads/task/fixture")
+        receipt, task = self.receipt, self.task
+        [row] = self.allocate("next")["reconciled"]
+        self.assertEqual((row["receipt"], row["status"]), (str(receipt), "RETAINED"))
+        self.assertIn("remote branch changed after merge; retain ref", row["reason"])
+        self.assertFalse(task.exists())
+        saved = read_json(receipt)["workspace_cleanup"]
+        self.assertEqual((saved["status"], saved["reason"]), ("RETAINED", row["reason"]))
+        self.assertEqual(self.g("rev-parse", "task/fixture"), self.sha)
+
     def test_reconcile_skips_open_and_unaccepted_and_retains_in_use_tree(self):
         self.allocate(); self.accept()
         self.complete("--mode", "pr", "--writers-stopped")
@@ -3741,16 +3971,17 @@ ctypes.CDLL(None).pthread_exit(None)
         other.write_bytes(b"owner data")
         link = self.task / ".devlyn/link"
         link.symlink_to(other)
-        result, _ = self.complete(success=False)
-        self.assertIn("path escapes custody", result["reason"])
+        result, _ = self.complete()
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("path escapes custody", result["workspace_cleanup"]["reason"])
         self.assertTrue(self.task.exists())
         self.assertTrue(link.is_symlink())
         self.assertEqual(other.read_bytes(), b"owner data")
         link.unlink()
         if hasattr(os, "mkfifo"):
             os.mkfifo(link)
-            result, _ = self.complete(success=False)
-            self.assertIn("regular file", result["reason"])
+            result, _ = self.complete()
+            self.assertIn("regular file", result["workspace_cleanup"]["reason"])
             self.assertTrue(self.task.exists())
             link.unlink()
         saved = self.receipt.parent / "records/.devlyn"
@@ -3817,8 +4048,9 @@ ctypes.CDLL(None).pthread_exit(None)
         extra = generation / ".devlyn/unexpected"
         extra.write_bytes(b"keep this copy\n")
         mismatch = records_manifest(generation)
-        result, _ = self.complete(success=False)
-        self.assertIn(generation.name, result["reason"])
+        result, _ = self.complete()
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn(generation.name, result["workspace_cleanup"]["reason"])
         self.assertTrue(self.task.exists())
         self.assertEqual(records_manifest(generation), mismatch)
         self.assertEqual(records_manifest(saved), original)
@@ -3845,8 +4077,9 @@ ctypes.CDLL(None).pthread_exit(None)
                 (work / ".devlyn/storage-cleanup.json").write_bytes(b"{}\n")
         args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=False)
         with patch.dict(os.environ, self.env), patch.dict(cleanup.__globals__, {"removable": changed}):
-            with self.assertRaisesRegex(CompletionError, "changed after it was copied; stop its writer and resume"):
-                complete(args)
+            result = complete(args)
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("changed after it was copied; stop its writer and resume", result["workspace_cleanup"]["reason"])
         self.assertTrue(self.task.exists())
         self.assertEqual(records_manifest(saved), original)
         final = records_manifest(self.task)
@@ -3868,8 +4101,9 @@ ctypes.CDLL(None).pthread_exit(None)
             return result
         args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=False)
         with patch.dict(os.environ, self.env), patch.object(shutil, "copytree", changed):
-            with self.assertRaisesRegex(CompletionError, "changed while it was copied; stop its writer and resume"):
-                complete(args)
+            result = complete(args)
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("changed while it was copied; stop its writer and resume", result["workspace_cleanup"]["reason"])
         self.assertTrue(self.task.exists())
         self.assertFalse((self.receipt.parent / "records").exists())
         self.assertEqual(list(self.receipt.parent.glob(".records-*")), [])
@@ -3877,8 +4111,8 @@ ctypes.CDLL(None).pthread_exit(None)
     def test_linked_custody_and_interrupted_removal(self):
         self.allocate(); self.accept()
         self.configure(interrupt_remove=True)
-        result, r = self.complete("--writers-stopped", "--mode", "auto", success=False)
-        self.assertNotEqual(r.returncode, 0)
+        result, _ = self.complete("--writers-stopped", "--mode", "auto")
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
         self.assertFalse(self.task.exists())
         saved = json.loads(self.receipt.read_text(encoding="utf-8"))
         self.assertNotIn("cleanup_started", saved)
@@ -3923,15 +4157,24 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual((d["pushs"], d["creates"], d["merges"]), (1, 1, 1))
 
     def test_retains_dirty_locked_and_active_tree(self):
+        # Prediction: the first call merges; each refused removal keeps the tree and task ref and reports CLEANUP_PENDING
+        # with delivery COMPLETE, while a caller inside the tree is refused (BLOCKED) before anything. Before: all BLOCKED.
         self.allocate(); self.accept()
+        reasons = {"no-yield": "resume with --writers-stopped", "dirty": "dirty/untracked workspace",
+                   "untracked": "dirty/untracked workspace", "locked": "detached or locked"}
         for case in ("no-yield", "dirty", "untracked", "locked", "cwd"):
             path = self.task / ("product" if case == "dirty" else "unknown")
             if case in {"dirty", "untracked"}:
                 path.parent.mkdir(exist_ok=True); path.write_text("do not delete", encoding="utf-8")
             if case == "locked": self.g("worktree", "lock", str(self.task))
             with self.subTest(case=case):
-                _, r = self.complete("--mode", "auto", *([] if case == "no-yield" else ["--writers-stopped"]), cwd=self.task if case == "cwd" else None, success=False)
-                self.assertNotEqual(r.returncode, 0)
+                result, r = self.complete("--mode", "auto", *([] if case == "no-yield" else ["--writers-stopped"]), cwd=self.task if case == "cwd" else None, success=False)
+                if case == "cwd":
+                    self.assertEqual((r.returncode, result["status"]), (1, "BLOCKED"))
+                    self.assertIn("caller cwd is inside", result["reason"])
+                else:
+                    self.assertEqual((r.returncode, result["status"], result["delivery_status"]), (0, "CLEANUP_PENDING", "COMPLETE"))
+                    self.assertIn(reasons[case], result["workspace_cleanup"]["reason"])
                 self.assertTrue(self.task.exists())
                 self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
             if case == "untracked": path.unlink()
@@ -4004,10 +4247,11 @@ ctypes.CDLL(None).pthread_exit(None)
             self.assertTrue(self.task.exists())
         finally:
             child.terminate(); child.wait(timeout=5)
-        # A foreign branch in the same registered tree never inherits ownership.
+        # A foreign branch in the same registered tree never inherits ownership; the merged delivery stays COMPLETE.
         self.g("switch", "-c", "foreign", work=self.task)
-        _, r = self.complete("--writers-stopped", success=False)
-        self.assertNotEqual(r.returncode, 0)
+        result, _ = self.complete("--writers-stopped")
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("foreign worktree branch", result["workspace_cleanup"]["reason"])
         self.assertTrue(self.task.exists())
         self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
 
@@ -4015,8 +4259,8 @@ ctypes.CDLL(None).pthread_exit(None)
         self.allocate(); self.accept()
         race = self.g("rev-parse", "main")
         self.configure(remote_delete_race=True, race_sha=race)
-        _, r = self.complete("--writers-stopped", "--mode", "auto", success=False)
-        self.assertNotEqual(r.returncode, 0)
+        result, _ = self.complete("--writers-stopped", "--mode", "auto")
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], race)
         self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
 
@@ -4032,16 +4276,37 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual(d["prs"][0]["state"], "MERGED")
         self.assertIsNone(d["prs"][0]["autoMergeRequest"])
 
-    def test_auto_disallowed_blocked_refuses_without_merge(self):
+    def test_auto_disallowed_blocked_waits_and_its_resume_merges(self):
+        # Prediction (B3): with auto-merge off, required checks or reviews not passing yet (BLOCKED) make no merge call
+        # and report PENDING with merge_waits; once the PR is CLEAN the printed resume merges it directly and cleans.
+        # Before: PR with merge_refused "not mergeable: BLOCKED", a refusal left for a person.
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=False, merge_state="BLOCKED")
+        result, _ = self.complete("--mode", "auto", "--writers-stopped")
+        self.assertEqual((result["status"], result.get("merge_waits")), ("PENDING", "BLOCKED"))
+        self.assertNotIn("merge_refused", result)
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual((d.get("merge_calls", []), d["prs"][0]["state"]), ([], "OPEN"))
+        self.assertEqual(read_json(self.receipt)["delivery"], "PENDING")
+        self.configure(merge_state="CLEAN")
+        result, _ = self.cli(*shlex.split(result["resume"])[2:])
+        self.assertEqual(result["status"], "COMPLETE")
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d["merge_calls"], [["pr", "merge", "1", "--merge", "--match-head-commit", self.sha,
+                                            "--repo", "github.com/test/project"]])
+        self.assertEqual(d["prs"][0]["state"], "MERGED")
+        self.assertFalse(self.task.exists())
+
+    def test_auto_disallowed_unmergeable_states_refuse_without_merge(self):
         self.allocate(); self.accept()
-        for state in ("BLOCKED", "BEHIND", "DIRTY", "DRAFT", "NEW_STATE"):
+        for state in ("BEHIND", "DIRTY", "DRAFT", "NEW_STATE"):
             with self.subTest(state=state):
                 self.configure(auto_allowed=False, merge_state=state)
                 result, _ = self.complete("--mode", "auto")
                 self.assertEqual(result["status"], "PR")
                 self.assertIn("not mergeable: " + state, result["merge_refused"])
         d = json.loads(self.data.read_text(encoding="utf-8"))
-        self.assertEqual(d["merge_state_views"], ["BLOCKED", "BEHIND", "DIRTY", "DRAFT", "NEW_STATE"])
+        self.assertEqual(d["merge_state_views"], ["BEHIND", "DIRTY", "DRAFT", "NEW_STATE"])
         self.assertEqual(d.get("merge_calls", []), [])
         self.assertEqual(d["prs"][0]["state"], "OPEN")
         self.assertIsNone(d["prs"][0]["autoMergeRequest"])
@@ -4065,12 +4330,12 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual(result["status"], "PENDING")
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8"))["auto_setting_reads"], 1)
 
-    def test_auto_disallowed_unknown_bound_refuses_without_merge(self):
+    def test_auto_disallowed_unknown_bound_waits_without_merge(self):
         self.allocate(); self.accept()
         self.configure(auto_allowed=False, merge_state="UNKNOWN")
         result, _ = self.complete("--mode", "auto")
-        self.assertEqual(result["status"], "PR")
-        self.assertIn("not mergeable: UNKNOWN", result["merge_refused"])
+        self.assertEqual((result["status"], result.get("merge_waits")), ("PENDING", "UNKNOWN"))
+        self.assertNotIn("merge_refused", result)
         d = json.loads(self.data.read_text(encoding="utf-8"))
         self.assertEqual(d["merge_state_views"], ["UNKNOWN"] * 10)
         self.assertEqual(d.get("merge_calls", []), [])
@@ -4154,8 +4419,8 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertNotIn("merge_refused", result)
         self.configure(merge_allowed=True, auto_allowed=False, pending=True)
         result, _ = self.complete("--mode", "auto")
-        self.assertEqual(result["status"], "PR")
-        self.assertIn("not mergeable: BLOCKED", result["merge_refused"])
+        self.assertEqual((result["status"], result.get("merge_waits")), ("PENDING", "BLOCKED"))
+        self.assertNotIn("merge_refused", result)
         self.assertTrue(self.task.exists())
         # Local-only cannot rewrite the delivery of a pushed PR; a local allocation keeps it (test_local_chain_*).
         result, _ = self.complete("--no-push", success=False)
@@ -4214,8 +4479,8 @@ ctypes.CDLL(None).pthread_exit(None)
         user_file.write_text("retained user data", encoding="utf-8")
         before = self.anchor_state()
         self.configure(interrupt_delete=True)
-        _, r = self.complete(acceptance=False, success=False)
-        self.assertNotEqual(r.returncode, 0)
+        result, _ = self.complete(acceptance=False)
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
         self.assertEqual(self.anchor_state(), before)
         other = self.root / "advance"
         self.run_cmd(["git", "clone", str(self.bare), str(other)])