devlyn-cli 4.0.1 → 4.2.0

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

@@ -2,7 +2,7 @@
 """Outer-owner delivery and recoverable cleanup (task-completion spec, R1–7).
 
 No phase/state writer, staging, scheduler, or implicit adoption. See
-devlyn-resolve/references/task-completion.md for the owner acceptance contract.
+_shared/task-completion.md for the owner acceptance contract.
 """
 from __future__ import annotations
 
@@ -28,6 +28,14 @@ class CompletionError(Exception):
     pass
 
 
+class WritersUnobservable(CompletionError):
+    """Writer cessation cannot be observed here, so owned resources are retained, never deleted."""
+
+
+class WriterActive(CompletionError):
+    """An observed process still uses the owned files: wait for it or stop it, then resume."""
+
+
 def require(condition, message):
     if not condition:
         raise CompletionError(message)
@@ -50,7 +58,7 @@ def shared(name):
 
 def read_json(path):
     require(stat.S_ISREG(path.lstat().st_mode), f"JSON must be a nonsymlink regular file: {path}")
-    return shared("archive_run")["loads_strict_json"](path.read_text(encoding="utf-8"))
+    return shared("expected-contract")["loads_strict_json"](path.read_text(encoding="utf-8"))
 
 
 def atomic_json(path, value):
@@ -180,19 +188,24 @@ def allocate(args):
     common = Path(git(work, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve()
     require(args.task.strip(), "task identity is required")
     git(work, "check-ref-format", "refs/heads/" + args.branch)
-    git(work, "check-ref-format", "refs/heads/" + args.base)
+    if args.base is not None:
+        git(work, "check-ref-format", "refs/heads/" + args.base)
     require(args.branch != args.base and args.branch not in {"main", "master"}, "cannot own a base/default branch")
     require(re.fullmatch(r"[A-Za-z0-9_.-]+", args.remote), "unsafe remote name")
     receipt = {"task": args.task, "repository": args.repository, "remote": args.remote,
                "base": args.base, "branch": args.branch, "common_gitdir": str(common),
                "anchor": str(work), "linked": True, "allocation": "allocating"}
-    policy(receipt, None)
-    receipt["remote_url"] = remote_url(receipt)
-    require("\n" not in receipt["remote_url"]["push"] and receipt["remote_url"]["push"] == receipt["remote_url"]["fetch"], "split/multiple remote URLs are unsupported")
     require(not ref_sha(receipt, "refs/heads/"+args.branch), "existing branch cannot be adopted")
-    receipt["baseline"] = remote_base(receipt)
-    target = Path(args.worktree).absolute()
-    require(target == target.resolve(), "worktree path must not traverse symlinks")
+    local = local_baseline(receipt, args)
+    if local:
+        receipt["local_only"] = True  # Local work needs no remote: nothing is fetched or pushed.
+    else:
+        require(args.repository and args.base, "a remote allocation needs --repository <owner/repo> and --base <branch>; allocate local work with --local-base or --from-receipt")
+        policy(receipt, None)
+        receipt["remote_url"] = remote_url(receipt)
+        require("\n" not in receipt["remote_url"]["push"] and receipt["remote_url"]["push"] == receipt["remote_url"]["fetch"], "split/multiple remote URLs are unsupported")
+    receipt["baseline"] = local or exact_commit(receipt, args.start, "--start") or remote_base(receipt)
+    target = Path(args.worktree).resolve()  # A relative, `..` or symlinked (macOS /tmp) path names its real location.
     require(not target.exists() and all(not target.is_relative_to(p) and not p.is_relative_to(target) for p in map(Path, registrations(receipt))), "linked worktree must be an absent path disjoint from every registered worktree")
     receipt["worktree"] = str(target)
     key = hashlib.sha256(args.branch.encode()).hexdigest()[:24]
@@ -213,78 +226,49 @@ def allocate(args):
     receipt["allocation"] = "owned"
     atomic_json(path, receipt)
     return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target), "scratch": str(scratch),
-            "reconciled": reconcile(common, path, work)}
-
-
-def pipeline_acceptance(work, acceptance, files, directory):
-    run_id = acceptance["run_id"]
-    require(re.fullmatch(r"[A-Za-z0-9_.-]+", run_id) and run_id not in {".", ".."}, "invalid intended run id")
-    archive = safe_path(work, ".devlyn/runs/" + run_id)
-    state_file = archive / "pipeline.state.json"
-    classifier = shared("terminal-claim-check")
-    classification, state = classifier["classify_state_bytes"](work, state_file, state_file.read_bytes(), archived=True)
-    require(classification.status == "CLEAN" and state["run_id"] == run_id, "intended archive is not terminal CLEAN")
-    require(state.get("mode") in {"spec", "free-form"}, "only normal archived runs may publish")
-    require((state.get("source") or {}).get("type") in {"spec", "generated"}, "normal archive must bind its source contract")
-    phases = state["phases"]
-    success = {"PASS", "PASS_WITH_ISSUES"}
-    verify = phases.get("verify") or {}
-    final = phases.get("final_report") or {}
-    require(verify.get("verdict") in success and final.get("verdict") == verify["verdict"], "archive did not finish successfully")
-    require(not any(str((phase or {}).get("verdict", "")).startswith("BLOCKED") for phase in phases.values()), "blocked phase takes terminal precedence")
-    for name in ("plan", "implement", "cleanup", "verify", "final_report", "build_gate"):
-        if name == "build_gate" and "build-gate" in (state.get("bypasses") or []):
-            continue
-        phase = phases.get(name) or {}
-        require(phase.get("completed_at") and phase.get("verdict") in success, f"required {name} evidence is incomplete")
-    require(phases["cleanup"].get("post_sha") == acceptance["source_sha"], "accepted source must equal cleanup.post_sha")
-    report_digest = shared("state-phase-write")["final_report_digest"](state, archive, str(archive / "final-report.md"))
-    require(final.get("output_sha256") == report_digest and final.get("artifacts", {}).get("log_file") == ".devlyn/final-report.md", "final report binding mismatch")
-    finish = read_json(archive / "finish-gate.summary.json")
-    require(finish.get("mode") == state["mode"] and finish.get("exit") == 0 and finish.get("offenders") == 0 and not finish.get("skipped") and not finish.get("malformed"), "finish gate was not clean")
-    require(read_json(archive / "verify-merge.summary.json").get("verdict") == verify["verdict"], "VERIFY summary disagrees with terminal result")
-    # Existing evidence validators expect the pre-archive .devlyn layout. Rebuild
-    # it in a temporary directory; never move or mutate the original archive.
-    with tempfile.TemporaryDirectory(prefix="validate-", dir=directory) as tmp:
-        reconstructed = Path(tmp)
-        devlyn = reconstructed / ".devlyn"
-        devlyn.mkdir()
-        prefix = f".devlyn/runs/{run_id}/"
-        for rel in files:
-            if rel.startswith(prefix):
-                dest = safe_path(devlyn, rel[len(prefix):])
-                dest.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copyfile(safe_path(work, rel), dest)
-        archive_module = shared("archive_run")
-        try:
-            for validator in ("dynamic_evidence_artifacts", "dynamic_invocation_artifacts", "dynamic_judge_role_artifacts"):
-                archive_module[validator](devlyn, state)
-        except archive_module["ArchiveError"] as exc:
-            raise CompletionError(str(exc)) from exc
-        evidence_module = shared("process-evidence")
-        for carrier in state.get("process_evidence") or []:
-            if carrier["round"] == (phases.get(carrier["phase"]) or {}).get("round"):
-                require(evidence_module["bound_carrier_outcome"](reconstructed, carrier)["verdict"] == "PASS", "required process evidence failed")
-        source = state.get("source") or {}
-        if source.get("spec_path"):
-            expected = Path(source["spec_path"]).with_name("spec.expected.json")
-            original = safe_path(work, str(expected))
-            if original.exists():
-                dest = safe_path(reconstructed, str(expected))
-                dest.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copyfile(original, dest)
-                for phase in ("implement", "build_gate", "verify"):
-                    obligations = evidence_module["declared_obligations"](reconstructed, state, phase)
-                    if obligations:
-                        carriers = [c for c in state.get("process_evidence") or [] if c.get("phase") == phase and c.get("round") == (phases.get(phase) or {}).get("round")]
-                        require(len(carriers) == 1, f"missing/ambiguous current {phase} process evidence")
-                        carrier = carriers[0]
-                        evidence_module["validate_manifest"](reconstructed, carrier["manifest"]["path"], run_id, phase, carrier["round"], obligations)
-        if evidence_module["mechanical_evidence_required"](reconstructed, state):
-            require((devlyn / "spec-verify.results.json").is_file(), "required MECHANICAL results are missing")
-        carrier = shared("verify-merge-findings")["mechanical_evidence_carrier"](devlyn)
-        if carrier:
-            require(evidence_module["bound_carrier_outcome"](reconstructed, carrier)["verdict"] == "PASS", "MECHANICAL checks did not pass")
+            "reconciled": [] if local else reconcile(common, path, work)}
+
+
+def exact_commit(receipt, value, flag):
+    require(value is None or re.fullmatch(r"[0-9a-f]{40,64}", value) and ref_sha(receipt, value+"^{commit}") == value,
+            f"{flag} must name an exact local commit")
+    return value
+
+
+def local_baseline(receipt, args):
+    """A local loop starts from its recorded base commit or a receipt-bound accepted predecessor, never a fetch."""
+    require(sum(map(bool, (args.local_base, args.from_receipt, args.start))) <= 1, "use one of --local-base, --from-receipt or --start")
+    if args.from_receipt:
+        with locked_receipt(Path(args.from_receipt).absolute(), blocking=False) as predecessor:
+            require(predecessor["common_gitdir"] == receipt["common_gitdir"], "predecessor receipt belongs to another repository")
+            require(predecessor.get("acceptance") and predecessor.get("product") != "FAILED", "predecessor has no accepted result")
+            require(ref_sha(predecessor, predecessor["recovery_ref"]) == predecessor["publish_sha"], "predecessor recovery ref changed")
+            gref(predecessor, "merge-base", "--is-ancestor", predecessor["source_sha"], predecessor["publish_sha"])
+            receipt["allocated_from"] = {"receipt": predecessor["id"], "source_sha": predecessor["source_sha"]}
+            return predecessor["source_sha"]
+    return exact_commit(receipt, args.local_base, "--local-base")
+
+
+def refuse_retired_pipeline(receipt, path, supplied, local, flags):
+    """Refuse an unbound acceptance of an archived resolve run before anything is written: binding its archive
+    needed the retired helpers. An unreadable acceptance is not classified here; binding reports it as before."""
+    if receipt.get("acceptance") or not supplied:
+        return
+    acceptance_path = Path(supplied).absolute()
+    try:
+        acceptance = read_json(acceptance_path)
+    except (CompletionError, OSError, ValueError):
+        return
+    if not isinstance(acceptance, dict) or acceptance.get("kind") != "pipeline":
+        return
+    command = shlex.join(["python3", "package/config/skills/_shared/task-complete.py", "complete", "--receipt", str(path),
+                          "--acceptance", str(acceptance_path), *(["--local-only"] if local else []), *flags])
+    raise CompletionError(
+        "pipeline acceptance (an archived resolve run) was retired after devlyn-cli 4.1.0; nothing was changed. Finish the run "
+        f"with that release: run `npm pack devlyn-cli@4.1.0`, extract the tarball, then run `{command}` there. "
+        + ("That local-only completion ends as LOCAL_ONLY without binding the acceptance, as every 4.1.0 local-only completion did."
+           if local else "That completion binds the pipeline acceptance before publishing; delivery of a receipt it binds then "
+           "resumes with this helper."))
 
 
 def bind_acceptance(receipt, path, supplied):
