devlyn-cli 4.2.5 → 4.2.6

package/bin/instructions.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { Lexer } = require('marked');
 const legacyTemplates = require('./instruction-templates.json');
 
 const BEGIN = '<!-- devlyn:instructions:begin';
@@ -119,16 +120,29 @@ function instructionParagraphs(text) {
   return paragraphs;
 }
 
-// Claude Code expands an `@AGENTS.md` import line, except inside a fenced code block.
+// Recognize direct adjacent imports in Markdown text, including inline imports.
+// Leaf tokens keep code, escapes and ordinary HTML from removing our only block.
 function importsAgentsMd(text) {
-  let fence = null;
-  for (const line of text.replace(/^\uFEFF/, '').split(/\r?\n/)) {
-    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
-    if (marker && !fence) fence = marker;
-    else if (marker && marker[0] === fence[0] && marker.length >= fence.length && /^ {0,3}(?:`+|~+)\s*$/.test(line)) fence = null;
-    else if (!fence && line.trimEnd() === '@AGENTS.md') return true;
-  }
-  return false;
+  // Match the complete native path token before dropping its optional fragment.
+  const matchesImport = (value) => [...value.matchAll(/(?:^|\s)@((?:[^\s\\]|\\ )+)/g)].some((match) => {
+    const file = match[1].split('#', 1)[0];
+    return file === 'AGENTS.md' || file === './AGENTS.md';
+  });
+  const containsImport = (tokens) => tokens.some((token) => {
+    if (['code', 'codespan'].includes(token.type)) return false;
+    if (token.type === 'html') {
+      const raw = token.raw || '';
+      // Native Claude scans text left after complete comments in a comment-shaped HTML token.
+      return raw.trimStart().startsWith('<!--') && raw.includes('-->')
+        && matchesImport(raw.replace(/<!--[\s\S]*?-->/g, ''));
+    }
+    if (token.tokens) return containsImport(token.tokens);
+    if (token.items) return containsImport(token.items);
+    return token.type === 'text' && matchesImport(token.text);
+  });
+  // Claude strips this bounded frontmatter prefix before expanding imports.
+  const body = text.replace(/^\uFEFF/, '').replace(/^---\s*\n([\s\S]*?)---\s*\n?/, '');
+  return containsImport(new Lexer({ gfm: false }).lex(body));
 }
 
 function customInstructions(text, name, template, managed = false) {

package/bin/skill-history.json

@@ -1,11 +1,12 @@
 {
-  "source": "devlyn-cli@4.1.0 (npm tarball sha1 398ff07d3d689b56cc22e18ac50260bc6e4e9e85); devlyn-cli@4.2.0 (npm tarball sha1 c93c2fb1cf5630b18d2eba0085182c14fddbe2d5); devlyn-cli@4.2.4 and 4.2.5 (_shared and devlyn-ideate, fingerprinted from an install of each packed tarball); whole-tree fingerprints from bin/skill-ownership.js; deprecated commands: commands/ and optional-commands/*/ files of devlyn-cli 0.0.1-0.5.8 (every published version that shipped them), LF-normalized SHA-256",
+  "source": "devlyn-cli@4.1.0 (npm tarball sha1 398ff07d3d689b56cc22e18ac50260bc6e4e9e85); devlyn-cli@4.2.0 (npm tarball sha1 c93c2fb1cf5630b18d2eba0085182c14fddbe2d5); devlyn-cli@4.2.4, 4.2.5 and 4.2.6 (_shared and devlyn-ideate, fingerprinted from an install of each packed tarball); whole-tree fingerprints from bin/skill-ownership.js; deprecated commands: commands/ and optional-commands/*/ files of devlyn-cli 0.0.1-0.5.8 (every published version that shipped them), LF-normalized SHA-256",
   "skills": {
     "_shared": [
       "eb3327d5e6940bd5e0459fa28c9ab323d9c58ccfdeb9426c19cd027cc4e5c4ed",
       "8c80926ab03b2477e52264495b35c2116f65fc51b02e8c56e441b5705872392a",
       "3c81c575cc43d70488865b440204cb399091405d9b7f81dbf047a32d3d5ac045",
-      "6546d6b833701f2641a004802cfc17ec62442e5d0003f396cb0231b676ba9a4a"
+      "6546d6b833701f2641a004802cfc17ec62442e5d0003f396cb0231b676ba9a4a",
+      "640500e3ada3d81645c293ddc956e9757f0c4ba0a06e3f914c9bdad4968cbc66"
     ],
     "devlyn-design-ui": [
       "91080266232fb62b6f1d45932184f065589e12eb66f02fb6442527c6dfcd81b6"
@@ -18,7 +19,8 @@
       "8ff5148cc65b4608c35b29afd6fef20d42d8da93a094144d98cfc63e74089b6e",
       "5824f07e455fe1c3942bf595a12e935258d4c0a851ca1bf741db915603d1c4e0",
       "7f451e48e391643b34f6249244bc47d93d6303875e7b092771e3af0718343bc1",
-      "d6433bf0f96dd9dd485c3623885255738654674b3e23cfcc1a2cfd24f3cda96e"
+      "d6433bf0f96dd9dd485c3623885255738654674b3e23cfcc1a2cfd24f3cda96e",
+      "7fb3ceaf835230e1a75e510b046f4fe26e79815760354bec1949fa55515c6316"
     ],
     "devlyn-queue": [
       "4c7d988dcd154c7bf658d2d24cd7868955df9d854ed87eb784742d6d4bb229e0"

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

@@ -185,7 +185,8 @@ def policy(receipt, override):
     return override or value or "auto"
 
 
-def allocate(args):
+def allocate(args, *, exclude_receipts=()):
+    """Reconcile older tasks, except receipts the queue has identified as invalid."""
     work = Path(git(Path(args.repo).resolve(), "rev-parse", "--show-toplevel")).resolve()
     common = Path(git(work, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve()
     require(args.task.strip(), "task identity is required")
@@ -228,7 +229,7 @@ def allocate(args):
     receipt["allocation"] = "owned"
     atomic_json(path, receipt)
     return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target), "scratch": str(scratch),
-            "reconciled": [] if local else reconcile(common, path, work)}
+            "reconciled": [] if local else reconcile(common, path, work, exclude_receipts=exclude_receipts)}
 
 
 def exact_commit(receipt, value, flag):
@@ -243,7 +244,7 @@ def local_baseline(receipt, args):
     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(predecessor.get("acceptance") and predecessor["acceptance"].get("verdict") != "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"]}
@@ -341,7 +342,7 @@ def accept(args):
     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),
+        return {"status": "FAILED" if receipt["acceptance"].get("verdict") == "FAILED" else "ACCEPTED", "receipt": str(path),
                 "source_sha": receipt["source_sha"], "recovery_ref": receipt["recovery_ref"]}
 
 
@@ -357,7 +358,7 @@ def attach(args):
             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),
+                    and (receipt["acceptance"].get("verdict") == "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")
@@ -439,6 +440,17 @@ def removable(receipt, work):
     stopped_writers(work)
 
 
+def linux_process_status(process):
+    # One opened status file is bound to that process, not a reused PID.
+    # A zombie leader can still have living sibling threads.
+    try:
+        return dict(line.split(":", 1) for line in (process / "status").read_text(encoding="utf-8").splitlines() if ":" in line)
+    except (FileNotFoundError, ProcessLookupError):
+        raise
+    except (OSError, UnicodeError) as exc:
+        raise WritersUnobservable("unknown process status; retain tree until writer cessation can be established") from exc
+
+
 def stopped_writers(work):
     outside(work)
     # The owner assertion covers its actual children; an OS observation catches
@@ -463,15 +475,22 @@ def stopped_writers(work):
                     try:
                         target = Path(os.readlink(link))
                     except FileNotFoundError:
-                        if link == process / "cwd":
-                            break
+                        if link == process / "cwd" and linux_process_status(process).get("Threads", "").strip() != "1":
+                            raise WritersUnobservable("unknown process thread access; retain tree until writer cessation can be established")
                         continue
                     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:
+            except (FileNotFoundError, ProcessLookupError):
                 continue  # Process exited during observation.
             except PermissionError as exc:
-                raise WritersUnobservable("unknown process access; retain tree until writer cessation can be established") from exc
+                reason = "unknown process access; retain tree until writer cessation can be established"
+                try:
+                    status = linux_process_status(process)
+                except (FileNotFoundError, ProcessLookupError) as error:
+                    raise WritersUnobservable(reason) from error
+                if status.get("State", "").strip() == "Z (zombie)" and status.get("Threads", "").strip() == "1":
+                    continue
+                raise WritersUnobservable(reason) from exc
     else:
         raise WritersUnobservable("writer observation unsupported on this platform; retain workspace")
 
@@ -646,10 +665,10 @@ def completion_result(receipt, path, status):
             "scratch_cleanup": scratch, "workspace_cleanup": receipt.get("workspace_cleanup")}
 
 
-def reconcile(common, allocated, anchor):
+def reconcile(common, allocated, anchor, *, exclude_receipts=()):
     results = []
     for path in sorted((common / "devlyn-completion").glob("*/receipt.json")):
-        if path == allocated:
+        if path == allocated or path in exclude_receipts:
             continue
         try:
             receipt = read_json(path)
@@ -693,7 +712,7 @@ def complete(args):
             atomic_json(path, receipt)
         def result(status):
             return completion_result(receipt, path, status)
-        if receipt.get("product") == "FAILED":
+        if (receipt.get("acceptance") or {}).get("verdict") == "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']}; "
@@ -1134,6 +1153,119 @@ class CompletionTests(unittest.TestCase):
             with self.assertRaisesRegex(WriterActive, "active process " + process.name):
                 stopped_writers(self.work)
 
+    def linux_unobservable_process(self, status, *, missing_cwd=False, active_fd=False):
+        from unittest.mock import patch
+        process = Path("/proc") / str(os.getpid() + 1)
+        original_entries, original_text, original_link = Path.iterdir, Path.read_text, os.readlink
+        def entries(path):
+            if path == Path("/proc"):
+                return iter([process])
+            if path == process / "fd":
+                if missing_cwd:
+                    return iter([process / "fd/3"] if active_fd else [])
+                raise PermissionError(path)
+            return original_entries(path)
+        def text(path, *args, **kwargs):
+            if path == process / "status":
+                if isinstance(status, Exception):
+                    raise status
+                return status
+            return original_text(path, *args, **kwargs)
+        def link(path, *args, **kwargs):
+            if path == process / "cwd":
+                raise FileNotFoundError(path)
+            if path == process / "fd/3":
+                return str(self.work / "product")
+            return original_link(path, *args, **kwargs)
+        with patch.object(sys, "platform", "linux"), patch.object(Path, "iterdir", entries), patch.object(Path, "read_text", text), patch.object(os, "readlink", link):
+            stopped_writers(self.work)
+
+    def test_linux_writer_scan_accepts_confirmed_single_thread_zombie(self):
+        self.linux_unobservable_process("Name:\tgit\nState:\tZ (zombie)\nThreads:\t1\n")
+
+    def test_linux_writer_scan_retains_denied_live_or_threaded_process(self):
+        # The leader may be Z after pthread_exit while sibling threads write.
+        for state, threads in (("Z (zombie)", "2"), ("R (running)", "1"), ("S (sleeping)", "1"), ("T (stopped)", "1")):
+            with self.subTest(state=state, threads=threads):
+                with self.assertRaises(WritersUnobservable):
+                    self.linux_unobservable_process(f"State:\t{state}\nThreads:\t{threads}\n")
+
+    def test_linux_writer_scan_retains_unknown_zombie_status(self):
+        for status in ("", "State:\tZ (zombie)\n", "Threads:\t1\n", "State:\tZ (zombie)\nThreads:\tunknown\n",
+                       PermissionError("status denied"), FileNotFoundError("exited before terminal evidence")):
+            with self.subTest(status=str(status)):
+                with self.assertRaises(WritersUnobservable):
+                    self.linux_unobservable_process(status)
+
+    def test_linux_missing_cwd_checks_threads_and_remaining_fds(self):
+        self.linux_unobservable_process("State:\tZ (zombie)\nThreads:\t1\n", missing_cwd=True)
+        self.linux_unobservable_process(FileNotFoundError("process exited"), missing_cwd=True)
+        self.linux_unobservable_process("State:\tS (sleeping)\nThreads:\t1\n", missing_cwd=True)
+        with self.assertRaises(WriterActive):
+            self.linux_unobservable_process("State:\tS (sleeping)\nThreads:\t1\n", missing_cwd=True, active_fd=True)
+        for status in ("State:\tZ (zombie)\nThreads:\t2\n", "State:\tS (sleeping)\nThreads:\t2\n", ""):
+            with self.subTest(status=status):
+                with self.assertRaises(WritersUnobservable):
+                    self.linux_unobservable_process(status, missing_cwd=True)
+
+    @unittest.skipUnless(sys.platform.startswith("linux"), "requires Linux proc and unreaped child")
+    def test_linux_real_zombie_allows_only_attested_scratch_cleanup(self):
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / "artifact").write_text("rebuildable")
+        child = os.fork()
+        if child == 0:
+            os._exit(0)
+        try:
+            os.waitid(os.P_PID, child, os.WEXITED | os.WNOWAIT)
+            state = (Path("/proc") / str(child) / "status").read_text()
+            self.assertRegex(state, r"State:\s+Z \(zombie\)")
+            self.assertRegex(state, r"Threads:\s+1\n")
+            result, _ = self.cli("clean-scratch", "--receipt", self.receipt, success=False)
+            self.assertIn("--writers-stopped", result["reason"])
+            self.assertTrue((scratch / "artifact").exists())
+            result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+            self.assertEqual(result["status"], "SCRATCH_CLEAN")
+            self.assertFalse(any(scratch.iterdir()))
+        finally:
+            os.waitpid(child, 0)
+
+    @unittest.skipUnless(sys.platform.startswith("linux"), "requires Linux pthread leader state")
+    def test_linux_real_zombie_leader_retains_live_sibling_writer(self):
+        import time
+        scratch = Path(self.allocate()["scratch"])
+        heartbeat = scratch / "heartbeat"
+        code = """import ctypes, pathlib, sys, threading, time
+path = pathlib.Path(sys.argv[1])
+def worker():
+    with path.open('w') as stream:
+        while True:
+            stream.write('x'); stream.flush(); time.sleep(.01)
+threading.Thread(target=worker).start()
+ctypes.CDLL(None).pthread_exit(None)
+"""
+        child = subprocess.Popen([sys.executable, "-c", code, str(heartbeat)], cwd=self.root)
+        try:
+            deadline = time.monotonic() + 5
+            while time.monotonic() < deadline:
+                status = (Path("/proc") / str(child.pid) / "status").read_text()
+                if re.search(r"State:\s+Z \(zombie\)", status) and heartbeat.exists():
+                    break
+                time.sleep(.01)
+            else:
+                self.fail("threaded zombie fixture did not become ready")
+            self.assertRegex(status, r"Threads:\s+2\n")
+            before = heartbeat.stat().st_size
+            result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+            self.assertIn("unknown process", result["reason"])
+            self.assertTrue(heartbeat.exists())
+            deadline = time.monotonic() + 5
+            while heartbeat.stat().st_size <= before and time.monotonic() < deadline:
+                time.sleep(.01)
+            self.assertGreater(heartbeat.stat().st_size, before)
+        finally:
+            child.kill()
+            child.wait(timeout=5)
+
     @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"])

package/config/skills/_shared/task-completion.md

@@ -15,6 +15,11 @@ just-edit instructions skip delivery. Existing session-wide restrictions remain
 in force until changed. Read-only work, unchanged work and incidental generated
 files do not trigger delivery. An ideate drain delivers every task.
 
+When delivery is implicit and no GitHub origin is configured, use the existing
+local-only route and report `LOCAL_ONLY`, the commit and why no PR/merge occurred.
+An explicit PR/merge request remains blocked. Authentication, network and
+configuration failures are not grounds for this fallback.
+
 ## Concurrent writers
 
 When other sessions or agents are known to write this checkout (the user says
@@ -58,11 +63,6 @@ isolation without publication, use `--local-base` with the exact current HEAD
 and omit `--repository`/`--remote`. Nothing is fetched or pushed; complete with
 `--local-only` only when committing is allowed.
 
-When delivery is implicit and no GitHub origin is configured, use the existing
-local-only route and report `LOCAL_ONLY`, the commit and why no PR/merge occurred.
-An explicit PR/merge request remains blocked. Authentication, network and
-configuration failures are not grounds for this fallback.
-
 After local completion or confirmed PR merge, reconcile the original checkout
 only when its branch and changes remain understood and can be preserved.
 After remote delivery, fetch first. If the branch can fast-forward to the

package/config/skills/devlyn-ideate/SKILL.md

@@ -122,7 +122,7 @@ python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" drain --repo . [--local-only] -- <e
 A drain can run for hours. Do not end the turn until it exits: run it in the foreground with the longest allowed timeout, or in the background and await its completion notice, because a headless host kills background tasks at its final response.
 
 - `WAITING` on legacy rows: plan and materialize each under the autonomous policy, then drain again; a row whose planning stops on material ambiguity stays pending and its question is reported.
-- `WAITING` on anything else, or `BLOCKED`: report the reason and resume commands; never edit receipts, refs or queue rows to get past them.
+- Other `WAITING`: report each task’s reason and recovery command. Task-local failures leave dependents and barrier-held siblings waiting while independent work continues; the next drain retries eligible work once. An interrupted executor is observed once per drain and cannot be adopted or respawned until it stops. `BLOCKED` means authoritative queue reconstruction or preflight failed, including a held drain lock. Never edit receipts, refs or queue rows to get past either result.
 - An interrupted drain is resumed by running `drain` again; accepted work is never replayed, and a failed task is never rerun: plan its work again as a new loop.
 
-Report each task's product result, delivery status, PR URL, resume command, assumptions and unresolved questions, plus whole-loop acceptance, the package's `## Decisions and assumptions`, the drain report paths and its exact `Bring into` command; leave running it to the user. Report any `cleanup` entry too: a package copy left in the checkout stops that command until it is removed.
+Report each task's product result, delivery status, PR URL, resume command, assumptions and unresolved questions, plus whole-loop acceptance, the package's `## Decisions and assumptions`, the drain report paths and its exact `Bring into` command; leave running it to the user. Report every `cleanup` diagnostic, including unavailable reports and retained parents; completed products keep their verdict. A package copy left in the checkout can prevent the `Bring into` command until it is removed.

package/config/skills/devlyn-ideate/references/loop.md

@@ -12,7 +12,7 @@ python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" drain --repo . [--local-only] [--wo
 Both print one JSON object; exit 1 is `BLOCKED` with a `reason`.
 
 - `status` takes `queue.lock` in the repository's Git directory and finishes `add`'s cleanup (step 1); it reports reconciled counts (`pending`, `active`, `accepted`, `failed`, `blocked`, `legacy_pending`), the `next` task, `blockers`, deliveries still pending with their resume (drain again until the terminal commit is attached, then `task-complete.py complete --receipt <receipt>`), and under `cleanup` the package copies `add` kept or could not remove.
-- `drain` ends `DRAINED` (no runnable task remains; open deliveries show per task), `WAITING` (a task waits with its reason, or legacy rows need planning) or `BLOCKED` (conflict, invalid input or a recovery blocker). Progress lines `devlyn-loop: <task>: <event>` go to stderr.
+- `drain` ends `DRAINED` (no runnable task remains; open deliveries show per task), `WAITING` (a task waits with its reason, or legacy rows need planning) or `BLOCKED` (unreadable or ambiguous authoritative queue, invalid invocation, preflight refusal or held drain lock). Progress lines `devlyn-loop: <task>: <event>` go to stderr.
 - `--local-only` (alias `--no-push`) keeps the loop local. A manifest `delivery: local-only` and any earlier local receipt of the loop keep that restriction for later drains. A local loop needs no remote; nothing is fetched or pushed. An `auto`/`pr` loop none of whose tasks has a pushed PR runs as a local loop from its capture and the branch it was added on. Once one has, that PR is never rewritten to local and the loop is never run locally: its tasks wait, naming the PR, while other work continues.
 - Worktrees default to `<repo parent>/<repo name>.devlyn/<loop-id>/<task-id>`.
 
@@ -22,13 +22,13 @@ The host supplies the executor and maps its configured engine to the argv; the l
 
 ## Steps
 
-1. **Reconcile.** First finish `add`'s cleanup of package copies ([package-format.md](package-format.md) Commands). Then read the queue view: the legacy rows, each replaced row as its loop's rows, then each loop's rows, from its capture or, without a record, from the checkout's tracked queue file ([package-format.md](package-format.md) Queue rows); every `<common Gitdir>/devlyn-completion/*/receipt.json` and their recovery refs. A row's identity, its receipt's branch `devlyn/<loop-id>/<task-id>`, the recovery ref (equal to the receipt's `publish_sha`, or to its validated terminal commit while that attachment is unfinished), the terminal commit's mark and, while active, the committed contract digests must agree. A receipt's terminal result supplements a `[ ]` row. Two receipts for one task or a terminal row contradicting its receipt stop selection with the conflict named; an unfinished allocation makes its task wait (step 10). A captured package never changes; for a loop without a record, an active task whose contract or expected acceptance changed in the checkout, also when that text is now missing or invalid, becomes `[F] inputs-changed` without executing again, its workspace retained, other work continuing while the revision is planned as a new task, and a pending task whose package text fails validation waits with that error, as do its dependents. Unsettled receipts (active, terminal commit unattached, or delivery not final) resume before any new allocation.
+1. **Reconcile.** First finish `add`'s cleanup of package copies ([package-format.md](package-format.md) Commands). Then read the queue view: the legacy rows, each replaced row as its loop's rows, then each loop's rows, from its capture or, without a record, from the checkout's tracked queue file ([package-format.md](package-format.md) Queue rows); every `<common Gitdir>/devlyn-completion/*/receipt.json` and their recovery refs. A row's identity, its receipt's branch `devlyn/<loop-id>/<task-id>`, the recovery ref (equal to the receipt's `publish_sha`, or to its validated terminal commit while that attachment is unfinished), the terminal commit's mark and, while active, the committed contract digests must agree. A receipt's terminal result supplements a `[ ]` row. Receipt, recovery-ref and packet conflicts invalidate the implicated tasks with an inspection/recovery reason; a missing queued prerequisite invalidates its dependent. Invalid evidence proves neither acceptance nor a frontier. A possible writer or package carrier retains its loop’s safety barrier while independent loops continue. An occupied receipt directory without a receipt waits for verified interrupted-allocation recovery; nothing is fabricated, rewritten or deleted. An unfinished allocation makes its task wait (step 10). Unreadable authoritative queue bytes, duplicate identities, missing/malformed queue files and invalid add records block the whole drain. A captured package never changes; for a loop without a record, an active task whose contract or expected acceptance changed in the checkout, also when that text is now missing or invalid, becomes `[F] inputs-changed` without executing again, its workspace retained, other work continuing while the revision is planned as a new task, and a pending task whose package text fails validation waits with that error, as do its dependents. Unsettled receipts (active, terminal commit unattached, or delivery not final) resume before any new allocation.
 2. **Select** the earliest pending row whose prerequisites are accepted with a receipt in every mode (a hand-written `[x]` never counts) and, for `auto`/`pr`, delivered (merged). A failed or blocked prerequisite makes its dependent `[F] blocked-prerequisite:<id>` without invoking the executor; that derived mark is proven by the prerequisite's receipt and travels into later checkouts and the report. A prerequisite awaiting delivery leaves its dependent pending while independent work continues; so does an `auto`/`pr` carrier in flight (step 3), or a local loop's active task (a local loop runs one task at a time), for every other task of its loop. Legacy rows wait for `add --materialize`.
-3. **Allocate** a new owned worktree on the absent branch `devlyn/<loop-id>/<task-id>` with `task-complete.py allocate`. First, the commit the task starts from must ignore `.devlyn/` (a committed `.gitignore` entry there, or `<common Gitdir>/info/exclude`), or nothing is allocated and the drain blocks naming the fix. It must also hold this checkout's `CLAUDE.md` and `AGENTS.md` (each identical, or both absent), so the task runs under the installed instructions, and, where it holds the loop's queue file, every captured package file unchanged, so the task binds its captured contract; otherwise the task waits, naming the fix, while independent work continues.
+3. **Allocate** a new owned worktree on the absent branch `devlyn/<loop-id>/<task-id>` with `task-complete.py allocate`. First, the commit the task starts from must ignore `.devlyn/` (a committed `.gitignore` entry there, or `<common Gitdir>/info/exclude`), or nothing is allocated and the task waits naming the fix while independent work continues. It must also hold this checkout's `CLAUDE.md` and `AGENTS.md` (each identical, or both absent), so the task runs under the installed instructions, and, where it holds the loop's queue file, every captured package file unchanged, so the task binds its captured contract; otherwise the task waits, naming the fix, while independent work continues.
    - Local: the first task uses `--local-base <HEAD of the branch the loop was added on>`, the add record's branch, never whichever branch is checked out; that HEAD must descend from the manifest `base_sha`, or the task waits naming it. Instructions committed there before this first allocation are therefore used. Its receipt keeps that start, and a later task with no accepted predecessor reuses it, also after the first task failed; a fixed start is never recalculated. Later tasks use `--from-receipt <latest accepted receipt of the loop>`, which starts from that receipt's exact `source_sha`, never its terminal commit, current HEAD or workspace. Every prerequisite's accepted source must be an ancestor of that frontier; divergent dependencies need a planned integration task, because the driver never merges. A failure leaves the frontier unchanged.
-   - `auto`/`pr`: `--start` the refreshed remote base, never an anchor-local commit, so no unpushed anchor commit reaches a task PR; push whatever the plan depends on. A task allocated while that base lacks `docs/specs/<loop-id>/` is the loop's carrier; a carrier that fails is never published, and the next task allocated becomes the carrier. The start must contain each prerequisite's merge commit, checked before allocation and again before every execution or resume. A squash merge needs no original-source ancestry.
+   - `auto`/`pr`: `--start` the refreshed remote base, never an anchor-local commit, so no unpushed anchor commit reaches a task PR; push whatever the plan depends on. A task allocated while that base lacks `docs/specs/<loop-id>/` is the loop's carrier; a carrier that fails is never published, and the next task allocated becomes the carrier. The start must contain each prerequisite's merge commit, checked before allocation and again before every execution or resume. A squash merge needs no original-source ancestry. A refresh failure waits for restored remote access or the base ref. A missing merge before allocation waits for that merge to be restored on the remote base; an allocated baseline is immutable and needs a new loop or verified recovery of a never-executed allocation.
 4. **Commit scoped inputs** on the owned branch before any executor write, only what the allocation base lacks. A base without `docs/specs/<loop-id>/` gets the package directory from the capture with the loop's queue file, its settled rows keeping their marks (receipt-proven `[x]` and `[F]`, prerequisite-blocked `[F]`): a local loop's first task, or an `auto`/`pr` carrier, whose PR lands the package before tasks diverge. Otherwise a local task commits the base's queue file with the loop's receipt-proven terminal rows (typically a predecessor's `[x]`), every other byte unchanged, and an `auto`/`pr` task commits nothing, so its PR changes only its own row and its product. A base that already carries them gets no inputs commit; unrelated product commits stay out.
-5. **Exchange one packet.** Write `<receipt dir>/packet.json`, then run the executor. An executor that exits without writing its submission leaves its task active, waiting with the exit code and `executor.stderr`, and the next drain runs it again; one that cannot start blocks the drain.
+5. **Exchange one packet.** Write `<receipt dir>/packet.json`, then run the executor. An executor that exits without writing its submission leaves its task active, waiting with the exit code and `executor.stderr`, and the next drain runs it again; one that cannot start keeps its allocation, packet and durable start/not-started log, waits for executable, permissions or workspace repair, and retries on the next drain.
 6. **Derive acceptance** with `acceptance.py accept`. It binds the committed contract to the packet digests; requires the candidate to be the owned branch head with HEAD checked out on that branch, to descend from the inputs, to leave the package (its queue file included) and `docs/specs/queue.md` untouched and to have a clean worktree; executes each declared command on that source, recording raw stdout/stderr and exit, timeout or spawn outcomes (a runner result is reused only when it is wholly clean — no reasons, so no failed check and no source change during its checks — for the same source and contract digests, with unchanged streams); evaluates the file and diff guards against the inputs; confirms the source is unchanged; checks review records; and writes `.devlyn/loop/acceptance.json`. Missing checks, missing review coverage and open binding findings cannot produce `[x]`, and acceptance weakening is not repair. This establishes command outcomes and evidence completeness, not a reviewer's semantic judgment; deliberate evidence forgery is outside the trust model.
 7. **Bind before terminal metadata.** `task-complete.py accept --receipt <receipt> --acceptance <worktree>/.devlyn/loop/acceptance.json` takes evidence custody and points the recovery ref at the source. Failed results are bound the same way; they never become a frontier or a publishable product.
 8. **Commit the terminal transition** under the queue lock: one commit whose sole parent is the bound source and whose only change is this task's row in `docs/specs/<loop-id>/queue.md` (`[x]`, or `[F] — <first reason> (receipt <id>)`), validated as the only legal transition. Then `task-complete.py attach --receipt <receipt> --commit <terminal> --file docs/specs/<loop-id>/queue.md` records it separately from the source and moves the recovery ref to it.
@@ -38,17 +38,21 @@ The host supplies the executor and maps its configured engine to the argv; the l
     | Interrupted | Resume |
     |---|---|
     | During allocation | A receipt without `allocation: owned` is never adopted: its task waits, naming the recovery (remove its worktree and branch if present, delete the receipt directory, drain again), while independent work continues. |
-    | Inputs commit | A branch head equal to the expected inputs tree is adopted; anything else blocks. |
-    | During execution | Each attempt's start is recorded before its spawn and its exit after it. A start without an exit waits until task-complete observes no process using the worktree, then adopts the submission that executor wrote or runs the executor again; where writers cannot be observed (native Windows) the task becomes `[F] interrupted-unobservable` with its workspace retained, its dependents become prerequisite-blocked and independent work continues. Exactly-once execution is not promised. |
+    | Inputs commit | A branch head equal to the expected inputs tree is adopted; anything else leaves the task waiting for inspection, preserving the unexpected commits. |
+    | During execution | Each attempt's start is recorded before its spawn and its exit after it. A start without an exit gets one writer observation per drain. A live writer leaves the task waiting while independent work continues; a later drain adopts the submission or runs the executor again only after cessation is established; where writers cannot be observed (native Windows) the task becomes `[F] interrupted-unobservable` with its workspace retained, its dependents become prerequisite-blocked and independent work continues. Exactly-once execution is not promised. |
     | During checks | Acceptance reruns; incomplete evidence stays unreferenced. |
     | During custody binding | Acceptance reruns while the receipt is unbound. Any unbound custody copy, complete or partial, is set aside in a unique hidden sibling before fresh custody is published; it and orphan staging copies stay retained and unreferenced. A bound receipt resumes its original result with strict evidence validation. |
     | Accepted, before terminal commit | Only the missing transition is created. |
     | Terminal committed, before attachment | The commit is validated and attached, also when attachment already moved the recovery ref; nothing reruns. |
     | Terminal committed, before delivery | Only the missing delivery effects run. |
-    | After delivery, before cleanup | Owned cleanup resumes; the product verdict is unchanged. |
+    | After delivery, before cleanup | Owned cleanup resumes; the product verdict is unchanged. After confirmed worktree removal, drain prunes empty parents strictly below its matching worktree root, preserving that root, nonempty directories and symlinks. Later drains revisit completed receipts to finish interrupted parent pruning without execution. |
+
+Expected task-local operational failures leave the selected task waiting with `<phase> blocked: <detail>` and recovery guidance. It is attempted at most once per drain; dependents, local siblings behind an active task, and siblings behind an undelivered package carrier wait too. Independent work continues and the drain ends `WAITING`. Inputs, acceptance, custody and terminal-attachment failures resume only their missing effects; bound results and accepted work never replay. The controller boundary contains `LoopError` and `OSError`; other programming errors propagate there. The inherited task-complete wrapper and delivery-repository lookup also contain helper `TypeError`, `KeyError` and `ValueError`, converting them to task waits.
 
 11. **Report** to `<common Gitdir>/devlyn-loops/<loop-id>/drain-report.md` after every drain: per task the product result and reason, receipt, evidence custody and recovery ref, allocation base, accepted (or unaccepted) source, terminal commit, delivery status, PR URL and resume command, assumptions and unresolved questions, the retained worktree and branch, and workspace and scratch cleanup. Include the package's decisions and assumptions once, excluding the manifest and separately from executor assumptions; read the captured package when an add record exists, otherwise use the checkout, and report an unreadable package explicitly. Whole-loop acceptance is reported separately over the manifest's complete task set: every task needs receipt-backed acceptance, including the integration task's assembled-product check on the final frontier; a manifest task missing from the queue is reported as not yet run. `Bring into` names the command that brings the accepted frontier into the branch the loop was added on. For a local loop it is `git merge --ff <final frontier branch>` on that branch, which fast-forwards when it can and merges otherwise, so the commands of several local loops apply in either order. For `auto`/`pr`, once the frontier is delivered, it is `git merge --ff origin/<base>` on `<base>`: the anchor holds no loop commit or copy, so it fast-forwards after merge, squash and rebase delivery alike unless that branch has commits of its own, and merges then.
 
+Package cleanup, parent pruning and report failures appear as diagnostics under `cleanup`, with retained paths and repair guidance; they do not change product acceptance or completed delivery. The next drain retries them.
+
 ## Executor exchange
 
 The packet (`<receipt dir>/packet.json`) carries everything a fresh executor needs: