devlyn-cli 3.1.0 → 3.1.2

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

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import argparse
 import contextlib
-import fcntl
 import functools
 import hashlib
 import json
@@ -35,7 +34,7 @@ def require(condition, message):
 
 
 def command(argv, *, cwd=None, ok=(0,)):
-    result = subprocess.run(argv, cwd=cwd, capture_output=True, text=True)
+    result = subprocess.run(argv, cwd=cwd, capture_output=True, text=True, encoding="utf-8")
     require(result.returncode in ok, f"{shlex.join(argv[:4])}: {result.stderr.strip() or result.stdout.strip()}")
     return result.stdout.strip()
 
@@ -51,23 +50,24 @@ 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())
+    return shared("archive_run")["loads_strict_json"](path.read_text(encoding="utf-8"))
 
 
 def atomic_json(path, value):
     fd, temporary = tempfile.mkstemp(dir=path.parent, prefix=".receipt-")
     try:
-        with os.fdopen(fd, "w") as stream:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
             json.dump(value, stream, sort_keys=True, indent=2)
             stream.write("\n")
             stream.flush()
             os.fsync(stream.fileno())
         os.replace(temporary, path)
-        directory = os.open(path.parent, os.O_RDONLY)
-        try:
-            os.fsync(directory)
-        finally:
-            os.close(directory)
+        if os.name != "nt":
+            directory = os.open(path.parent, os.O_RDONLY)
+            try:
+                os.fsync(directory)
+            finally:
+                os.close(directory)
     finally:
         Path(temporary).unlink(missing_ok=True)
 
@@ -167,7 +167,7 @@ def repository_from_url(url):
 
 
 def policy(receipt, override):
-    config = subprocess.run(["git", "--git-dir", receipt["common_gitdir"], "config", "--local", "--get-all", "devlyn.completionMode"], capture_output=True, text=True)
+    config = subprocess.run(["git", "--git-dir", receipt["common_gitdir"], "config", "--local", "--get-all", "devlyn.completionMode"], capture_output=True, text=True, encoding="utf-8")
     require(config.returncode in {0, 1}, "cannot read local completion policy: " + config.stderr.strip())
     require(config.returncode == 1 or config.stdout in {"auto\n", "pr\n"}, "invalid local devlyn.completionMode; use auto|pr")
     value = config.stdout.strip() if config.returncode == 0 else None
@@ -204,6 +204,9 @@ def allocate(args):
     path = directory / "receipt.json"
     receipt["id"] = key
     receipt["recovery_ref"] = "refs/devlyn/completed/" + key
+    scratch = directory / "scratch"
+    scratch.mkdir()
+    receipt["scratch_identity"] = workspace_identity(scratch, directory)
     # Persist prospective intent BEFORE native creation. An interrupted allocation
     # stays visibly incomplete; a later call may not adopt whatever now exists.
     atomic_json(path, receipt)
@@ -215,7 +218,7 @@ def allocate(args):
     receipt["worktree_identity"] = workspace_identity(target, Path(receipt["worktree_gitdir"]))
     receipt["allocation"] = "owned"
     atomic_json(path, receipt)
-    return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target)}
+    return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target), "scratch": str(scratch)}
 
 
 def pipeline_acceptance(work, acceptance, files, directory):
@@ -269,7 +272,7 @@ def pipeline_acceptance(work, acceptance, files, directory):
                 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_suffix(".expected.json")
+            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))
@@ -342,7 +345,8 @@ def bind_acceptance(receipt, path, supplied):
                     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")
-                expected = str(Path(source[key]).with_suffix(".expected.json"))
+                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)
     else:
@@ -412,7 +416,7 @@ def stopped_writers(work, *, linked):
     # The owner assertion covers its actual children; an OS observation catches
     # 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)
+        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")
         pid = None
         for line in result.stdout.splitlines():
@@ -437,6 +441,75 @@ def stopped_writers(work, *, linked):
         raise CompletionError("writer observation unsupported on this platform; retain workspace")
 
 
+def scratch_mounts():
+    if sys.platform.startswith("linux"):
+        rows = Path("/proc/self/mountinfo").read_text(encoding="utf-8").splitlines()
+        paths = []
+        for line in rows:
+            fields = line.split()
+            require(len(fields) >= 6, "cannot parse mount table; retain scratch")
+            paths.append(re.sub(r"\\([0-7]{3})", lambda m: chr(int(m[1], 8)), fields[4]))
+    elif sys.platform == "darwin":
+        paths = []
+        for line in command(["mount"]).splitlines():
+            description, separator, options = line.rpartition(" (")
+            candidates = [description[match.end():] for match in re.finditer(" on ", description)]
+            require(separator and options.endswith(")") and candidates, "cannot parse mount table; retain scratch")
+            # Darwin prints literal paths. Consider every possible separator so
+            # ' on ' in a device or directory name can only cause retention.
+            paths.extend(candidates)
+    else:
+        raise CompletionError("mount observation unsupported; retain scratch")
+    return [Path(value).resolve() for value in paths]
+
+
+def raise_walk_error(error):
+    raise error
+
+
+def clean_scratch(receipt, path, writers_stopped):
+    """Empty the owned build directory; keep its identity across resume/reuse."""
+    scratch = path.parent / "scratch"
+    if "scratch_identity" not in receipt:
+        return {"status": "NOT_OWNED"}
+    require(writers_stopped, "stop/yield scratch writers, then use --writers-stopped")
+    require(scratch == scratch.resolve() and scratch.is_dir(), "owned scratch missing or redirected; retain and inspect")
+    identity = receipt["scratch_identity"]
+    require(workspace_identity(scratch, path.parent) == identity, "scratch directory was replaced; retain")
+    require(shutil.rmtree.avoids_symlink_attacks, "safe scratch removal unsupported on this platform; retain")
+    require(not any(mount.is_relative_to(scratch) for mount in scratch_mounts()), "scratch contains a mounted filesystem; retain")
+    stopped_writers(scratch, linked=True)
+    size = 0
+    for directory, dirs, files in os.walk(scratch, followlinks=False, onerror=raise_walk_error):
+        require(not any(name.casefold() == ".git" for name in dirs + files), "scratch contains Git recovery data; move it to retained custody before cleanup")
+        for name in dirs + files:
+            item = Path(directory) / name
+            info = item.lstat()
+            require(info.st_dev == identity[0][0], "scratch contains a mounted filesystem; retain")
+            size += info.st_size if stat.S_ISREG(info.st_mode) else 0
+    stopped_writers(scratch, linked=True)
+    require(workspace_identity(scratch, path.parent) == identity, "scratch changed before removal; retain")
+    require(not any(mount.is_relative_to(scratch) for mount in scratch_mounts()), "scratch mount appeared before removal; retain")
+    for item in scratch.iterdir():
+        if item.is_dir() and not item.is_symlink():
+            shutil.rmtree(item)
+        else:
+            item.unlink()
+    require(workspace_identity(scratch, path.parent) == identity and not any(scratch.iterdir()), "scratch changed during cleanup; retain and inspect")
+    result = {"status": "CLEAN", "logical_bytes_removed": size}
+    receipt["scratch_cleanup"] = result
+    atomic_json(path, receipt)
+    return result
+
+
+def clean_scratch_command(args):
+    path = Path(args.receipt).absolute()
+    with locked_receipt(path) as receipt:
+        result = clean_scratch(receipt, path, args.writers_stopped)
+        return {"status": "SCRATCH_CLEAN" if result["status"] == "CLEAN" else "SCRATCH_NOT_OWNED",
+                "receipt": str(path), "scratch_cleanup": result, "product_verdict_unchanged": True}
+
+
 def cleanup(receipt, path, pr, writers_stopped):
     require(pr["state"] == "MERGED" and pr.get("mergedAt") and pr.get("mergeCommit", {}).get("oid"), "actual matching merge evidence is required")
     require(writers_stopped, "wait actual children, stop/yield known writers, then resume with --writers-stopped")
@@ -508,8 +581,11 @@ def cleanup(receipt, path, pr, writers_stopped):
 def locked_receipt(path):
     require(path.name == "receipt.json" and path.parent.parent.name == "devlyn-completion" and path == path.resolve(), "receipt must be its original external nonsymlink path")
     require(not (path.parent / "lock").is_symlink(), "receipt lock must not be a symlink")
-    with (path.parent / "lock").open("a+") as lock:
-        fcntl.flock(lock, fcntl.LOCK_EX)
+    with contextlib.ExitStack() as stack:
+        try:
+            stack.enter_context(shared("platform-support")["file_lock"](path.parent / "lock", blocking=True))
+        except (ImportError, OSError, AttributeError) as exc:
+            raise CompletionError(f"receipt lock unavailable: {path}: {exc}") from exc
         receipt = read_json(path)
         require(path == Path(receipt["common_gitdir"]) / "devlyn-completion" / receipt["id"] / "receipt.json", "receipt/common Gitdir binding mismatch")
         require(receipt["id"] == hashlib.sha256(receipt["branch"].encode()).hexdigest()[:24] and receipt["branch"] not in {receipt["base"], "main", "master"}, "receipt branch ownership changed")
@@ -519,11 +595,27 @@ def locked_receipt(path):
 
 def complete(args):
     path = Path(args.receipt).absolute()
-    resume = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)])
+    resume = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)] +
+                        (["--writers-stopped"] if args.writers_stopped else []))
     with locked_receipt(path) as receipt:
         def result(status):
-            return {"status": status, "receipt": str(path), "pr": receipt.get("pr_url"), "resume": resume,
-                    "acceptance": (receipt.get("acceptance") or {}).get("kind"), "product_verdict_unchanged": True}
+            scratch = {"status": "NOT_OWNED"}
+            if "scratch_identity" in receipt:
+                try:
+                    scratch = clean_scratch(receipt, path, args.writers_stopped)
+                except (CompletionError, OSError, ValueError, KeyError, TypeError, IndexError) as error:
+                    scratch = {"status": "RETAINED", "reason": str(error), "resume": shlex.join([
+                        sys.executable, str(Path(__file__).resolve()), "clean-scratch", "--receipt", str(path), "--writers-stopped"])}
+                    receipt["scratch_cleanup"] = scratch
+                    try:
+                        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,
+                    "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}
         if args.local_only or receipt.get("local_only"):
             receipt["local_only"] = True
             atomic_json(path, receipt)
@@ -607,20 +699,24 @@ def main():
     completion.add_argument("--mode", choices=("auto", "pr"))
     completion.add_argument("--local-only", "--no-push", action="store_true")
     completion.add_argument("--writers-stopped", action="store_true")
+    scratch_cleanup = actions.add_parser("clean-scratch")
+    scratch_cleanup.add_argument("--receipt", required=True)
+    scratch_cleanup.add_argument("--writers-stopped", action="store_true")
     args = parser.parse_args()
     if args.self_test:
         return self_test()
     if args.action is None:
-        parser.error("allocate or complete is required")
+        parser.error("allocate, complete or clean-scratch is required")
     try:
-        result = allocate(args) if args.action == "allocate" else complete(args)
+        result = (allocate(args) if args.action == "allocate" else
+                  clean_scratch_command(args) if args.action == "clean-scratch" else complete(args))
         print(json.dumps(result, sort_keys=True))
         return 0
-    except (CompletionError, OSError, ValueError, KeyError, TypeError, SystemExit) as exc:
+    except (CompletionError, OSError, ValueError, KeyError, TypeError, IndexError, SystemExit) as exc:
         result = {"status": "BLOCKED", "reason": str(exc)}
-        if args.action == "complete":
+        if args.action in {"complete", "clean-scratch"}:
             result["receipt"] = str(Path(args.receipt).absolute())
-            result["resume"] = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", result["receipt"]])
+            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
 
@@ -639,10 +735,10 @@ def self_test(names=None):
 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()); a = sys.argv[1:]
-def save(): p.write_text(json.dumps(d))
+d = json.loads(p.read_text(encoding="utf-8")); a = sys.argv[1:]
+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)
+    r = subprocess.run([os.environ['REAL_GIT'], '--git-dir', d['bare'], 'rev-parse', '--verify', ref], capture_output=True, text=True, encoding="utf-8")
     return r.stdout.strip() if r.returncode == 0 else None
 if a[:2] == ['repo', 'view']:
     assert a[2:] == ['github.com/test/project', '--json', 'nameWithOwner,url,defaultBranchRef,mergeCommitAllowed'], 'unsupported gh repo view arguments: '+str(a)
@@ -673,8 +769,8 @@ elif a[:2] == ['pr', 'merge']:
     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).strip()
-        merge = subprocess.check_output(g+['commit-tree',tree,'-p',base,'-p',sha,'-m','merge fixture'],text=True).strip()
+        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()
         subprocess.check_call(g+['update-ref','refs/heads/main',merge,base])
         d['pr'].update(state='MERGED',mergedAt='now',mergeCommit={'oid':merge})
     save()
@@ -686,22 +782,22 @@ else:
 GIT_WRAPPER = r'''#!/usr/bin/env python3
 import json, os, pathlib, subprocess, sys
 a = sys.argv[1:]
-p = pathlib.Path(os.environ['FIXTURE_GH']); d = json.loads(p.read_text())
+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']])
-    p.write_text(json.dumps(d))
+    p.write_text(json.dumps(d), encoding="utf-8")
 for operation in ('push', 'fetch', 'ls-remote'):
     if operation in a and 'origin' in a:
         prefix = a[:a.index(operation)]
-        url = subprocess.check_output([os.environ['REAL_GIT'], *prefix, 'remote', 'get-url', *(['--push'] if operation == 'push' else []), '--all', 'origin'], text=True).strip()
+        url = subprocess.check_output([os.environ['REAL_GIT'], *prefix, 'remote', 'get-url', *(['--push'] if operation == 'push' else []), '--all', 'origin'], text=True, encoding="utf-8").strip()
         if url in {'https://github.com/test/project.git', 'git@github.com:test/project.git', 'ssh://git@github.com/test/project.git'}:
             a[a.index('origin')] = d['bare']
         break
 r = subprocess.run([os.environ['REAL_GIT'],*a])
 event = 'delete' if 'push' in a and any(x.startswith(':refs/') for x in a) else 'push' if 'push' in a else 'remove' if 'worktree' in a and 'remove' in a else None
 if r.returncode == 0 and event:
-    d = json.loads(p.read_text()); d[event+'s'] = d.get(event+'s',0)+1
-    fail = d.pop('interrupt_'+event,False); p.write_text(json.dumps(d))
+    d = json.loads(p.read_text(encoding="utf-8")); d[event+'s'] = d.get(event+'s',0)+1
+    fail = d.pop('interrupt_'+event,False); p.write_text(json.dumps(d), encoding="utf-8")
     if fail: sys.exit(1)
 sys.exit(r.returncode)
 '''
@@ -717,7 +813,7 @@ class CompletionTests(unittest.TestCase):
         self.bin = self.root / "bin"
         self.bin.mkdir()
         self.data = self.root / "gh.json"
-        self.data.write_text(json.dumps({"bare": str(self.bare)}))
+        self.data.write_text(json.dumps({"bare": str(self.bare)}), 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",
@@ -728,13 +824,13 @@ class CompletionTests(unittest.TestCase):
                 del self.env[key]
         for name, body in (("gh", FAKE_GH), ("git", GIT_WRAPPER)):
             path = self.bin / name
-            path.write_text(body)
+            path.write_text(body, encoding="utf-8")
             path.chmod(0o755)
         self.env["PATH"] = str(self.bin) + os.pathsep + os.environ["PATH"]
         self.run_cmd(["git", "init", "--bare", "--initial-branch=main", str(self.bare)])
         self.run_cmd(["git", "init", "--initial-branch=main", str(self.work)])
-        (self.work / ".gitignore").write_text(".devlyn/\nignored/\n")
-        (self.work / "product").write_text("baseline\n")
+        (self.work / ".gitignore").write_text(".devlyn/\nignored/\n", encoding="utf-8")
+        (self.work / "product").write_text("baseline\n", encoding="utf-8")
         self.g("add", ".")
         self.g("commit", "-m", "baseline")
         self.g("remote", "add", "origin", "https://github.com/test/project.git")
@@ -742,7 +838,7 @@ class CompletionTests(unittest.TestCase):
         self.configure(pushs=0)
 
     def run_cmd(self, args, *, cwd=None, success=True):
-        r = subprocess.run(args, cwd=cwd or self.root, env=self.env, capture_output=True, text=True)
+        r = subprocess.run(args, cwd=cwd or self.root, env=self.env, capture_output=True, text=True, encoding="utf-8")
         if success:
             self.assertEqual(r.returncode, 0, r.stderr + r.stdout)
         return r
@@ -751,8 +847,8 @@ class CompletionTests(unittest.TestCase):
         return self.run_cmd(["git", "-C", str(work or self.work), *args]).stdout.strip()
 
     def configure(self, **values):
-        d = json.loads(self.data.read_text()); d.update(values)
-        self.data.write_text(json.dumps(d))
+        d = json.loads(self.data.read_text(encoding="utf-8")); d.update(values)
+        self.data.write_text(json.dumps(d), encoding="utf-8")
 
     def cli(self, *args, success=True, cwd=None):
         r = self.run_cmd([sys.executable, str(Path(__file__).resolve()), *map(str, args)], success=success, cwd=cwd)
@@ -767,49 +863,176 @@ class CompletionTests(unittest.TestCase):
         self.task = Path(result["worktree"])
         return result
 
-    def accept(self, pipeline=False, queue=False, spec_expected=None):
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_disposable_scratch_cleans_for_local_only_and_preserves_source(self):
+        result = self.allocate()
+        scratch = Path(result["scratch"])
+        (scratch / "target").mkdir()
+        (scratch / "target" / "object").write_bytes(b"rebuildable")
+        (self.task / "uncommitted-work").write_text("preserve")
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--local-only", "--writers-stopped")
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        self.assertFalse(any(scratch.iterdir()))
+        self.assertEqual((self.task / "uncommitted-work").read_text(), "preserve")
+        self.assertEqual(result["scratch_cleanup"]["logical_bytes_removed"], 11)
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["status"], "SCRATCH_CLEAN")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_rejects_active_writer_and_requires_owner_assertion(self):
+        scratch = Path(self.allocate()["scratch"])
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, success=False)
+        self.assertIn("--writers-stopped", result["reason"])
+        child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"], cwd=scratch)
+        try:
+            result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+            self.assertIn("active process", result["reason"])
+            self.assertTrue(scratch.is_dir())
+        finally:
+            child.terminate()
+            child.wait(timeout=5)
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_rejects_redirect_and_git_data_but_does_not_follow_child_links(self):
+        scratch = Path(self.allocate()["scratch"])
+        outside = self.root / "outside"
+        outside.mkdir()
+        (outside / "keep").write_text("source")
+        retained = scratch.with_name("retained")
+        scratch.rename(retained)
+        scratch.symlink_to(outside, target_is_directory=True)
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("redirected", result["reason"])
+        scratch.unlink()
+        retained.rename(scratch)
+        (scratch / ".GiT").write_text("gitdir: elsewhere")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("Git recovery data", result["reason"])
+        (scratch / ".GiT").unlink()
+        (scratch / "external-link").symlink_to(outside, target_is_directory=True)
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual((outside / "keep").read_text(), "source")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_reuse_and_partial_cleanup_keep_original_identity(self):
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / "first-build").write_bytes(b"first")
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        (scratch / "resumed-build").write_bytes(b"next")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["scratch_cleanup"]["logical_bytes_removed"], 4)
+        self.assertFalse(any(scratch.iterdir()))
+        scratch.rename(scratch.with_name("original"))
+        scratch.mkdir()
+        (scratch / "foreign").write_text("preserve")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("replaced", result["reason"])
+        self.assertIn("--writers-stopped", result["resume"])
+        self.assertEqual((scratch / "foreign").read_text(), "preserve")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_refusal_does_not_block_local_only_delivery(self):
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / ".git").mkdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--local-only", "--writers-stopped")
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        self.assertEqual(result["scratch_cleanup"]["status"], "RETAINED")
+        self.assertIn("Git recovery data", result["scratch_cleanup"]["reason"])
+        self.assertEqual(json.loads(self.receipt.read_text())["scratch_cleanup"]["status"], "RETAINED")
+        self.assertTrue((scratch / ".git").is_dir())
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_refusal_reports_delivery_separately(self):
+        scratch = Path(self.allocate()["scratch"])
+        self.accept()
+        (scratch / ".git").mkdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--acceptance", self.acceptance, "--writers-stopped")
+        self.assertEqual(result["status"], "CLEANUP_PENDING")
+        self.assertEqual(result["delivery_status"], "COMPLETE")
+        self.assertEqual(result["scratch_cleanup"]["status"], "RETAINED")
+        self.assertIn("--writers-stopped", result["scratch_cleanup"]["resume"])
+        self.assertIn("--writers-stopped", result["resume"])
+        (scratch / ".git").rmdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["status"], "COMPLETE")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_mount_and_scan_failure_preserve_contents(self):
+        from unittest.mock import patch
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / "keep").write_text("retained")
+        receipt = json.loads(self.receipt.read_text())
+        with patch.dict(clean_scratch.__globals__, {"scratch_mounts": lambda: [scratch / "same-device-bind"]}):
+            with self.assertRaisesRegex(CompletionError, "mounted filesystem"):
+                clean_scratch(receipt, self.receipt, True)
+        def failed_walk(*args, **kwargs):
+            kwargs["onerror"](PermissionError("unreadable subtree"))
+        with patch.object(os, "walk", failed_walk):
+            with self.assertRaisesRegex(PermissionError, "unreadable subtree"):
+                clean_scratch(receipt, self.receipt, True)
+        self.assertEqual((scratch / "keep").read_text(), "retained")
+
+    def test_scratch_mount_table_parsing_preserves_ambiguous_literal_paths(self):
+        from unittest.mock import patch
+        target = "/task/scratch/name on inside\\040literal"
+        with patch.object(sys, "platform", "darwin"), patch.dict(scratch_mounts.__globals__, {
+            "command": lambda args: "device on source on " + target + " (local, journaled)",
+        }):
+            self.assertIn(Path(target).resolve(), scratch_mounts())
+        alias = self.root / "scratch-alias"
+        alias.symlink_to(self.root, target_is_directory=True)
+        with patch.object(sys, "platform", "darwin"), patch.dict(scratch_mounts.__globals__, {
+            "command": lambda args: "device on " + str(alias / "mounted") + " (local)",
+        }):
+            self.assertEqual(scratch_mounts(), [(self.root / "mounted").resolve()])
+        with patch.object(sys, "platform", "linux"), patch.object(Path, "read_text", return_value="truncated row"):
+            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.md").write_text("# Fixture\nProduct contains accepted bytes.\n")
-            (self.task / "spec.expected.json").write_text(json.dumps(spec_expected))
-            self.g("add", "spec.md", "spec.expected.json", work=self.task)
-        (self.task / "product").write_text("accepted\n")
+            (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)
+        (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)
         self.sha = self.g("rev-parse", "HEAD", work=self.task)
         evidence = self.task / ".devlyn"
         evidence.mkdir(exist_ok=True)
