devlyn-cli 4.3.27 → 4.3.29

package/config/skills/devlyn-ideate/scripts/queue.py

@@ -15,6 +15,7 @@ import datetime
 import errno
 import functools
 import hashlib
+import itertools
 import json
 import os
 from pathlib import Path
@@ -52,7 +53,7 @@ OBLIGATIONS = [
     "Work only in this worktree on its owned branch under the installed methodology; never edit the loop package or docs/specs/queue.md.",
     "Commit any source changes on the owned branch; when none are needed, use inputs_sha without creating an empty commit. Leave no uncommitted or untracked source and remove residue the change created.",
     "Run `runner` on the committed candidate; review records must bind engine, model, that source and both contract digests.",
-    "Write `submission` and exit; report a blocker instead of weakening acceptance.",
+    "Write `submission` as executor.md says and exit; never weaken acceptance.",
 ]
 
 
@@ -1220,8 +1221,8 @@ def ensure_packet(v, row, path, receipt):
         body = (f"Execute task packet {packet_path}. Work only in {worktree} on its owned branch.\n"
                 f"Read {binding['defaults']['path']} and apply it as defaults; explicit user and native owner/project instructions win, except a Devlyn managed block (devlyn:instructions markers), which these defaults replace.\n"
                 f"Set DEVLYN_SKILL_DIR={bound_skills / 'devlyn-ideate'} and DEVLYN_SHARED_DIR={bound_skills / '_shared'}.\n"
-                f"Follow Executor exchange and Review records in {bound_skills / 'devlyn-ideate/references/loop.md'}.\n"
-                f"Meet the packet obligations, run its runner and write {packet['submission']}. Never push, open a pull request or merge.\n")
+                f"Follow {bound_skills / 'devlyn-ideate/references/executor.md'}: meet the packet obligations and write "
+                f"{packet['submission']} as it says. Never push, open a pull request or merge.\n")
         acceptance()["atomic_write"](prompt, body.encode("utf-8"))
         packet["workerPrompt"] = harness_call("file_identity", prompt)
     write_json(packet_path, packet)
@@ -1243,7 +1244,9 @@ def ensure_submission(identity, packet_path, packet, executor):
 
     An attempt's start is recorded before the spawn and its exit after the wait, so a start without an exit may have
     left a live executor: drain observes once and waits if it is active. Only established cessation permits adoption
-    or another execution. Where writers cannot be observed the task fails as interrupted-unobservable."""
+    or another execution. Where writers cannot be observed the task fails as interrupted-unobservable. A submission
+    blocked only by infrastructure is retired once its writers are observed to have stopped, and the task waits to run
+    again; where they cannot be observed, it fails the task with its blocker."""
     harness_call("verify_packet", packet, packet_path, SKILLS)
     submission = Path(packet["submission"])
     worktree = Path(packet["worktree"])
@@ -1263,7 +1266,7 @@ def ensure_submission(identity, packet_path, packet, executor):
         except (helper["CompletionError"], OSError) as exc:
             raise LoopError(f"cannot establish that an interrupted execution stopped: {exc}; repair writer observation, then drain again") from exc
     if submission.exists():
-        return None
+        return retire_retryable(packet, submission)
     defaults = packet["methodology"].get("defaults") if packet.get("schema_version") == 2 else None
     if packet.get("harness") is None and defaults and not Path(defaults["path"]).is_file():
         # An installation's own copy moves with its updates; only its absence matters, and only before a spawn.
@@ -1301,8 +1304,33 @@ def ensure_submission(identity, packet_path, packet, executor):
         code = child.wait()
     record(log, f"exit {code} (pid {child.pid})")
     if not submission.exists():
-        raise Waiting(f"executor exited {code} without a submission (see {output / 'executor.stderr'}); the next drain runs it again")
-    return None
+        raise Waiting(f"executor exited {code} without a submission (see executor.stdout and executor.stderr in {output}); "
+                      "the next drain runs it again")
+    return retire_retryable(packet, submission)
+
+
+def retire_retryable(packet, submission):
+    """Adopt a stopped executor's submission, unless only infrastructure blocks it (a kind earlier instructions offered):
+    once its writers are observed to have stopped, that one is kept under a retired name, so no later drain adopts it,
+    and the task waits for the next drain. While a writer is active it waits in place."""
+    if acceptance()["infrastructure_causes"](packet, submission) is None:
+        return None
+    helper = shared("task-complete")
+    try:
+        helper["stopped_writers"](Path(packet["worktree"]))
+    except helper["WriterActive"] as exc:
+        raise Waiting(f"executor reported a cause a later run can clear, but a writer is still active: {exc}; wait for or "
+                      "stop the named writer (an editor or shell open in the task worktree counts), then drain again") from exc
+    except (helper["CompletionError"], OSError):
+        return None  # Unobservable: another run could start beside a live writer, so the blocker fails the task.
+    causes = acceptance()["infrastructure_causes"](packet, submission)  # As it stands now: a writer may have replaced it.
+    if causes is None:
+        return None
+    retired = next(path for number in itertools.count(1)
+                   if not (path := submission.with_name(f"submission.retired-{number}.json")).exists())
+    submission.rename(retired)
+    raise Waiting(f"executor reported a cause a later run can clear: {'; '.join(map(one_line, causes))} (see {retired}); "
+                  "the next drain runs it again")
 
 
 def terminal_queue(cwd, receipt, identity):
@@ -2148,7 +2176,7 @@ class QueueTests(unittest.TestCase):
         """The attempt's start is durable before the spawn, so a resumed drain observes writers first: it waits while
         an executor lives and adopts its submission, runs the executor once when none did, and fails the task where
         writers cannot be observed. Prediction (H2): that one run exits 0 without writing a submission, so the task waits,
-        naming the exit code and executor.stderr, and no submission exists. Before: the drain wrote a stand-in submission
+        naming the exit code and both output files, and no submission exists. Before: the drain wrote a stand-in submission
         with a blocked-infrastructure blocker, which made the task [F]."""
         from unittest import mock
         helper = shared("task-complete")
@@ -2197,10 +2225,11 @@ class QueueTests(unittest.TestCase):
         def unobservable(count):
             raise helper["WritersUnobservable"]("writer observation unsupported on this platform; retain workspace")
 
-        stderr = Path(packet["evidence_dir"]) / "executor.stderr"
+        output = Path(packet["evidence_dir"])
         for crash, observe, outcome in ((crash_after_spawn, survivor, (1, 3, None)),
                                         (crash_before_spawn, lambda count: None,
-                                         (1, 1, f"executor exited 0 without a submission (see {stderr}); the next drain runs it again")),
+                                         (1, 1, f"executor exited 0 without a submission (see executor.stdout and executor.stderr in "
+                                                f"{output}); the next drain runs it again")),
                                         (crash_before_spawn, unobservable, (0, 1, "interrupted-unobservable"))):
             with self.subTest(crash=crash.__name__, observe=getattr(observe, "__name__", "nothing")):
                 spawns.clear()
@@ -2221,6 +2250,25 @@ class QueueTests(unittest.TestCase):
                 if crash is crash_after_spawn:
                     self.assertEqual(read_json(Path(packet["submission"])), {"by": "executor"})
 
+    def test_a_submission_is_retired_only_as_it_stands_once_its_writers_stopped(self):
+        """C5 review 2. Prediction: a writer that replaces an infrastructure-only submission with one carrying a product
+        blocker and exits before the observation leaves that submission adopted (None) in place, so the task fails with
+        its blockers, and nothing is retired. Before: the reading from before the observation retired it and the task
+        ran again."""
+        from unittest import mock
+        submission = self.root / "submission.json"
+        infrastructure = {"kind": "blocked-infrastructure", "detail": "registry unreachable"}
+        product = {"kind": "failed", "detail": "notes format undecided"}
+
+        def write(*blockers):
+            submission.write_text(json.dumps({"schema_version": 1, "task": "l.t", "source_sha": "0" * 40, "blockers": blockers}),
+                                  encoding="utf-8")
+        write(infrastructure)
+        with mock.patch.dict(shared("task-complete"), stopped_writers=lambda worktree: write(infrastructure, product)):
+            self.assertIsNone(retire_retryable({"task": "l.t", "worktree": str(self.root)}, submission))
+        self.assertEqual((read_json(submission)["blockers"], [path.name for path in self.root.glob("submission*")]),
+                         ([infrastructure, product], ["submission.json"]))
+
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)

package/harness/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- devlyn:instructions:begin sha256=25ed8e19648642bab459f945a6608ea1d7fe217497c29840d49d3d65a6de1092 -->
+<!-- devlyn:instructions:begin sha256=f2206e5ed1c96a6c5fc368836bb041e8e77328048ca617f902ed6fb72dcb742d -->
 Project-specific instructions outside this managed block take precedence over these defaults.
 
 # Project Instructions
@@ -18,7 +18,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — zero CRITICAL, zero HIGH security/design findings on the shippable path. Any review is one pass in which every reviewer, including each one the user requires, reads the source the checks ran on; fix each finding or reject it with a reason, re-check the fixes and the invariants they touch, and repeat the full review only while a CRITICAL or HIGH finding remains.
 5. **Best practice** — idiomatic for the language and framework. Use standard primitives; do not hand-roll what the library already provides.