@@ -295,7 +279,8 @@ def bind_acceptance(receipt, path, supplied):
         verify_files(path.parent / "custody", receipt["files"])
         return
     require(supplied, "first completion requires explicit root acceptance")
-    acceptance_path = Path(supplied).absolute()
+    named = Path(supplied).absolute()
+    acceptance_path = named.parent.resolve() / named.name  # Its directory's real path, as allocate names the worktree.
     require(acceptance_path.is_relative_to(work), "acceptance must be a regular file in its task checkout")
     safe_path(work, str(acceptance_path.relative_to(work)))
     acceptance = read_json(acceptance_path)
@@ -304,14 +289,10 @@ def bind_acceptance(receipt, path, supplied):
     require(isinstance(sha, str) and re.fullmatch(r"[0-9a-f]{40,64}", sha), "acceptance must name an exact commit")
     require(gref(receipt, "rev-parse", sha+"^{commit}") == sha, "source is not a commit")
     gref(receipt, "merge-base", "--is-ancestor", receipt["baseline"], sha)
-    publish = sha
-    queue = acceptance.get("queue")
-    if queue:
-        publish = queue["commit"]
-        safe_path(work, queue["file"])
-        require(gref(receipt, "rev-list", "--parents", "-n", "1", publish).split() == [publish, sha], "queue commit must be directly atop verified source with one parent")
-        require(gref(receipt, "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", publish).strip("\0") == queue["file"], "queue commit must change exactly the declared queue file")
-    require(ref_sha(receipt, "refs/heads/"+receipt["branch"]) == publish and git(work, "rev-parse", "HEAD") == publish, "unverified source delta or changed task ref")
+    # A failed loop result is never published, so its checkout stays as the executor left it (as in attach).
+    failed = acceptance.get("kind") == "loop" and acceptance.get("verdict") == "FAILED"
+    require(ref_sha(receipt, "refs/heads/"+receipt["branch"]) == sha and (failed or git(work, "rev-parse", "HEAD") == sha),
+            "unverified source delta or changed task ref")
     paths = [str(acceptance_path.relative_to(work))]
     kind = acceptance.get("kind")
     if kind == "direct":
@@ -320,42 +301,66 @@ def bind_acceptance(receipt, path, supplied):
         for check in checks:
             require(isinstance(check.get("command"), str) and check["command"].strip(), "direct check must name its command")
             paths.append(check["evidence"])
-    elif kind == "pipeline":
-        paths.append(".devlyn/runs/" + acceptance["run_id"])
-        state = read_json(safe_path(work, paths[-1]) / "pipeline.state.json")
-        source = state.get("source") or {}
-        for key in ("spec_path", "criteria_path"):
-            if source.get(key):
-                if key == "criteria_path" and source.get("type") == "generated":
-                    require(source[key] == ".devlyn/criteria.generated.md", "generated criteria path is not canonical")
-                    relative = f".devlyn/runs/{acceptance['run_id']}/criteria.generated.md"
-                else:
-                    relative = source[key]
-                paths.append(relative)
-                source_file = safe_path(work, relative)
-                if relative == source[key]:
-                    committed = subprocess.run(["git", "--git-dir", receipt["common_gitdir"], "show", sha+":"+relative], capture_output=True)
-                    require(committed.returncode == 0 and committed.stdout == source_file.read_bytes(), "source contract changed since accepted commit")
-                bound_digest = source.get(key.replace("_path", "_sha256"))
-                require(file_record(source_file)["sha256"] == bound_digest, "source contract differs from run binding")
-                source_path = Path(source[key])
-                expected = str(source_path.with_name("spec.expected.json") if key == "spec_path" else source_path.with_suffix(".expected.json"))
-                if safe_path(work, expected).exists():
-                    paths.append(expected)
+    elif kind == "loop":
+        require(acceptance.get("verdict") in {"ACCEPTED", "FAILED"}, "loop result verdict must be ACCEPTED or FAILED")
+        evidence = acceptance.get("evidence")
+        require(isinstance(evidence, list) and all(isinstance(p, str) for p in evidence), "loop result must list its evidence files")
+        paths.extend(evidence)
     else:
-        raise CompletionError("acceptance kind must be direct|pipeline")
+        raise CompletionError("acceptance kind must be direct|loop")
     files = snapshot_files(work, paths)
-    if kind == "pipeline":
-        pipeline_acceptance(work, acceptance, files, path.parent)
     custody(work, path.parent / "custody", files)
     recovery = ref_sha(receipt, receipt["recovery_ref"])
-    require(recovery in {None, publish}, "recovery ref changed")
+    require(recovery in {None, sha}, "recovery ref changed")
     if recovery is None:
-        gref(receipt, "update-ref", receipt["recovery_ref"], publish, "0"*len(publish))
-    receipt.update(acceptance=acceptance, acceptance_digest=file_record(acceptance_path)["sha256"], source_sha=sha, publish_sha=publish, files=files)
+        gref(receipt, "update-ref", receipt["recovery_ref"], sha, "0"*len(sha))
+    receipt.update(acceptance=acceptance, acceptance_digest=file_record(acceptance_path)["sha256"], source_sha=sha, publish_sha=sha, files=files)
+    if acceptance.get("verdict") == "FAILED":
+        # Failed results keep custody and a recovery ref, but never become a frontier or a publishable product.
+        receipt["product"] = "FAILED"
     atomic_json(path, receipt)
 
 
+def queue_commit(receipt, work, queue, source):
+    safe_path(work, queue["file"])
+    commit = queue["commit"]
+    require(gref(receipt, "rev-list", "--parents", "-n", "1", commit).split() == [commit, source], "queue commit must be directly atop verified source with one parent")
+    require(gref(receipt, "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", commit).strip("\0") == queue["file"], "queue commit must change exactly the declared queue file")
+
+
+def accept(args):
+    """Bind a result's source and evidence custody before terminal metadata or any delivery decision."""
+    path = Path(args.receipt).absolute()
+    with locked_receipt(path) as receipt:
+        refuse_retired_pipeline(receipt, path, args.acceptance, receipt.get("local_only"), [])
+        bind_acceptance(receipt, path, args.acceptance)
+        return {"status": "FAILED" if receipt.get("product") == "FAILED" else "ACCEPTED", "receipt": str(path),
+                "source_sha": receipt["source_sha"], "recovery_ref": receipt["recovery_ref"]}
+
+
+def attach(args):
+    """Attach the queue-only terminal commit to an already bound result; the recovery ref moves with it."""
+    path = Path(args.receipt).absolute()
+    queue = {"commit": args.commit, "file": args.file}
+    with locked_receipt(path) as receipt:
+        require(receipt.get("acceptance"), "bind the result before attaching its terminal commit")
+        if receipt.get("queue") != queue:
+            require(not receipt.get("queue"), "a different terminal commit is already attached")
+            work = Path(receipt["worktree"])
+            queue_commit(receipt, work, queue, receipt["source_sha"])
+            # A failed result is never published, so its checkout stays as left; a publishable one must be checked out.
+            require(ref_sha(receipt, "refs/heads/"+receipt["branch"]) == args.commit
+                    and (receipt.get("product") == "FAILED" or git(work, "rev-parse", "HEAD") == args.commit),
+                    "task ref and HEAD must be the terminal commit")
+            recovery = ref_sha(receipt, receipt["recovery_ref"])
+            require(recovery in {receipt["source_sha"], args.commit}, "recovery ref changed")
+            if recovery != args.commit:
+                gref(receipt, "update-ref", receipt["recovery_ref"], args.commit, receipt["source_sha"])
+            receipt.update(queue=queue, publish_sha=args.commit)
+            atomic_json(path, receipt)
+        return {"status": "ATTACHED", "receipt": str(path), "source_sha": receipt["source_sha"], "terminal_sha": args.commit}
+
+
 PR_FIELDS = "number,url,headRefName,baseRefName,headRefOid,headRepository,headRepositoryOwner,isCrossRepository,state,mergedAt,mergeCommit,autoMergeRequest"
 
 
@@ -428,13 +433,14 @@ def stopped_writers(work):
     # other currently open files/cwds, not future writers or a universal lease.
     if sys.platform == "darwin":
         result = subprocess.run(["lsof", "-Fpn", "+D", str(work)], capture_output=True, text=True, encoding="utf-8")
-        require(result.returncode in {0, 1} and not result.stderr.strip(), "writer observation unavailable; retain tree and inspect writers")
+        if result.returncode not in {0, 1} or result.stderr.strip():
+            raise WritersUnobservable("writer observation unavailable; retain tree and inspect writers")
         pid = None
         for line in result.stdout.splitlines():
             if line.startswith("p"):
                 pid = int(line[1:])
             elif line.startswith("n") and pid != os.getpid():
-                raise CompletionError(f"active process {pid} uses task files; stop/yield actual writers before resume")
+                raise WriterActive(f"active process {pid} uses task files; stop/yield actual writers before resume")
     elif sys.platform.startswith("linux"):
         for process in Path("/proc").iterdir():
             if not process.name.isdigit() or int(process.name) == os.getpid():
@@ -448,13 +454,14 @@ def stopped_writers(work):
                         if link == process / "cwd":
                             break
                         continue
-                    require(not target.is_absolute() or not target.is_relative_to(work), f"active process {process.name} uses task files; stop/yield it before resume")
+                    if target.is_absolute() and target.is_relative_to(work):
+                        raise WriterActive(f"active process {process.name} uses task files; stop/yield it before resume")
             except FileNotFoundError:
                 continue  # Process exited during observation.
             except PermissionError as exc:
-                raise CompletionError("unknown process access; retain tree until writer cessation can be established") from exc
+                raise WritersUnobservable("unknown process access; retain tree until writer cessation can be established") from exc
     else:
-        raise CompletionError("writer observation unsupported on this platform; retain workspace")
+        raise WritersUnobservable("writer observation unsupported on this platform; retain workspace")
 
 
 def scratch_mounts():
@@ -579,6 +586,7 @@ def cleanup(receipt, path, pr):
     if ref_sha(receipt, branch_ref) is not None:
         require(all(row.get("branch") != branch_ref for row in registrations(receipt).values()), "task branch became checked out; retain ref")
         gref(receipt, "update-ref", "-d", branch_ref, sha)
+    receipt.pop("workspace_cleanup", None)
     receipt["status"] = "COMPLETE"
     atomic_json(path, receipt)
 
@@ -600,6 +608,9 @@ def locked_receipt(path, *, blocking=True):
 
 
 def completion_result(receipt, path, status):
+    if receipt.get("delivery") != status:
+        receipt["delivery"] = status  # Phase-independent checkpoint: the latest delivery outcome.
+        atomic_json(path, receipt)
     released = receipt.get("writers_released", False)
     resume = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)] +
                         (["--writers-stopped"] if released else []))
@@ -615,11 +626,12 @@ def completion_result(receipt, path, status):
                 atomic_json(path, receipt)
             except OSError as record_error:
                 scratch["record_error"] = str(record_error)
-    return {"status": "CLEANUP_PENDING" if status == "COMPLETE" and scratch["status"] == "RETAINED" else status,
+    retained = scratch["status"] == "RETAINED" or "workspace_cleanup" in receipt
+    return {"status": "CLEANUP_PENDING" if status == "COMPLETE" and retained else status,
             "delivery_status": status, "receipt": str(path), "pr": receipt.get("pr_url"), "resume": resume,
             "acceptance": (receipt.get("acceptance") or {}).get("kind"), "product_verdict_unchanged": True,
             "scratch_path": str(path.parent / "scratch") if "scratch_identity" in receipt else None,
-            "scratch_cleanup": scratch}
+            "scratch_cleanup": scratch, "workspace_cleanup": receipt.get("workspace_cleanup")}
 
 
 def reconcile(common, allocated, anchor):
@@ -659,6 +671,9 @@ def reconcile(common, allocated, anchor):
 def complete(args):
     path = Path(args.receipt).absolute()
     with locked_receipt(path) as receipt:
+        local = args.local_only or receipt.get("local_only")
+        refuse_retired_pipeline(receipt, path, args.acceptance, local, [*(["--mode", args.mode] if args.mode and not local else []),
+                                                                       *(["--writers-stopped"] if args.writers_stopped else [])])
         if args.writers_stopped:
             if receipt["linked"]:
                 outside(Path(receipt["worktree"]))
@@ -666,9 +681,18 @@ def complete(args):
             atomic_json(path, receipt)
         def result(status):
             return completion_result(receipt, path, status)
+        if receipt.get("product") == "FAILED":
+            return result("FAILED")
         if args.local_only or receipt.get("local_only"):
+            require(not receipt.get("pushed"), f"{receipt['task']} already has a pushed PR {receipt.get('pr_url') or receipt['branch']}; "
+                    "--local-only cannot rewrite its delivery, resume it without --local-only")
             receipt["local_only"] = True
             atomic_json(path, receipt)
+            if args.acceptance or receipt.get("acceptance"):
+                # Persist acceptance custody before the local-only return.
+                if not receipt.get("acceptance"):
+                    inspect_workspace(dict(receipt, publish_sha=ref_sha(receipt, "refs/heads/"+receipt["branch"])))
+                bind_acceptance(receipt, path, args.acceptance)
             return result("LOCAL_ONLY")
         mode = policy(receipt, args.mode or receipt.get("mode_override"))
         if args.mode:
@@ -737,7 +761,13 @@ def complete(args):
                 return dict(result("PR"), merge_refused=refused) if refused and not pr.get("autoMergeRequest") else result("PENDING")
         receipt["merge"] = pr
         atomic_json(path, receipt)
-        cleanup(receipt, path, pr)
+        try:
+            cleanup(receipt, path, pr)
+        except (WritersUnobservable, WriterActive) as error:
+            # Conservative retention: the merge settles delivery; workspace, task refs and custody stay, reported.
+            receipt["workspace_cleanup"] = {"status": "RETAINED", "reason": str(error), "resume": shlex.join([
+                sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)])}
+            atomic_json(path, receipt)
         return result("COMPLETE")
 
 
@@ -747,10 +777,22 @@ def main():
     actions = parser.add_subparsers(dest="action")
     allocation = actions.add_parser("allocate")
     allocation.add_argument("--repo", default=".")
-    for name in ("task", "branch", "repository", "base"):
+    for name in ("task", "branch"):
         allocation.add_argument("--"+name, required=True)
+    allocation.add_argument("--base")
+    allocation.add_argument("--repository")
     allocation.add_argument("--remote", default="origin")
     allocation.add_argument("--worktree", required=True)
+    allocation.add_argument("--local-base")
+    allocation.add_argument("--from-receipt")
+    allocation.add_argument("--start")
+    binding = actions.add_parser("accept")
+    binding.add_argument("--receipt", required=True)
+    binding.add_argument("--acceptance", required=True)
+    attachment = actions.add_parser("attach")
+    attachment.add_argument("--receipt", required=True)
+    attachment.add_argument("--commit", required=True)
+    attachment.add_argument("--file", default="docs/specs/queue.md")
     completion = actions.add_parser("complete")
     completion.add_argument("--receipt", required=True)
     completion.add_argument("--acceptance")
@@ -764,16 +806,17 @@ def main():
     if args.self_test:
         return self_test()
     if args.action is None:
-        parser.error("allocate, complete or clean-scratch is required")
+        parser.error("allocate, accept, attach, complete or clean-scratch is required")
     try:
-        result = (allocate(args) if args.action == "allocate" else
-                  clean_scratch_command(args) if args.action == "clean-scratch" else complete(args))
+        result = {"allocate": allocate, "accept": accept, "attach": attach,
+                  "clean-scratch": clean_scratch_command, "complete": complete}[args.action](args)
         print(json.dumps(result, sort_keys=True))
         return 0
     except (CompletionError, OSError, ValueError, KeyError, TypeError, IndexError, SystemExit) as exc:
         result = {"status": "BLOCKED", "reason": str(exc)}
-        if args.action in {"complete", "clean-scratch"}:
+        if args.action != "allocate":
             result["receipt"] = str(Path(args.receipt).absolute())
+        if args.action in {"complete", "clean-scratch"}:
             result["resume"] = shlex.join([sys.executable, str(Path(__file__).resolve()), args.action, "--receipt", result["receipt"], *(["--writers-stopped"] if args.writers_stopped else [])])
         print(json.dumps(result, sort_keys=True))
         return 1
@@ -794,6 +837,7 @@ FAKE_GH = r'''#!/usr/bin/env python3
 import json, os, pathlib, subprocess, sys
 p = pathlib.Path(os.environ['FIXTURE_GH'])
 d = json.loads(p.read_text(encoding="utf-8")); a = sys.argv[1:]
+prs = d.setdefault('prs', [])  # PR number n is prs[n-1]; several may be open at once.
 def save(): p.write_text(json.dumps(d), encoding="utf-8")
 def remote(ref):
     r = subprocess.run([os.environ['REAL_GIT'], '--git-dir', d['bare'], 'rev-parse', '--verify', ref], capture_output=True, text=True, encoding="utf-8")
@@ -803,38 +847,44 @@ if a[:2] == ['repo', 'view']:
     print(json.dumps({'nameWithOwner':'test/project', 'url':'https://github.com/test/project', 'defaultBranchRef':{'name':d.get('default_branch','main')}, 'mergeCommitAllowed':d.get('merge_allowed',True)}))
 elif a[:2] == ['pr', 'list']:
     assert '--repo' in a and a[a.index('--repo')+1] == 'github.com/test/project'
-    print(json.dumps([d['pr']] if d.get('pr') else []))
+    print(json.dumps([pr for pr in prs if pr['headRefName'] == a[a.index('--head')+1]]))
 elif a[:2] == ['pr', 'create']:
     d['creates'] = d.get('creates',0)+1
-    assert not d.get('pr'), 'duplicate PR'
     head = a[a.index('--head')+1]; base = a[a.index('--base')+1]
-    d['pr'] = {'number':1,'url':'https://github.com/test/project/pull/1','headRefName':head,'baseRefName':base,'headRefOid':remote('refs/heads/'+head),'headRepository':{'name':'project','owner':{'login':'test'}}, 'headRepositoryOwner':{'login':'test'},'isCrossRepository':False,'state':'OPEN','mergedAt':None,'mergeCommit':None,'autoMergeRequest':None}
+    assert not [pr for pr in prs if pr['headRefName'] == head], 'duplicate PR'
+    url = 'https://github.com/test/project/pull/%d' % (len(prs)+1)
+    prs.append({'number':len(prs)+1,'url':url,'headRefName':head,'baseRefName':base,'headRefOid':remote('refs/heads/'+head),'headRepository':{'name':'project','owner':{'login':'test'}}, 'headRepositoryOwner':{'login':'test'},'isCrossRepository':False,'state':'OPEN','mergedAt':None,'mergeCommit':None,'autoMergeRequest':None})
     save()
-    print(d['pr']['url'])
+    print(url)
     if d.pop('interrupt_create',False): save(); sys.exit(1)
 elif a[:2] == ['pr', 'view']:
-    print(json.dumps(d['pr']))
+    print(json.dumps(prs[int(a[2])-1]))
 elif a[:2] == ['pr', 'merge'] and '--disable-auto' in a:
     d['disables'] = d.get('disables',0)+1
-    d['pr']['autoMergeRequest'] = None
+    prs[int(a[2])-1]['autoMergeRequest'] = None
     save()
 elif a[:2] == ['pr', 'merge']:
     assert '--admin' not in a and '--delete-branch' not in a
     assert '--auto' in a and '--merge' in a and '--match-head-commit' in a
+    pr = prs[int(a[2])-1]
     sha = a[a.index('--match-head-commit')+1]
-    assert sha == remote('refs/heads/'+d['pr']['headRefName'])
+    assert sha == remote('refs/heads/'+pr['headRefName'])
     d['merges'] = d.get('merges',0)+1
     if not d.get('auto_allowed',True) and d.get('pending'):
         save(); print('repository disallows auto merge',file=sys.stderr); sys.exit(1)
     if d.get('pending'):
-        d['pr']['autoMergeRequest'] = {'enabledAt':'now'}
+        pr['autoMergeRequest'] = {'enabledAt':'now'}
     else:
         g = [os.environ['REAL_GIT'],'--git-dir',d['bare']]
         base = remote('refs/heads/main')
-        tree = subprocess.check_output(g+['rev-parse',sha+'^{tree}'],text=True, encoding="utf-8").strip()
-        merge = subprocess.check_output(g+['commit-tree',tree,'-p',base,'-p',sha,'-m','merge fixture'],text=True, encoding="utf-8").strip()
+        # A three-way merge into the current base, as GitHub makes it; a conflicting PR does not merge.
+        merged = subprocess.run(g+['merge-tree','--write-tree',base,sha],capture_output=True,text=True,encoding="utf-8")
+        if merged.returncode:
+            save(); print('pull request is not mergeable: '+merged.stdout,file=sys.stderr); sys.exit(1)
+        parents = ['-p',base] if d.get('squash') else ['-p',base,'-p',sha]
+        merge = subprocess.check_output(g+['commit-tree',merged.stdout.split()[0],*parents,'-m','merge fixture'],text=True, encoding="utf-8").strip()
         subprocess.check_call(g+['update-ref','refs/heads/main',merge,base])
-        d['pr'].update(state='MERGED',mergedAt='now',mergeCommit={'oid':merge})
+        pr.update(state='MERGED',mergedAt='now',mergeCommit={'oid':merge})
     save()
     if d.pop('interrupt_merge',False): save(); sys.exit(1)
 else:
@@ -854,7 +904,7 @@ import json, os, pathlib, subprocess, sys
 a = sys.argv[1:]
 p = pathlib.Path(os.environ['FIXTURE_GH']); d = json.loads(p.read_text(encoding="utf-8"))
 if 'push' in a and any(x.startswith('--force-with-lease=') for x in a) and d.pop('remote_delete_race',False):
-    subprocess.check_call([os.environ['REAL_GIT'],'--git-dir',d['bare'],'update-ref','refs/heads/'+d['pr']['headRefName'],d['race_sha']])
+    subprocess.check_call([os.environ['REAL_GIT'],'--git-dir',d['bare'],'update-ref','refs/heads/'+d['prs'][0]['headRefName'],d['race_sha']])
     p.write_text(json.dumps(d), encoding="utf-8")
 for operation in ('push', 'fetch', 'ls-remote'):
     if operation in a and 'origin' in a:
@@ -1069,7 +1119,7 @@ class CompletionTests(unittest.TestCase):
                 return str(self.work / "product")
             return readlink(path, *args, **kwargs)
         with patch.object(sys, "platform", "linux"), patch.object(Path, "iterdir", entries), patch.object(os, "readlink", target):
-            with self.assertRaisesRegex(CompletionError, "active process " + process.name):
+            with self.assertRaisesRegex(WriterActive, "active process " + process.name):
                 stopped_writers(self.work)
 
     @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
@@ -1169,11 +1219,7 @@ class CompletionTests(unittest.TestCase):
             with self.assertRaisesRegex(CompletionError, "cannot parse mount table"):
                 scratch_mounts()
 
-    def accept(self, pipeline=False, queue=False, spec_expected=None, spec_name="spec.md"):
-        if spec_expected is not None:
-            (self.task / spec_name).write_text("# Fixture\nProduct contains accepted bytes.\n", encoding="utf-8")
-            (self.task / "spec.expected.json").write_text(json.dumps(spec_expected), encoding="utf-8")
-            self.g("add", spec_name, "spec.expected.json", work=self.task)
+    def accept(self):
         (self.task / "product").write_text("accepted\n", encoding="utf-8")
         self.g("add", "product", work=self.task)
         self.g("commit", "-m", "scoped task", work=self.task)
@@ -1184,32 +1230,6 @@ class CompletionTests(unittest.TestCase):
         a = {"kind": "direct", "task": "fixture", "source_sha": self.sha,
              "checks": [{"command": "fixture byte assertion", "evidence": ".devlyn/checks.txt"}]}
         self.assertEqual((self.task / "product").read_text(encoding="utf-8"), "accepted\n")
-        if pipeline:
-            a = {"kind": "pipeline", "task": "fixture", "source_sha": self.sha, "run_id": "fixture-run"}
-            archive = evidence / "runs" / a["run_id"]
-            archive.mkdir(parents=True)
-            self.archive = archive
-            report = "<!-- devlyn:final-report run_id=fixture-run -->\nFixture completed.\n"
-            (archive / "final-report.md").write_text(report, encoding="utf-8")
-            phases = {n: {"started_at": "2026-09-10T00:00:00Z", "completed_at": "2026-09-10T00:00:01Z", "verdict": "PASS"}
-                      for n in ("plan", "implement", "build_gate", "cleanup", "verify", "final_report")}
-            phases["cleanup"]["post_sha"] = self.sha
-            phases["final_report"].update(output_sha256=hashlib.sha256(report.encode()).hexdigest(), artifacts={"log_file": ".devlyn/final-report.md"})
-            criteria = "# Fixture acceptance\nProduct contains accepted bytes.\n"
-            (archive / "criteria.generated.md").write_text(criteria, encoding="utf-8")
-            source = {"type": "generated", "criteria_path": ".devlyn/criteria.generated.md", "criteria_sha256": hashlib.sha256(criteria.encode()).hexdigest()}
-            self.state = {"run_id": a["run_id"], "mode": "free-form", "source": source, "phases": phases, "process_evidence": None}
-            if spec_expected is not None:
-                self.state["mode"] = "spec"
-                self.state["source"] = {"type": "spec", "spec_path": spec_name, "spec_sha256": hashlib.sha256((self.task / spec_name).read_bytes()).hexdigest()}
-            (archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
-            (archive / "finish-gate.summary.json").write_text(json.dumps({"mode": self.state["mode"], "exit": 0, "offenders": 0, "checked": 1}), encoding="utf-8")
-            (archive / "verify-merge.summary.json").write_text(json.dumps({"verdict": "PASS"}), encoding="utf-8")
-        if queue:
-            (self.task / "queue.md").write_text("- [x] fixture\n", encoding="utf-8")
-            self.g("add", "queue.md", work=self.task)
-            self.g("commit", "-m", "terminal queue", work=self.task)
-            a["queue"] = {"commit": self.g("rev-parse", "HEAD", work=self.task), "file": "queue.md"}
         self.acceptance = evidence / "acceptance.json"
         self.acceptance.write_text(json.dumps(a), encoding="utf-8")
 
@@ -1250,7 +1270,7 @@ class CompletionTests(unittest.TestCase):
         self.assertEqual(result["status"], "PR")
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
         d = json.loads(self.data.read_text(encoding="utf-8"))
-        self.assertEqual((d["pushs"], d.get("merges", 0), d["pr"]["autoMergeRequest"]), (1, 0, None))
+        self.assertEqual((d["pushs"], d.get("merges", 0), d["prs"][0]["autoMergeRequest"]), (1, 0, None))
 
     def test_pr_mode_disables_only_owned_auto_merge(self):
         self.allocate(); self.accept()
@@ -1260,12 +1280,12 @@ class CompletionTests(unittest.TestCase):
         result, _ = self.complete("--mode", "pr")
         self.assertEqual(result["status"], "PR")
         d = json.loads(self.data.read_text(encoding="utf-8"))
-        self.assertEqual((d["disables"], d["pr"]["autoMergeRequest"]), (1, None))
-        self.configure(pr=dict(d["pr"], isCrossRepository=True, autoMergeRequest={"enabledAt": "now"}))
+        self.assertEqual((d["disables"], d["prs"][0]["autoMergeRequest"]), (1, None))
+        self.configure(prs=[dict(d["prs"][0], isCrossRepository=True, autoMergeRequest={"enabledAt": "now"})])
         _, r = self.complete("--mode", "pr", success=False)
         self.assertIn("PR head repository differs", json.loads(r.stdout)["reason"])
         d = json.loads(self.data.read_text(encoding="utf-8"))
-        self.assertEqual((d["disables"], d["pr"]["autoMergeRequest"]), (1, {"enabledAt": "now"}))
+        self.assertEqual((d["disables"], d["prs"][0]["autoMergeRequest"]), (1, {"enabledAt": "now"}))
 
     def test_remote_rewrite_after_allocation_is_rejected(self):
         self.allocate(); self.accept()
@@ -1387,6 +1407,22 @@ class CompletionTests(unittest.TestCase):
         self.assertFalse(self.task.exists())
         self.assertEqual(self.g("branch", "--list", "task/fixture"), "")
 
+    def test_unobservable_writers_settle_a_merged_delivery_and_retain_the_workspace(self):
+        from unittest.mock import patch
+        self.allocate(); self.accept()
+        self.complete("--mode", "pr", "--writers-stopped")
+        self.merge_pr()
+        args = argparse.Namespace(receipt=str(self.receipt), acceptance=None, mode=None, local_only=False, writers_stopped=False)
+        with patch.object(sys, "platform", "win32"), patch.dict(os.environ, self.env):
+            result = complete(args)
+        self.assertEqual((result["status"], result["delivery_status"]), ("CLEANUP_PENDING", "COMPLETE"))
+        self.assertIn("writer observation unsupported", result["workspace_cleanup"]["reason"])
+        receipt = json.loads(self.receipt.read_text(encoding="utf-8"))
+        self.assertEqual((receipt["delivery"], receipt.get("status")), ("COMPLETE", None))
+        self.assertTrue(self.task.exists())
+        self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
+        self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
+
     def test_release_is_refused_from_inside_the_task_tree(self):
         self.allocate(); self.accept()
         _, r = self.complete("--mode", "pr", "--writers-stopped", cwd=self.task, success=False)
@@ -1403,8 +1439,8 @@ class CompletionTests(unittest.TestCase):
         tree = self.run_cmd(bare + ["rev-parse", self.sha + "^{tree}"]).stdout.strip()
         squash = self.run_cmd(bare + ["commit-tree", tree, "-p", base, "-m", "squash fixture"]).stdout.strip()
         self.run_cmd(bare + ["update-ref", "refs/heads/main", squash, base])
-        pr = json.loads(self.data.read_text(encoding="utf-8"))["pr"]
-        self.configure(pr=dict(pr, state="MERGED", mergedAt="now", mergeCommit={"oid": squash}))
+        pr = json.loads(self.data.read_text(encoding="utf-8"))["prs"][0]
+        self.configure(prs=[dict(pr, state="MERGED", mergedAt="now", mergeCommit={"oid": squash})])
         result, _ = self.complete()
         self.assertEqual(result["status"], "COMPLETE")
         self.assertFalse(self.task.exists())
@@ -1451,7 +1487,7 @@ class CompletionTests(unittest.TestCase):
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
         # Reopen only the fixture PR to exercise the owner's pre-merge release.
         d = json.loads(self.data.read_text())
-        self.configure(pr=dict(d["pr"], state="OPEN", mergedAt=None, mergeCommit=None))
+        self.configure(prs=[dict(d["prs"][0], state="OPEN", mergedAt=None, mergeCommit=None)])
         self.receipt, self.task = receipt, task
         result, _ = self.complete("--mode", "pr", "--writers-stopped")
         self.assertEqual(result["status"], "PR")
@@ -1493,13 +1529,13 @@ class CompletionTests(unittest.TestCase):
         saved.update(pr_number=1, writers_released=True)
         unaccepted.write_text(json.dumps(saved))
         unaccepted_before = unaccepted.read_bytes()
-        pr = json.loads(self.data.read_text())["pr"]
-        self.configure(pr=dict(pr, state="CLOSED"))
+        pr = json.loads(self.data.read_text())["prs"][0]
+        self.configure(prs=[dict(pr, state="CLOSED")])
         result = self.allocate("closed")
         self.assertEqual(result["reconciled"], [])
         self.assertEqual(receipt.read_bytes(), before)
         self.assertTrue(task.exists())
-        self.configure(pr=pr)
+        self.configure(prs=[pr])
         self.merge_pr()
         self.g("worktree", "lock", str(task))
         result = self.allocate("locked")
@@ -1672,36 +1708,21 @@ class CompletionTests(unittest.TestCase):
         self.assertFalse(self.task.exists())
 
     def test_linked_custody_and_interrupted_removal(self):
-        self.allocate(); self.accept(pipeline=True)
+        self.allocate(); self.accept()
         self.configure(interrupt_remove=True)
         result, r = self.complete("--writers-stopped", "--mode", "auto", success=False)
         self.assertNotEqual(r.returncode, 0)
         self.assertFalse(self.task.exists())
         saved = json.loads(self.receipt.read_text(encoding="utf-8"))
         self.assertNotIn("cleanup_started", saved)
-        recovered = self.receipt.parent / "custody" / ".devlyn/runs/fixture-run/final-report.md"
-        self.assertEqual(hashlib.sha256(recovered.read_bytes()).hexdigest(), saved["files"][".devlyn/runs/fixture-run/final-report.md"]["sha256"])
+        recovered = self.receipt.parent / "custody" / ".devlyn/checks.txt"
+        self.assertEqual(hashlib.sha256(recovered.read_bytes()).hexdigest(), saved["files"][".devlyn/checks.txt"]["sha256"])
         result, _ = self.complete("--writers-stopped", acceptance=False)
         self.assertEqual(result["status"], "COMPLETE")
         self.assertEqual(self.g("show", saved["recovery_ref"]+":product"), "accepted")
 
-    def test_reject_acceptance_and_policy_before_push(self):
-        self.allocate(); self.accept(pipeline=True)
-        original = json.loads(json.dumps(self.state))
-        for case in ("failed", "verify-only", "blocked", "unfinished", "digest", "source"):
-            state = json.loads(json.dumps(original))
-            if case == "failed": state["phases"]["verify"]["verdict"] = "NEEDS_WORK"
-            if case == "verify-only": state["mode"] = "verify-only"
-            if case == "blocked": state["phases"]["implement"]["verdict"] = "BLOCKED"
-            if case == "unfinished": state["phases"]["verify"]["completed_at"] = None
-            if case == "digest": state["phases"]["final_report"]["output_sha256"] = "0"*64
-            if case == "source": state["phases"]["cleanup"]["post_sha"] = self.g("rev-parse", "main")
-            (self.archive / "pipeline.state.json").write_text(json.dumps(state), encoding="utf-8")
-            with self.subTest(case=case):
-                _, r = self.complete(success=False)
-                self.assertNotEqual(r.returncode, 0)
-                self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
-        (self.archive / "pipeline.state.json").write_text(json.dumps(original), encoding="utf-8")
+    def test_reject_invalid_policy_before_push(self):
+        self.allocate(); self.accept()
         for value in ("typo", "", " auto"):
             self.g("config", "--local", "devlyn.completionMode", value)
             _, r = self.complete("--mode", "pr", success=False)
@@ -1710,8 +1731,8 @@ class CompletionTests(unittest.TestCase):
         self.assertEqual(result["status"], "LOCAL_ONLY")
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("creates", 0), 0)
 
-    def test_queue_only_and_unverified_descendant(self):
-        self.allocate(); self.accept(pipeline=True, queue=True)
+    def test_unverified_descendant_is_never_merged(self):
+        self.allocate(); self.accept()
         result, _ = self.complete("--mode", "pr")
         self.assertEqual(result["status"], "PR")
         (self.task / "product").write_text("unverified", encoding="utf-8")
@@ -1788,13 +1809,16 @@ class CompletionTests(unittest.TestCase):
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("merges",0), 0)
 
     def test_actual_foreign_writer_and_registration(self):
+        # H4. Prediction: a process still using the merged task's tree settles the delivery COMPLETE with the workspace
+        # retained (CLEANUP_PENDING) and the process named, as unobservable writers do. Before: complete ended BLOCKED
+        # "active process <pid> uses task files", so the merged delivery never settled and a drain stopped there.
         self.allocate(); self.accept()
         child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"], cwd=self.task)
         try:
-            _, 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.assertIn("active process", result["workspace_cleanup"]["reason"])
             self.assertTrue(self.task.exists())
-            self.assertIn("active process", json.loads(r.stdout)["reason"])
         finally:
             child.terminate(); child.wait(timeout=5)
         # A foreign branch in the same registered tree never inherits ownership.
@@ -1829,45 +1853,52 @@ class CompletionTests(unittest.TestCase):
         self.assertEqual(result["status"], "PR")
         self.assertIn("disallows auto merge", result["merge_refused"])
         self.assertTrue(self.task.exists())
-        result, _ = self.complete("--no-push")
-        self.assertEqual(result["status"], "LOCAL_ONLY")
-        result, _ = self.complete(acceptance=False)
-        self.assertEqual(result["status"], "LOCAL_ONLY")
-
-    def test_queue_commit_cannot_hide_product_changes(self):
-        self.allocate(); self.accept(pipeline=True, queue=True)
-        (self.task / "product").write_text("unverified extra\n", encoding="utf-8")
-        self.g("add", "product", work=self.task)
-        self.g("commit", "--amend", "--no-edit", work=self.task)
-        a = json.loads(self.acceptance.read_text(encoding="utf-8"))
-        a["queue"]["commit"] = self.g("rev-parse", "HEAD", work=self.task)
-        self.acceptance.write_text(json.dumps(a), encoding="utf-8")
-        _, r = self.complete(success=False)
-        self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
-
-    def test_pipeline_sealed_process_evidence(self):
-        self.allocate(); self.accept(pipeline=True)
-        evidence_module = shared("process-evidence")
-        obligation = {"id": "actual-check", "phase": "verify", "argv": [sys.executable, "-c", "print('fixture passed')"], "exit_code": 0, "stdout_contains": ["fixture passed"], "timeout_sec": 10}
-        relative = ".devlyn/process-evidence/fixture-run/verify/round-0/manifest.json"
-        evidence_module["capture_process"](self.task, self.task / relative, "fixture-run", "verify", 0, obligation)
-        carrier = evidence_module["validate_manifest"](self.task, relative, "fixture-run", "verify", 0, [obligation])
-        results = {"commands": evidence_module["bound_carrier_summary_commands"](self.task, carrier), "process_evidence": carrier}
-        self.state["phases"]["verify"]["round"] = 0
-        self.state["process_evidence"] = [carrier]
-        (self.archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
-        (self.archive / "spec-verify.results.json").write_text(json.dumps(results), encoding="utf-8")
-        shutil.move(str(self.task / ".devlyn/process-evidence"), str(self.archive / "process-evidence"))
-        stdout = self.archive / carrier["streams"][0]["stdout"]["path"].removeprefix(".devlyn/")
-        before = stdout.read_bytes()
-        stdout.write_text("tampered", encoding="utf-8")
-        _, r = self.complete(success=False)
-        self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
-        stdout.write_bytes(before)
-        result, _ = self.complete("--mode", "pr")
-        self.assertEqual(result["status"], "PR")
+        # 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)
+        self.assertIn("fixture already has a pushed PR https://github.com/test/project/pull/1", result["reason"])
+        self.assertNotIn("local_only", json.loads(self.receipt.read_text(encoding="utf-8")))
+
+    def test_pipeline_acceptance_is_refused_with_recovery_instruction(self):
+        # Binding an archived resolve run needed the retired helpers. Whatever completion flags come with it,
+        # it is refused before the receipt, a ref or the worktree changes, with the 4.1.0 command that finishes
+        # it in the requested delivery mode; it never becomes direct acceptance.
+        self.allocate(); self.accept()
+        self.acceptance.write_text(json.dumps({"kind": "pipeline", "task": "fixture", "source_sha": self.sha,
+                                               "run_id": "fixture-run"}), encoding="utf-8")
+        def state():
+            return (self.receipt.read_bytes(), self.g("show-ref"), self.g("rev-parse", "HEAD", work=self.task),
+                    self.g("status", "--porcelain", "--untracked-files=all", work=self.task),
+                    sorted(p.name for p in self.receipt.parent.iterdir() if p.name != "lock"))
+        before = state()
+        publish, local = "binds the pipeline acceptance before publishing", "ends as LOCAL_ONLY without binding"
+        for flags, outcome in (((), publish), (("--mode", "pr"), publish), (("--mode", "auto", "--writers-stopped"), publish),
+                               (("--local-only",), local), (("--local-only", "--writers-stopped"), local)):
+            with self.subTest(flags=flags):
+                result, r = self.complete(*flags, success=False)
+                self.assertEqual((r.returncode, result["status"]), (1, "BLOCKED"))
+                self.assertEqual(state(), before)
+                self.assertIn("`npm pack devlyn-cli@4.1.0`", result["reason"])
+                self.assertIn(shlex.join(["complete", "--receipt", str(self.receipt), "--acceptance", str(self.acceptance), *flags]) + "`",
+                              result["reason"])
+                self.assertIn(outcome, result["reason"])
+        result, r = self.cli("accept", "--receipt", self.receipt, "--acceptance", self.acceptance, success=False)
+        self.assertEqual((r.returncode, result["status"]), (1, "BLOCKED"))
+        self.assertEqual(state(), before)
+        self.assertIn(publish, result["reason"])
+        self.assertNotIn(json.loads(before[0])["recovery_ref"], before[1])
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs", 0), 0)
+
+    def test_bound_pipeline_receipt_resumes_delivery(self):
+        # A receipt an earlier release bound to a resolve run keeps its custody; delivery resumes here.
+        self.allocate(); self.accept()
+        self.cli("accept", "--receipt", self.receipt, "--acceptance", self.acceptance)
+        receipt = json.loads(self.receipt.read_text(encoding="utf-8"))
+        receipt["acceptance"] = {"kind": "pipeline", "task": "fixture", "source_sha": self.sha, "run_id": "fixture-run"}
+        self.receipt.write_text(json.dumps(receipt), encoding="utf-8")
+        result, _ = self.complete("--writers-stopped", "--mode", "auto", acceptance=False)
+        self.assertEqual((result["status"], result["acceptance"]), ("COMPLETE", "pipeline"))
+        self.assertFalse(self.task.exists())
+        self.assertEqual(self.g("show", receipt["recovery_ref"] + ":product"), "accepted")
 
     def test_legacy_in_place_resume_does_not_overwrite_ignored_collision(self):
         self.allocate_legacy(); self.accept()
@@ -1914,45 +1945,219 @@ class CompletionTests(unittest.TestCase):
         self.assertTrue(self.task.exists())
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
 
-    def test_spec_source_and_report_binding(self):
-        self.allocate(); self.accept(pipeline=True, spec_expected={"verification_commands": []})
-        report = self.archive / "final-report.md"
-        original = report.read_bytes()
-        report.write_text("<!-- devlyn:final-report run_id=another-run -->\nBody\n", encoding="utf-8")
-        self.state["phases"]["final_report"]["output_sha256"] = hashlib.sha256(report.read_bytes()).hexdigest()
-        (self.archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
-        _, r = self.complete(success=False)
-        self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
-        report.write_bytes(original)
-        self.state["phases"]["final_report"]["output_sha256"] = hashlib.sha256(original).hexdigest()
-        (self.archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
-        result, _ = self.complete("--mode", "pr")
-        self.assertEqual(result["status"], "PR")
+    def allocate_local(self, name, **source):
+        args = ["allocate", "--repo", self.work, "--task", name, "--branch", "task/"+name, "--repository", "test/project",
+                "--base", "main", "--worktree", self.root / name]
+        for key, value in source.items():
+            args += ["--" + key.replace("_", "-"), value]
+        result, _ = self.cli(*args)
+        self.receipt, self.task = Path(result["receipt"]), Path(result["worktree"])
+        return result
 
-    def test_missing_required_process_evidence(self):
-        expected = {"process_evidence": [{"id": "red-first", "phase": "implement", "argv": [sys.executable, "-c", "print('red')"], "exit_code": 0, "timeout_sec": 10}]}
-        self.allocate(); self.accept(pipeline=True, spec_expected=expected)
-        _, r = self.complete(success=False)
-        self.assertNotEqual(r.returncode, 0)
-        self.assertIn("implement process evidence", json.loads(r.stdout)["reason"])
-        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
+    def loop_result(self, verdict="ACCEPTED"):
+        (self.task / "product").write_text(verdict.lower() + "\n", encoding="utf-8")
+        self.g("add", "product", work=self.task)
+        self.g("commit", "-m", "loop source", work=self.task)
+        self.sha = self.g("rev-parse", "HEAD", work=self.task)
+        stream = self.task / ".devlyn/loop/runs/1/cmd-0.stdout"
+        stream.parent.mkdir(parents=True, exist_ok=True)
+        stream.write_text("check output\n", encoding="utf-8")
+        self.acceptance = self.task / ".devlyn/loop/acceptance.json"
+        self.acceptance.write_text(json.dumps({"kind": "loop", "task": json.loads(self.receipt.read_text())["task"], "source_sha": self.sha,
+                                               "verdict": verdict, "evidence": [".devlyn/loop/runs/1/cmd-0.stdout"]}), encoding="utf-8")
+        return self.cli("accept", "--receipt", self.receipt, "--acceptance", self.acceptance)[0]
+
+    def terminal(self):
+        (self.task / "queue.md").write_text("- [x] fixture\n", encoding="utf-8")
+        self.g("add", "queue.md", work=self.task)
+        self.g("commit", "-m", "terminal", work=self.task)
+        commit = self.g("rev-parse", "HEAD", work=self.task)
+        return commit, self.cli("attach", "--receipt", self.receipt, "--commit", commit, "--file", "queue.md")[0]
+
+    def test_local_chain_starts_from_accepted_source_not_terminal_commit(self):
+        base = self.g("rev-parse", "main")
+        other = self.root / "advance"  # The remote advances; a local allocation never fetches it.
+        self.run_cmd(["git", "clone", str(self.bare), str(other)])
+        (other / "product").write_text("remote advance\n", encoding="utf-8")
+        self.g("commit", "-am", "remote advance", work=other)
+        self.g("push", "origin", "main", work=other)
+        self.configure(pushs=0)
+        result = self.allocate_local("first", local_base=base)
+        receipt = json.loads(self.receipt.read_text())
+        self.assertEqual((result["reconciled"], receipt["baseline"], receipt["local_only"]), ([], base, True))
+        self.assertNotEqual(self.run_cmd(["git", "-C", str(self.work), "rev-parse", "--verify", "--quiet", "refs/remotes/origin/main"], success=False).returncode, 0)
+        self.assertEqual(self.loop_result()["status"], "ACCEPTED")
+        source = self.sha
+        terminal, _ = self.terminal()
+        receipt = json.loads(self.receipt.read_text())
+        self.assertEqual((receipt["source_sha"], receipt["publish_sha"], self.g("rev-parse", receipt["recovery_ref"])), (source, terminal, terminal))
+        first = self.receipt
+        self.allocate_local("second", from_receipt=first)
+        second = json.loads(self.receipt.read_text())
+        self.assertEqual((second["baseline"], second["allocated_from"]["source_sha"], self.g("rev-parse", "HEAD", work=self.task)), (source, source, source))
+        self.receipt = first
+        result, _ = self.complete("--mode", "auto", acceptance=False)
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        self.assertEqual(json.loads(self.data.read_text()).get("pushs", 0), 0)
+
+    def test_local_allocation_refuses_unaccepted_failed_or_inexact_sources(self):
+        self.allocate_local("pending", local_base=self.g("rev-parse", "main"))
+        predecessor = self.receipt
+        args = ["allocate", "--repo", self.work, "--task", "next", "--branch", "task/next", "--repository", "test/project",
+                "--base", "main", "--worktree", self.root / "next"]
+        for state in ("pending", "failed"):
+            if state == "failed":
+                self.assertEqual(self.loop_result("FAILED")["status"], "FAILED")
+            result, _ = self.cli(*args, "--from-receipt", predecessor, success=False)
+            self.assertIn("predecessor has no accepted result", result["reason"])
+        result, _ = self.cli(*args, "--local-base", "main", success=False)
+        self.assertIn("exact local commit", result["reason"])
+        self.assertEqual(self.g("branch", "--list", "task/next"), "")
+        self.assertFalse((self.root / "next").exists())
+
+    def test_local_allocation_needs_no_repository(self):
+        """E4. Prediction: without --repository, a remote allocation is refused naming it, with nothing created, while a
+        local allocation, here beside an origin that is not GitHub, is ALLOCATED and its local-only completion returns
+        LOCAL_ONLY with nothing pushed. Before: argparse required --repository, so both failed as an argparse error."""
+        args = ["allocate", "--repo", self.work, "--base", "main"]
+        refused, _ = self.cli(*args, "--task", "next", "--branch", "task/next", "--worktree", self.root / "next", success=False)
+        self.assertIn("--repository", refused["reason"])
+        self.assertEqual((self.g("branch", "--list", "task/next"), (self.root / "next").exists()), ("", False))
+        self.g("remote", "set-url", "origin", "https://gitlab.com/team/project.git")
+        result, _ = self.cli(*args, "--task", "fixture", "--branch", "task/fixture", "--worktree", self.root / "linked",
+                             "--local-base", self.g("rev-parse", "HEAD"))
+        self.assertEqual(result["status"], "ALLOCATED")
+        self.receipt, self.task = Path(result["receipt"]), Path(result["worktree"])
+        self.accept()
+        self.assertEqual(self.complete("--local-only")[0]["status"], "LOCAL_ONLY")
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs", 0), 0)
+
+    def test_local_allocation_needs_no_base(self):
+        """P4-2. Prediction: a local allocation with --local-base and no --base, the form agents wrote in 3 of 3 timed
+        runs, is ALLOCATED and completes LOCAL_ONLY, while a remote allocation without --base is refused naming it, with
+        nothing created."""
+        args = ["allocate", "--repo", self.work, "--task", "fixture", "--branch", "task/fixture", "--worktree", self.root / "linked"]
+        refused, _ = self.cli(*args, "--repository", "test/project", success=False)
+        self.assertIn("--base", refused["reason"])
+        self.assertEqual((self.g("branch", "--list", "task/fixture"), (self.root / "linked").exists()), ("", False))
+        result, _ = self.cli(*args, "--local-base", self.g("rev-parse", "HEAD"))
+        self.assertEqual(result["status"], "ALLOCATED")
+        self.receipt, self.task = Path(result["receipt"]), Path(result["worktree"])
+        self.accept()
+        self.assertEqual(self.complete("--local-only")[0]["status"], "LOCAL_ONLY")
 
-    def test_named_spec_custody(self):
-        self.allocate(); self.accept(pipeline=True, spec_expected={"pure_design": True}, spec_name="X.md")
-        result, _ = self.complete("--mode", "pr")
+    def test_allocation_canonicalizes_symlinked_and_dotted_worktree_paths(self):
+        """P4-2. Prediction: an absent worktree path reached through a symlinked directory (macOS /tmp) or written with
+        `..` (`../work-x`, `$(pwd -P)/../work-x`) is ALLOCATED at its canonical path, and that path, now present, is
+        refused through the link as not absent."""
+        alias = self.root / "alias"
+        alias.symlink_to(self.root, target_is_directory=True)
+        args = ["allocate", "--repo", self.work, "--base", "main", "--local-base", self.g("rev-parse", "HEAD")]
+        for name, given in (("linked", alias / "linked"), ("dotted", Path("..") / "dotted")):
+            result, _ = self.cli(*args, "--task", name, "--branch", "task/" + name, "--worktree", given, cwd=self.work)
+            self.assertEqual((result["status"], result["worktree"]), ("ALLOCATED", str(self.root / name)))
+            self.assertEqual(self.g("rev-parse", "--show-toplevel", work=self.root / name), str(self.root / name))
+        refused, _ = self.cli(*args, "--task", "again", "--branch", "task/again", "--worktree", alias / "dotted", success=False)
+        self.assertIn("linked worktree must be an absent path", refused["reason"])
+
+    def test_completion_accepts_the_path_form_the_worktree_was_allocated_with(self):
+        """Prediction: an acceptance named through the symlinked or `..` form the worktree was allocated with completes
+        LOCAL_ONLY; before, allocate canonicalized the worktree but complete refused that form as outside it."""
+        alias = self.root / "alias"
+        alias.symlink_to(self.root, target_is_directory=True)
+        for name, given in (("linked", alias / "linked"), ("dotted", Path("..") / "dotted")):
+            result, _ = self.cli("allocate", "--repo", self.work, "--task", "fixture", "--branch", "task/" + name,
+                                 "--worktree", given, "--local-base", self.g("rev-parse", "HEAD"), cwd=self.work)
+            self.receipt, self.task = Path(result["receipt"]), Path(result["worktree"])
+            self.accept()
+            self.acceptance = given / ".devlyn" / "acceptance.json"
+            self.assertEqual(self.complete("--local-only", cwd=self.work)[0]["status"], "LOCAL_ONLY")
+
+    def test_remote_allocation_starts_from_an_exact_commit(self):
+        # An ideate auto/pr task starts from the exact refreshed remote base the drain checked, never a second fetch.
+        (self.work / "product").write_text("added locally\n", encoding="utf-8")
+        self.g("commit", "-qam", "devlyn loop: add fixture")
+        start = self.g("rev-parse", "HEAD")
+        args = ["allocate", "--repo", self.work, "--task", "first", "--branch", "task/first", "--repository", "test/project",
+                "--base", "main", "--worktree", self.root / "first"]
+        for extra, reason in ((["--start", "main"], "--start must name an exact local commit"),
+                              (["--start", start, "--local-base", start], "use one of --local-base, --from-receipt or --start")):
+            self.assertIn(reason, self.cli(*args, *extra, success=False)[0]["reason"])
+        result, _ = self.cli(*args, "--start", start)
+        receipt = json.loads(Path(result["receipt"]).read_text(encoding="utf-8"))
+        self.assertEqual((receipt["baseline"], receipt.get("local_only"), self.g("rev-parse", "HEAD", work=Path(result["worktree"]))),
+                         (start, None, start))
+
+    def test_failed_loop_result_keeps_custody_and_recovery_but_never_publishes(self):
+        self.allocate()
+        self.assertEqual(self.loop_result("FAILED")["status"], "FAILED")
+        receipt = json.loads(self.receipt.read_text())
+        self.assertEqual((receipt["product"], self.g("rev-parse", receipt["recovery_ref"])), ("FAILED", self.sha))
+        self.assertTrue((self.receipt.parent / "custody/.devlyn/loop/runs/1/cmd-0.stdout").is_file())
+        terminal, _ = self.terminal()
+        self.assertEqual(self.g("rev-parse", receipt["recovery_ref"]), terminal)
+        result, _ = self.complete("--mode", "auto", acceptance=False)
+        self.assertEqual(result["status"], "FAILED")
+        d = json.loads(self.data.read_text())
+        self.assertEqual((d.get("pushs", 0), d.get("creates", 0)), (0, 0))
+
+    def test_bind_requires_the_source_checkout_only_for_a_publishable_result(self):
+        for verdict in ("ACCEPTED", "FAILED"):
+            with self.subTest(verdict=verdict):
+                self.allocate(verdict.lower() + "-detached")
+                (self.task / "product").write_text("source\n", encoding="utf-8")
+                self.g("add", "product", work=self.task)
+                self.g("commit", "-m", "loop source", work=self.task)
+                sha = self.g("rev-parse", "HEAD", work=self.task)
+                self.g("checkout", "-q", "--detach", "HEAD~1", work=self.task)  # The executor left HEAD at another commit.
+                acceptance = self.task / ".devlyn/loop/acceptance.json"
+                acceptance.parent.mkdir(parents=True, exist_ok=True)
+                (self.task / ".devlyn/loop/out.txt").write_text("check output\n", encoding="utf-8")
+                acceptance.write_text(json.dumps({"kind": "loop", "task": json.loads(self.receipt.read_text())["task"], "source_sha": sha,
+                                                  "verdict": verdict, "evidence": [".devlyn/loop/out.txt"]}), encoding="utf-8")
+                result, _ = self.cli("accept", "--receipt", self.receipt, "--acceptance", acceptance, success=False)
+                self.assertEqual(result["status"], "FAILED" if verdict == "FAILED" else "BLOCKED", result)
+
+    def test_attach_requires_the_terminal_checkout_only_for_a_publishable_result(self):
+        for verdict in ("ACCEPTED", "FAILED"):
+            with self.subTest(verdict=verdict):
+                self.allocate(verdict.lower())
+                self.loop_result(verdict)
+                (self.task / "queue.md").write_text("- [x] fixture\n", encoding="utf-8")
+                self.g("add", "queue.md", work=self.task)
+                self.g("commit", "-m", "terminal", work=self.task)
+                terminal = self.g("rev-parse", "HEAD", work=self.task)
+                self.g("checkout", "-q", "--detach", self.sha, work=self.task)  # The task ref is terminal; HEAD stays at the source.
+                result, _ = self.cli("attach", "--receipt", self.receipt, "--commit", terminal, "--file", "queue.md", success=False)
+                self.assertEqual(result["status"], "ATTACHED" if verdict == "FAILED" else "BLOCKED", result)
+
+    def test_local_only_completion_binds_acceptance_custody(self):
+        self.allocate(); self.accept()
+        result, _ = self.complete("--local-only")
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        receipt = json.loads(self.receipt.read_text())
+        self.assertEqual((receipt["source_sha"], self.g("rev-parse", receipt["recovery_ref"])), (self.sha, self.sha))
+        verify_files(self.receipt.parent / "custody", receipt["files"])
+
+    def test_attach_binds_only_a_queue_only_commit_and_publishes_it_with_the_source(self):
+        self.allocate(); self.loop_result()
+        source = self.sha
+        (self.task / "product").write_text("unaccepted\n", encoding="utf-8")
+        (self.task / "queue.md").write_text("- [x] fixture\n", encoding="utf-8")
+        self.g("add", "product", "queue.md", work=self.task)
+        self.g("commit", "-m", "mixed", work=self.task)
+        result, _ = self.cli("attach", "--receipt", self.receipt, "--commit", self.g("rev-parse", "HEAD", work=self.task),
+                             "--file", "queue.md", success=False)
+        self.assertIn("exactly the declared queue file", result["reason"])
+        self.g("reset", "--hard", source, work=self.task)
+        terminal, attached = self.terminal()
+        self.assertEqual(attached["status"], "ATTACHED")
+        self.assertEqual(self.cli("attach", "--receipt", self.receipt, "--commit", terminal, "--file", "queue.md")[0]["status"], "ATTACHED")
+        receipt = json.loads(self.receipt.read_text())
+        self.assertEqual((receipt["source_sha"], receipt["publish_sha"]), (source, terminal))
+        result, _ = self.complete("--mode", "pr", acceptance=False)
         self.assertEqual(result["status"], "PR")
-        receipt = json.loads(self.receipt.read_text(encoding="utf-8"))
-        self.assertIn("spec.expected.json", receipt["files"])
-        self.assertEqual((self.receipt.parent / "custody/spec.expected.json").read_bytes(), (self.task / "spec.expected.json").read_bytes())
-
-    def test_named_spec_missing_required_process_evidence(self):
-        expected = {"process_evidence": [{"id": "red-first", "phase": "implement", "argv": [sys.executable, "-c", "print('red')"], "exit_code": 0, "timeout_sec": 10}]}
-        self.allocate(); self.accept(pipeline=True, spec_expected=expected, spec_name="X.md")
-        _, r = self.complete(success=False)
-        self.assertNotEqual(r.returncode, 0)
-        self.assertIn("implement process evidence", json.loads(r.stdout)["reason"])
-        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
+        self.assertEqual(json.loads(self.data.read_text())["prs"][0]["headRefOid"], terminal)
 
 
 if __name__ == "__main__":