-        (evidence / "checks.txt").write_text("actual fixture check: accepted bytes\n")
+        (evidence / "checks.txt").write_text("actual fixture check: accepted bytes\n", encoding="utf-8")
         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(), "accepted\n")
+        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)
+            (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)
+            (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.md", "spec_sha256": hashlib.sha256((self.task / "spec.md").read_bytes()).hexdigest()}
-            (archive / "pipeline.state.json").write_text(json.dumps(self.state))
-            (archive / "finish-gate.summary.json").write_text(json.dumps({"mode": self.state["mode"], "exit": 0, "offenders": 0, "checked": 1}))
-            (archive / "verify-merge.summary.json").write_text(json.dumps({"verdict": "PASS"}))
+                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")
+            (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))
+        self.acceptance.write_text(json.dumps(a), encoding="utf-8")
 
     def complete(self, *args, success=True, cwd=None, acceptance=True):
         command_args = ["complete", "--receipt", self.receipt]
@@ -843,11 +1066,11 @@ class CompletionTests(unittest.TestCase):
         alias = "git@github.com:test/project.git"
         self.g("config", "url." + alias + ".insteadOf", intended)
         self.allocate(); self.accept()
-        self.assertEqual(json.loads(self.receipt.read_text())["remote_url"], {"literal": intended, "fetch": alias, "push": alias})
+        self.assertEqual(json.loads(self.receipt.read_text(encoding="utf-8"))["remote_url"], {"literal": intended, "fetch": alias, "push": alias})
         result, _ = self.complete("--mode", "pr")
         self.assertEqual(result["status"], "PR")
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], self.sha)
-        self.assertEqual(json.loads(self.data.read_text())["pushs"], 1)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8"))["pushs"], 1)
 
     def test_remote_rewrite_after_allocation_is_rejected(self):
         self.allocate(); self.accept()
@@ -868,9 +1091,9 @@ class CompletionTests(unittest.TestCase):
         destination = "https://github.com/test/other.git"
         self.g("config", "url." + destination + ".insteadOf", "https://github.com/test/project.git")
         # Reproduce a receipt the old literal-only allocation check accepted.
-        receipt = json.loads(self.receipt.read_text())
+        receipt = json.loads(self.receipt.read_text(encoding="utf-8"))
         receipt["remote_url"].update(fetch=destination, push=destination)
-        self.receipt.write_text(json.dumps(receipt))
+        self.receipt.write_text(json.dumps(receipt), encoding="utf-8")
         local_refs = self.g("show-ref")
         remote_refs = self.run_cmd(["git", "--git-dir", str(self.bare), "show-ref"]).stdout
         server = self.data.read_bytes()
@@ -891,17 +1114,17 @@ class CompletionTests(unittest.TestCase):
         for _ in range(2):
             result, _ = self.complete("--mode", "auto")
             self.assertEqual(result["status"], "PENDING")
-        d = json.loads(self.data.read_text())
+        d = json.loads(self.data.read_text(encoding="utf-8"))
         self.assertEqual((d["creates"], d["merges"], d["pushs"]), (1, 1, 1))
 
     def test_in_place_retains_ignored_data(self):
         self.allocate(); self.accept()
         (self.task / "ignored").mkdir()
-        (self.task / "ignored" / "user.txt").write_text("retain me")
+        (self.task / "ignored" / "user.txt").write_text("retain me", encoding="utf-8")
         result, _ = self.complete("--writers-stopped")
         self.assertEqual(result["status"], "COMPLETE")
         self.assertEqual(self.g("branch", "--show-current"), "main")
-        self.assertEqual((self.task / "ignored/user.txt").read_text(), "retain me")
+        self.assertEqual((self.task / "ignored/user.txt").read_text(encoding="utf-8"), "retain me")
         self.assertEqual(self.g("branch", "--list", "task/fixture"), "")
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
         again, _ = self.complete("--writers-stopped", acceptance=False)
@@ -915,7 +1138,7 @@ class CompletionTests(unittest.TestCase):
         result, r = self.complete("--writers-stopped", success=False)
         self.assertNotEqual(r.returncode, 0)
         self.assertFalse(self.task.exists())
-        saved = json.loads(self.receipt.read_text())
+        saved = json.loads(self.receipt.read_text(encoding="utf-8"))
         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"])
         result, _ = self.complete("--writers-stopped", acceptance=False)
@@ -933,30 +1156,30 @@ class CompletionTests(unittest.TestCase):
             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))
+            (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))
+        (self.archive / "pipeline.state.json").write_text(json.dumps(original), encoding="utf-8")
         for value in ("typo", "", " auto"):
             self.g("config", "--local", "devlyn.completionMode", value)
             _, r = self.complete("--mode", "pr", success=False)
             self.assertNotEqual(r.returncode, 0)
         result, _ = self.complete("--local-only")
         self.assertEqual(result["status"], "LOCAL_ONLY")
-        self.assertEqual(json.loads(self.data.read_text()).get("creates", 0), 0)
+        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)
         result, _ = self.complete("--mode", "pr")
         self.assertEqual(result["status"], "PR")
-        (self.task / "product").write_text("unverified")
+        (self.task / "product").write_text("unverified", encoding="utf-8")
         self.g("add", "product", work=self.task)
         self.g("commit", "-m", "unverified", work=self.task)
         _, r = self.complete(success=False)
         self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text()).get("merges", 0), 0)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("merges", 0), 0)
 
     def test_interrupted_external_effects(self):
         self.allocate(); self.accept()
@@ -966,7 +1189,7 @@ class CompletionTests(unittest.TestCase):
             self.assertNotEqual(r.returncode, 0)
         result, _ = self.complete("--writers-stopped")
         self.assertEqual(result["status"], "COMPLETE")
-        d = json.loads(self.data.read_text())
+        d = json.loads(self.data.read_text(encoding="utf-8"))
         self.assertEqual((d["pushs"], d["creates"], d["merges"]), (1, 1, 1))
 
     def test_retains_unknown_dirty_locked_and_active_tree(self):
@@ -974,7 +1197,7 @@ class CompletionTests(unittest.TestCase):
         for case in ("ignored", "dirty", "untracked", "locked", "cwd", "no-yield"):
             path = self.task / ("ignored/unknown" if case == "ignored" else "product" if case == "dirty" else "unknown")
             if case in {"ignored", "dirty", "untracked"}:
-                path.parent.mkdir(exist_ok=True); path.write_text("do not delete")
+                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(*([] if case == "no-yield" else ["--writers-stopped"]), cwd=self.task if case == "cwd" else None, success=False)
@@ -982,7 +1205,7 @@ class CompletionTests(unittest.TestCase):
                 self.assertTrue(self.task.exists())
                 self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
             if case in {"ignored", "untracked"}: path.unlink()
-            if case == "dirty": path.write_text("accepted\n")
+            if case == "dirty": path.write_text("accepted\n", encoding="utf-8")
             if case == "locked": self.g("worktree", "unlock", str(self.task))
 
     def test_no_adoption_and_remote_head_race(self):
@@ -993,34 +1216,34 @@ class CompletionTests(unittest.TestCase):
         self.run_cmd(["git", "--git-dir", str(self.bare), "update-ref", "refs/heads/task/fixture", self.g("rev-parse", "main")])
         _, r = self.complete(success=False)
         self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text()).get("merges",0), 0)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("merges",0), 0)
 
     def test_concurrent_completions(self):
         self.allocate(); self.accept(); self.configure(pending=True)
         args = [sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(self.receipt), "--acceptance", str(self.acceptance)]
-        procs = [subprocess.Popen(args, cwd=self.root, env=self.env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) for _ in range(2)]
+        procs = [subprocess.Popen(args, cwd=self.root, env=self.env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8") for _ in range(2)]
         for proc in procs:
             out, err = proc.communicate(timeout=30)
             self.assertEqual(proc.returncode, 0, out+err)
-        d = json.loads(self.data.read_text())
+        d = json.loads(self.data.read_text(encoding="utf-8"))
         self.assertEqual((d["pushs"], d["creates"], d["merges"]), (1,1,1))
 
     def test_custody_failure_and_evidence_tamper(self):
         self.allocate(linked=True); self.accept()
         bad = self.receipt.parent / "custody/.devlyn/checks.txt"
         bad.parent.mkdir(parents=True)
-        bad.write_text("partial interrupted copy")
+        bad.write_text("partial interrupted copy", encoding="utf-8")
         _, r = self.complete("--writers-stopped", success=False)
         self.assertNotEqual(r.returncode, 0)
         self.assertTrue(self.task.exists())
-        self.assertEqual((self.task / ".devlyn/checks.txt").read_text(), "actual fixture check: accepted bytes\n")
+        self.assertEqual((self.task / ".devlyn/checks.txt").read_text(encoding="utf-8"), "actual fixture check: accepted bytes\n")
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture"), "")
         bad.unlink()  # Owner repairs only the identified corrupt fixture copy.
         self.complete("--mode", "pr")
-        (self.task / ".devlyn/checks.txt").write_text("altered after acceptance")
+        (self.task / ".devlyn/checks.txt").write_text("altered after acceptance", encoding="utf-8")
         _, r = self.complete("--mode", "auto", success=False)
         self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text()).get("merges",0), 0)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("merges",0), 0)
 
     def test_actual_foreign_writer_and_registration(self):
         self.allocate(linked=True); self.accept()
@@ -1053,7 +1276,7 @@ class CompletionTests(unittest.TestCase):
         self.configure(merge_allowed=False)
         _, r = self.complete(success=False)
         self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(json.loads(self.data.read_text()).get("pushs",0), 0)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
         self.complete("--mode", "pr")
         result, _ = self.complete()
         self.assertEqual(result["status"], "PR")
@@ -1068,15 +1291,15 @@ class CompletionTests(unittest.TestCase):
 
     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")
+        (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())
+        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))
+        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()).get("pushs",0), 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)
@@ -1088,15 +1311,15 @@ class CompletionTests(unittest.TestCase):
         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))
-        (self.archive / "spec-verify.results.json").write_text(json.dumps(results))
+        (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")
+        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()).get("pushs",0), 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")
@@ -1105,7 +1328,7 @@ class CompletionTests(unittest.TestCase):
         self.allocate(); self.accept()
         user_file = self.task / "ignored/user.txt"
         user_file.parent.mkdir()
-        user_file.write_text("retained user data")
+        user_file.write_text("retained user data", encoding="utf-8")
         self.configure(interrupt_delete=True)
         _, r = self.complete("--writers-stopped", success=False)
         self.assertNotEqual(r.returncode, 0)
@@ -1113,13 +1336,13 @@ class CompletionTests(unittest.TestCase):
         other = self.root / "advance"
         self.run_cmd(["git", "clone", str(self.bare), str(other)])
         (other / "ignored").mkdir()
-        (other / "ignored/user.txt").write_text("new upstream tracked file")
+        (other / "ignored/user.txt").write_text("new upstream tracked file", encoding="utf-8")
         self.g("add", "-f", "ignored/user.txt", work=other)
         self.g("commit", "-m", "upstream collision", work=other)
         self.g("push", "origin", "main", work=other)
         _, r = self.complete("--writers-stopped", acceptance=False, success=False)
         self.assertNotEqual(r.returncode, 0)
-        self.assertEqual(user_file.read_text(), "retained user data")
+        self.assertEqual(user_file.read_text(encoding="utf-8"), "retained user data")
         self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
 
     def test_replaced_tree_and_unsafe_custody(self):
@@ -1138,21 +1361,21 @@ class CompletionTests(unittest.TestCase):
         self.assertNotEqual(r.returncode, 0)
         self.assertIn("replaced", json.loads(r.stdout)["reason"])
         self.assertTrue(self.task.exists())
-        self.assertEqual(json.loads(self.data.read_text()).get("pushs",0), 0)
+        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")
+        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))
+        (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()).get("pushs",0), 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))
+        (self.archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
         result, _ = self.complete("--mode", "pr")
         self.assertEqual(result["status"], "PR")
 
@@ -1162,8 +1385,25 @@ class CompletionTests(unittest.TestCase):
         _, 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()).get("pushs",0), 0)
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
+
+    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")
+        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)
 
 
 if __name__ == "__main__":
+    runpy.run_path(str(Path(__file__).with_name("platform-support.py")))["configure_utf8"]()
     sys.exit(main())