-6. **Optimized** — use efficient code and avoid unnecessary work without sacrificing correctness or the user's requirements.
+6. **Optimized** — efficient on the resource that matters (the user's time, tokens, attention, runtime) without weakening correctness or requirements. An extra check or process step must beat the simpler path.
 7. **Production ready** — error states are explicit and visible; behavior under failure is what the user expects, not silent corruption.
 
 Three discipline rules govern HOW the principles are applied:

package/harness/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- devlyn:instructions:begin sha256=25ed8e19648642bab459f945a6608ea1d7fe217497c29840d49d3d65a6de1092 -->
+<!-- devlyn:instructions:begin sha256=f2206e5ed1c96a6c5fc368836bb041e8e77328048ca617f902ed6fb72dcb742d -->
 Project-specific instructions outside this managed block take precedence over these defaults.
 
 # Project Instructions
@@ -18,7 +18,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — zero CRITICAL, zero HIGH security/design findings on the shippable path. Any review is one pass in which every reviewer, including each one the user requires, reads the source the checks ran on; fix each finding or reject it with a reason, re-check the fixes and the invariants they touch, and repeat the full review only while a CRITICAL or HIGH finding remains.
 5. **Best practice** — idiomatic for the language and framework. Use standard primitives; do not hand-roll what the library already provides.
-6. **Optimized** — use efficient code and avoid unnecessary work without sacrificing correctness or the user's requirements.
+6. **Optimized** — efficient on the resource that matters (the user's time, tokens, attention, runtime) without weakening correctness or requirements. An extra check or process step must beat the simpler path.
 7. **Production ready** — error states are explicit and visible; behavior under failure is what the user expects, not silent corruption.
 
 Three discipline rules govern HOW the principles are applied:

package/native/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn",
-  "version": "4.3.27",
+  "version": "4.3.29",
   "description": "Devlyn harness skills",
   "skills": "./skills/"
 }

package/native/claude/skills/_shared/engine-doctor.sh

@@ -29,7 +29,7 @@ check_binary() {
 
 check_adapter() {
   # $1 = target name
-  if [ -f "$ADAPTERS_DIR/$1.md" ]; then printf 'yes'; else printf 'no'; fi
+  if [ -f "$ADAPTERS_DIR/$1.adapter.md" ]; then printf 'yes'; else printf 'no'; fi
 }
 
 check_executor() {
@@ -47,7 +47,7 @@ for i in "${!TARGETS[@]}"; do
   kind="${KINDS[$i]}"
   binary="$(check_binary "${BINARIES[$i]}")"
   adapter="$(check_adapter "$target")"
-  executor="$(check_executor "$ADAPTERS_DIR/$target.md")"
+  executor="$(check_executor "$ADAPTERS_DIR/$target.adapter.md")"
 
   note='-'
   case "$kind" in

package/native/claude/skills/_shared/engine-preflight.md

@@ -4,7 +4,7 @@ Used by `/devlyn-ideate` and `/devlyn-engines`: one rule for which engine execut
 
 ## Selection
 
-The executor is the `executor` pin in `.devlyn/engines.json` at the checkout root (set with `/devlyn-engines executor <name>`), else the CLI the user opened. A linked worktree or subdirectory has no pin unless one is set there. Pi and Grok have no executor adapter, so a drain from them needs a claude, codex or omp pin. Keys earlier releases wrote for retired pipeline roles (`pair_judge_priority`, `roles`) stay as written and select nothing: a worker profile never becomes the executor.
+The executor is the `executor` pin in `.devlyn/engines.json` at the checkout root (set with `/devlyn-engines executor <name>`), else the CLI the user opened. A linked worktree or subdirectory has no pin unless one is set there. Only Claude and Codex can execute, so a drain from any other CLI needs a claude or codex pin. Keys earlier releases wrote for retired pipeline roles (`pair_judge_priority`, `roles`) stay as written and select nothing: a worker profile never becomes the executor.
 
 Before dispatching to the executor, run:
 
@@ -16,7 +16,7 @@ A pin is a promise. When the pinned engine's CLI is unavailable, the command exi
 
 ## Engines
 
-An engine is pinnable when `_shared/adapters/<name>.md` exists and does not declare `executor: no` under `## Role eligibility`. Adapters ship with devlyn-cli releases, and a reinstall replaces `_shared`. An adapter's `## Invocation` says how to start it. On native Windows, use native Node/npm and Python (`python3` on PATH), with Git for Windows Bash for the shipped shell wrapper.
+An engine is pinnable when `_shared/adapters/<name>.adapter.md` exists and does not declare `executor: no`. Adapters ship with devlyn-cli releases, and a reinstall replaces `_shared`. An adapter's `## Invocation` says how to start it. On native Windows, use native Node/npm and Python (`python3` on PATH), with Git for Windows Bash for the shipped shell wrapper.
 
 ## Reporting a blocked engine
 

package/native/claude/skills/_shared/managed-storage.md

@@ -0,0 +1,80 @@
+# Managed storage
+
+New allocation and warming modes come from enrollment state alone:
+
+| `~/.devlyn/storage-client.json` | recovery marker | unenroll journal | Mode |
+|---|---|---|---|
+| absent | absent | not read | standalone (never enrolled) |
+| valid | any | not read | managed; a fenced authority refuses |
+| invalid or unreadable | any | not read | refuse; repair registration |
+| absent | present | verified `retired: true` | standalone (unenrollment complete) |
+| absent | present | absent, unreadable or incomplete | refuse; Open Devlyn to repair its storage registration |
+
+An unfinished retirement takes precedence over enrollment; follow its
+operation-specific retained-helper resume to reconcile or cancel as named.
+The journal `storage-client-unenroll.json` is read no-follow for retirement
+recovery and the last two rows. Schema 1, canonical UUIDv7 operation, permanent `storage-client-fence.json`,
+matching operation/root/lock identities and Rust's archive ordering/path
+validation are required. If native root/lock identities or the home path changed,
+completed retirement permits standalone only when `storage`, `control`,
+`harness/state.json` and `storage-client.json` are all absent under the current
+lifecycle root (checked without following links). Live inventory requires repair.
+No repository-wide receipt scan selects mode. Other keys can allocate after
+completed unenrollment; a leftover managed key retains its own recovery command.
+
+Existing operations keep their managed identity. Receipts pin the control
+identity; current enrollment verifies the helper before allocation. Recovery uses
+the current verified `storage-client-recovery/pins.json`, including after uninstall
+or unenrollment, and requires its authority binding to match the receipt, except
+for a proven moved task: use its unflagged, operation-specific `recover-storage`
+resume to release it, retain its files, and archive its receipt under `moved/`. Missing
+or invalid pins retain resources and require repair; saved artifacts are never a
+fallback. Enrolled checkout preserves
+`managed_pending`/`managed_owned` and Rust's `storage-allocation.json` subreceipt.
+After an interrupted reply, use the returned `recover-storage` resume. Never
+delete managed receipts or replace an unfinished operation ID.
+
+Owner `recover-storage --receipt <receipt.json> --operation-id <saved ID>
+--for-removal` fences allocation and reconciles closure and the exact cache set.
+Never-published allocations are abandoned. Accepted LOCAL_ONLY, FAILED, and PRs
+observed CLOSED without merge share custody/recovery-ref verification and fenced
+removal, retaining task branches and a durable terminal delivery. Release writers
+with `complete --writers-stopped` first. A queue-produced FAILED checkout is
+advanced by `read-tree -m -u <source_sha> <publish_sha>` only when HEAD is at the
+attached publish commit and the index and worktree are exactly at source; other
+differences refuse as dirty.
+
+Removal-finished receipts with final COMPLETE, LOCAL_ONLY, FAILED or CLOSED
+delivery move under `devlyn-completion/retired/`, regardless of scratch status.
+Retirement moves scratch and its saved cleanup record with the audit and deletes
+nothing. `complete --writers-stopped` saves the writer release there and retries
+pending scratch, including an interrupted cleanup with no saved result; the next
+allocation retries completed deliveries with released writers. `clean-scratch`
+remains available there and never downgrades CLEAN.
+Saved managed `complete`, `recover-storage` and `clean-scratch` resumes carry an
+operation ID validated under the receipt lock. Without an ID, a locator selects
+its active receipt. An ID selects only that operation, including its verified
+retired receipt; a mismatched ID refuses. Retired paths also remain usable.
+A new allocation may reuse a retired key without disturbing its audit.
+
+Retained submodule repositories in the admin directory block removal even when
+the checkout is absent; preserve/publish their source and explicitly resolve
+them. Manual checkout removal is advised only after portable source checks and
+record preservation succeed; changed or new source requires retention. If native
+Windows or unobservable writers then require retention, stop all
+writers, remove the task checkout by hand, keep its branch and receipt, then run
+the returned owner-removal resume. The absent-tree path completes the fenced
+registration removal. Scratch cleanup requires positive allocation closure,
+without a cache-removal fence; actual checkout removal owns that fence, including
+empty cache sets. Missing helpers or uncertain closure retain resources with a
+repair/resume action. Compatible recovery artifacts and Rust's LaunchGate remain
+required while managed obligations exist.
+
+Managed allocations currently start cold; `build_dirs` retains each returned cache
+and publication lease ID. Managed warming is deferred. Standalone allocations keep
+the warming behavior in [task-completion.md](task-completion.md).
+
+For managed receipts, use the saved `clean-scratch` resume with `--operation-id <saved ID>`.
+
+New managed allocations use the recovery ref `refs/devlyn/completed/<id>.<operation>` so branch reuse
+preserves earlier recovery refs.

package/native/claude/skills/_shared/platform-support.py

@@ -327,7 +327,9 @@ if os.name == "nt":
             self.creating = False
             self.interrupted_signal = None
 
-        def start(self, argv, stdin):
+        def start(self, argv, stdin, **popen):
+            """Launch argv, a list or a command line passed verbatim, inside this job; `popen` passes cwd, env and
+            streams to the enclosed bootstrap, whose target inherits them."""
             self.handle = _kernel.CreateJobObjectW(None, None)
             limits = _ExtendedLimits()
             limits.BasicLimitInformation.LimitFlags = 0x2000  # KILL_ON_JOB_CLOSE; no breakaway.
@@ -346,13 +348,15 @@ if os.name == "nt":
                     os.set_handle_inheritable(handle, True)
                 startup = subprocess.STARTUPINFO()
                 startup.lpAttributeList = {"handle_list": inherited}
+                # A list travels element by element, a command line verbatim as one element; a mode word tells which.
                 command = [sys.executable, "-I", "-S", str(Path(__file__).resolve()), "--job-bootstrap",
-                           str(inherited[0]), str(inherited[2]), str(inherited[1]), *argv]
+                           str(inherited[0]), str(inherited[2]), str(inherited[1]),
+                           *(("line", argv) if isinstance(argv, str) else ("argv", *argv))]
                 # Retain the Popen object even if __init__ raises after native creation.
                 self.child = subprocess.Popen.__new__(subprocess.Popen)
                 self.creating = True
                 try:
-                    self.child.__init__(command, stdin=stdin, startupinfo=startup, close_fds=True)
+                    self.child.__init__(command, stdin=stdin, startupinfo=startup, close_fds=True, **popen)
                 finally:
                     self.creating = False
                 if self.interrupted_signal is not None:
@@ -424,6 +428,11 @@ if os.name == "nt":
 
     def _job_bootstrap(argv):
         job, allow, ready = map(int, argv[:3])
+        mode, command = argv[3], argv[4:]
+        if mode == "line":
+            command, = command
+        elif mode != "argv":
+            raise ValueError(f"unknown job target mode {mode!r}")
         with contextlib.ExitStack() as handles:
             allow_fd = msvcrt.open_osfhandle(allow, os.O_RDONLY | os.O_BINARY)
             handles.callback(os.close, allow_fd)
@@ -436,50 +445,77 @@ if os.name == "nt":
             os.write(ready_fd, b"R")
             if _read_control(allow_fd, 1) != b"G":
                 raise OSError("Windows job launch was not authorized")
-            with subprocess.Popen(argv[3:], stdin=sys.stdin.buffer, close_fds=True) as target:
+            with subprocess.Popen(command, stdin=sys.stdin.buffer, close_fds=True) as target:
                 os.write(ready_fd, target.pid.to_bytes(4, "little"))
                 return target.wait()
 
 
+def _signal_group(child, sig):
+    """Send `sig` to the child's process group; False once it has no member this process may signal. An exited leader
+    is reaped first: until then it still counts as a member."""
+    child.poll()
+    try:
+        os.killpg(child.pid, sig)
+    except ProcessLookupError:
+        return False
+    except PermissionError:  # EPERM: no member this process may signal; with the leader alive the run cannot be ended.
+        if child.poll() is None:
+            raise
+        return False
+    return True
+
+
 def terminate_tree(child, job=None):
     if job is not None:
         job.terminate()
         return
-    try:
-        os.killpg(child.pid, signal.SIGTERM)
-    except ProcessLookupError:
-        child.wait()
-        return
-    # Reap the leader and retain the grace period for its surviving descendants.
-    deadline = time.monotonic() + 5
-    try:
-        child.wait(timeout=5)
-    except subprocess.TimeoutExpired:
-        pass  # The leader also needs the final group KILL below.
-    time.sleep(max(0, deadline - time.monotonic()))
-    try:
-        os.killpg(child.pid, signal.SIGKILL)
-    except ProcessLookupError:
-        pass  # Every member already exited during the grace period.
-    child.wait()
+    # SIGTERM and up to 5 s for the group to leave, then SIGKILL and about 1 s more; what still answers then is dead but
+    # unreaped or may not be signalled, which cannot be told apart. A member this process cannot signal, or one that left
+    # the session, is not owned; acceptance.py's evidence is safe from it because no check process holds an evidence file.
+    for sig, seconds in ((signal.SIGTERM, 5), (signal.SIGKILL, 1)):
+        deadline = time.monotonic() + seconds
+        alive = _signal_group(child, sig)
+        while alive and time.monotonic() < deadline:
+            time.sleep(0.01)
+            alive = _signal_group(child, 0)
+        if not alive:
+            return
 
 
-def run_process(argv, stdin, seconds, *, heartbeat=0):
+def run_process(argv, stdin, seconds, *, heartbeat=0, on_timeout=124, **popen):
+    """Run argv as an owned tree (its own POSIX session or Windows job), ended whole however the run ends; `popen`
+    passes cwd, env and streams. Returns the exit status, or `on_timeout` once `seconds` pass. On Windows argv may be a
+    command line passed verbatim."""
     child = None
     job = _WindowsJob() if os.name == "nt" else None
     previous = {}
+    received = []  # Every handled signal; the first ends the run with 128 + it once the tree has ended.
+    deferring = False  # While set, a signal only waits: a POSIX child's creation and the teardown are not interrupted.
 
     def interrupted(signum, _frame):
+        received.append(signum)
         # CPython stores the native handle only after CreateProcess's finally block.
         if job is not None and job.creating:
             job.interrupted_signal = signum
-            return
-        raise SystemExit(128 + signum)
+        elif not deferring:
+            raise SystemExit(128 + signum)
 
     try:
-        for sig in (signal.SIGTERM, signal.SIGINT):
-            previous[sig] = signal.signal(sig, interrupted)
-        child = job.start(argv, stdin) if job is not None else subprocess.Popen(argv, stdin=stdin, start_new_session=True)
+        handled = [signal.SIGTERM, signal.SIGINT]
+        if os.name != "nt" and signal.getsignal(signal.SIGHUP) is not signal.SIG_IGN:
+            # A closed terminal hangs up the runner, not the child's own session; an inherited ignore (nohup) stays.
+            handled.append(signal.SIGHUP)
+        for sig in handled:
+            previous[sig] = signal.getsignal(sig)  # Saved first: a signal right after installation finds it to restore.
+            signal.signal(sig, interrupted)
+        if job is not None:
+            child = job.start(argv, stdin, **popen)
+        else:
+            deferring = True  # Raised inside Popen, a signal would leave the new session unowned.
+            child = subprocess.Popen(argv, stdin=stdin, start_new_session=True, **popen)
+            deferring = False
+            if received:
+                raise SystemExit(128 + received[0])
         started = time.monotonic()
         next_heartbeat = started + heartbeat
         if heartbeat:
@@ -492,17 +528,20 @@ def run_process(argv, stdin, seconds, *, heartbeat=0):
                 if seconds and now - started >= seconds:
                     if heartbeat:
                         print(f"[codex-monitored] timeout: elapsed={int(now-started)}s limit={seconds}s", file=sys.stderr, flush=True)
-                    return 124
+                    return on_timeout
                 if heartbeat and now >= next_heartbeat:
                     print(f"[codex-monitored] heartbeat: elapsed={int(now-started)}s", file=sys.stderr, flush=True)
                     next_heartbeat = now + heartbeat
     finally:
+        deferring = True  # Teardown runs to its end.
         try:
             if job is not None or child is not None:
                 terminate_tree(child, job)
         finally:
             for sig, handler in previous.items():
                 signal.signal(sig, handler)
+            if received:  # Whenever it came and whatever teardown raised, a signal ends the run.
+                raise SystemExit(128 + received[0])
 
 
 if __name__ == "__main__" and os.name == "nt":

package/native/claude/skills/_shared/role-config.py

@@ -56,13 +56,19 @@ def name(value, field):
     return value
 
 
+INELIGIBLE = re.compile(r"^executor: no\s*$", re.M)
+
+
+# Named `<engine>.adapter.md`: on a case-insensitive filesystem Claude Code loads `claude.md` as nested instructions.
 def adapter(engine, shared=SHARED):
     name(engine, "engine")
-    path = shared / "adapters" / f"{engine}.md"
+    path = shared / "adapters" / f"{engine}.adapter.md"
     if not path.is_file():
-        fail(f"no adapter for {engine}; valid: {', '.join(sorted(p.stem for p in (shared / 'adapters').glob('*.md')))}")
+        valid = sorted(p.name.removesuffix(".adapter.md") for p in path.parent.glob("*.adapter.md")
+                       if not INELIGIBLE.search(p.read_text(encoding="utf-8")))
+        fail(f"no adapter for {engine}; valid: {', '.join(valid)}")
     text = path.read_text(encoding="utf-8")
-    if re.search(r"^executor: no\s*$", text, re.M):
+    if INELIGIBLE.search(text):
         fail(f"{engine} is ineligible as executor")
     return text
 
@@ -178,15 +184,18 @@ def self_test():
         # Pins are validated before any byte changes.
         ineligible = work / "shared"
         (ineligible / "adapters").mkdir(parents=True)
-        (ineligible / "adapters/judge.md").write_text("## Role eligibility\n\nexecutor: no\n", encoding="utf-8")
-        (ineligible / "adapters/codex.md").write_text("# Codex adapter\n", encoding="utf-8")
+        (ineligible / "adapters/judge.adapter.md").write_text("## Role eligibility\n\nexecutor: no\n", encoding="utf-8")
+        (ineligible / "adapters/codex.adapter.md").write_text("# Codex adapter\n", encoding="utf-8")
         path.write_bytes(legacy)
-        for engine, shared, message in (("grok", SHARED, "no adapter for grok"), ("judge", ineligible, "ineligible as executor"),
+        # A refused name lists only the engines that can execute.
+        for engine, shared, message in (("grok", SHARED, "no adapter for grok; valid: claude, codex"),
+                                        ("grok", ineligible, "no adapter for grok; valid: codex"),
+                                        ("judge", ineligible, "ineligible as executor"),
                                         ("../codex", SHARED, "nonempty identifier")):
             try:
                 edit(work, engine, shared=shared)
             except ValueError as exc:
-                assert "BLOCKED:invalid-engine-config" in str(exc) and message in str(exc), exc
+                assert str(exc).startswith("BLOCKED:invalid-engine-config:") and str(exc).endswith(message), exc
             else:
                 raise AssertionError(f"{engine} was pinned")
             assert path.read_bytes() == legacy

package/native/claude/skills/_shared/runtime-principles.md

@@ -17,7 +17,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — zero CRITICAL, zero HIGH security/design findings on the shippable path. Any review is one pass in which every reviewer, including each one the user requires, reads the source the checks ran on; fix each finding or reject it with a reason, re-check the fixes and the invariants they touch, and repeat the full review only while a CRITICAL or HIGH finding remains.
 5. **Best practice** — idiomatic for the language and framework. Use standard primitives; do not hand-roll what the library already provides.
-6. **Optimized** — use efficient code and avoid unnecessary work without sacrificing correctness or the user's requirements.
+6. **Optimized** — efficient on the resource that matters (the user's time, tokens, attention, runtime) without weakening correctness or requirements. An extra check or process step must beat the simpler path.
 7. **Production ready** — error states are explicit and visible; behavior under failure is what the user expects, not silent corruption.
 
 Three discipline rules govern HOW the principles are applied:

package/native/claude/skills/_shared/storage-client.py

@@ -42,7 +42,6 @@ import uuid
 MAX_REQUEST = 128 * 1024
 MAX_REPLY = 4 * 1024 * 1024
 EXCHANGE_SECONDS = 15.0
-BUSY_SECONDS = 2.0
 MANAGED_PENDING = "managed_pending"
 MANAGED_OWNED = "managed_owned"
 MANAGED_STATES = frozenset({MANAGED_PENDING, MANAGED_OWNED})
@@ -726,7 +725,9 @@ class Client:
     def call(self, request):
         data = encode_request(request)  # Freeze validated bytes before retry.
         expected = REQUESTS[request["op"]][1]
-        busy_deadline, backoff = time.monotonic()+BUSY_SECONDS, 0.01
+        # Behind a busy worker, wait as long as one exchange may take, as devlynd's own clients
+        # do (EXCHANGE_BUDGET): one slow request must not fail the call.
+        busy_deadline, backoff = time.monotonic()+EXCHANGE_SECONDS, 0.01
         try:
             while True:
                 try:
@@ -1113,6 +1114,7 @@ def moved_operation(saved):
         pins = lifecycle_evidence(root, root / 'storage-client-recovery/pins.json', observed)
         if pins is None:
             return None  # No retained binding can establish a moved receipt.
+        require_known_pins(pins)
         validate(pins, {'schema': 'u32', 'enrollment': ENROLLMENT_SHAPE, 'runtime': ARTIFACT_SHAPE, 'node': 'str'}, exact=True)
         require(pins['schema'] == pins['enrollment']['schema'] == 1, 'unsupported recovery pins')
         if (all(saved.get(key) == pins['enrollment'][key] for key in ('control_directory', 'control_identity'))
@@ -1174,6 +1176,8 @@ def retirement_refusal(root=None):
         require(fence is not None, 'retirement fence missing')
         record = recovery_registration()
     except (StorageRefusal, OSError, ValueError, RuntimeError) as exc:
+        if isinstance(exc, StorageRefusal) and exc.code == 'storage_unsupported':
+            raise  # An update answers it; Devlyn can repair nothing a newer Devlyn wrote.
         detail = exc.diagnostic if isinstance(exc, StorageRefusal) else str(exc)
         repair = 'Open Devlyn to repair its storage registration'
         raise StorageRefusal('storage_unavailable', detail, phase='enrollment', message=repair, resume=repair) from exc
@@ -1188,6 +1192,22 @@ def retirement_refusal(root=None):
                          message='Finish this storage retirement; resume ' + resume + alternative, resume=resume)
 
 
+def require_known_pins(pins):
+    """Pins a newer Devlyn wrote refuse as unsupported, as the managed read's newer record does, never as pins to
+    repair: only that Devlyn may change them."""
+    enrollment = pins.get('enrollment') if type(pins) is dict else None
+    schemas = (pins.get('schema') if type(pins) is dict else None,
+               enrollment.get('schema') if type(enrollment) is dict else None)
+    require(not any(type(schema) is int and schema > 1 for schema in schemas),
+            'recovery pins from a newer Devlyn', 'storage_unsupported')
+
+
+def invalid_pins(exc):
+    detail = exc.diagnostic if isinstance(exc, StorageRefusal) else str(exc)
+    return StorageRefusal('storage_unavailable', f'recovery pins invalid: {detail}', phase='enrollment',
+                          message='Retain the workspace and receipt; repair Devlyn recovery pins and retry')
+
+
 def recovery_registration():
     """Current retained pins survive replacement of the app and unenrollment."""
     try:
@@ -1199,6 +1219,10 @@ def recovery_registration():
         require(info is not None and stat.S_ISDIR(info.st_mode), 'recovery pins directory missing/invalid')
         observed = [(marker, info)]
         pins = read_evidence_json(marker / 'pins.json', observed)
+    except (StorageRefusal, OSError, ValueError, RuntimeError) as exc:
+        raise invalid_pins(exc) from exc
+    require_known_pins(pins)
+    try:
         validate(pins, {'schema': 'u32', 'enrollment': ENROLLMENT_SHAPE,
                         'runtime': ARTIFACT_SHAPE, 'node': 'str'}, exact=True)
         record = pins['enrollment']
@@ -1216,9 +1240,7 @@ def recovery_registration():
             require(after is None if before is None else _same_file(before, after), f'recovery pins changed: {path}')
         return record
     except (StorageRefusal, OSError, ValueError, RuntimeError) as exc:
-        detail = exc.diagnostic if isinstance(exc, StorageRefusal) else str(exc)
-        raise StorageRefusal('storage_unavailable', f'recovery pins invalid: {detail}', phase='enrollment',
-                             message='Retain the workspace and receipt; repair Devlyn recovery pins and retry') from exc
+        raise invalid_pins(exc) from exc
 
 
 def windows_profile():
@@ -1480,7 +1502,9 @@ def queue_handoff(common, binding):
                             helper = runpy.run_path(str(Path(__file__).with_name('task-complete.py')))
                             text += ' resume ' + helper['receipt_resume']('recover-storage', receipt, saved)
                         holders.append(text)
-                except (StorageRefusal, OSError, ValueError, TypeError, AttributeError, KeyError):
+                except (StorageRefusal, OSError, ValueError, TypeError, AttributeError, KeyError) as exc:
+                    if isinstance(exc, StorageRefusal) and exc.code == 'storage_unsupported':
+                        return f'{receipt}: {exc}'  # Evidence a newer Devlyn wrote: update, never repair.
                     if adapter_marker:
                         holders.append(str(receipt))
                         continue
@@ -1491,7 +1515,7 @@ def queue_handoff(common, binding):
         return drain if managed else None
     return ('this queue waits for the tasks in progress here: ' + '; '.join(holders)
             + ". Finish each with this release, and follow any resume a refusal names; a moved task's resume releases it and keeps its files; "
-            + '`recover-storage --for-removal` removes one only when the owner says so (task-completion.md); '
+            + '`recover-storage --for-removal` removes one only when the owner says so (managed-storage.md); '
             + ('then start it with Drain in Devlyn' if managed else 'then run this again'))
 
 

package/native/claude/skills/_shared/task-complete.py

@@ -328,7 +328,7 @@ def storage_call(name, *args, adapter=False, receipt_path=None, resume=None, **k
         if resume:
             if resume not in message:
                 message += '; resume ' + resume
-        else:
+        elif exc.code != 'storage_unsupported':  # An update is that refusal's remedy, never a repair.
             message += '; repair Devlyn enrollment and retry'
         error = CompletionError(message)
         error.storage_error = exc.result(receipt=path, resume=resume)