devlyn-cli 4.3.27 → 4.3.29

package/config/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/config/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/config/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/config/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/config/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)

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

@@ -96,75 +96,7 @@ can an interrupted standalone receipt that never reached `allocation: owned`:
 remove its worktree and branch if present, delete its receipt directory, then allocate again.
 Unreceipted tasks remain owner-managed.
 
-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.
+Work is standalone when `~/.devlyn/storage-client.json` and its recovery marker `~/.devlyn/storage-client-recovery` are both absent and the receipt in hand is not a managed one; otherwise read [managed-storage.md](managed-storage.md) first.
 
 Copy attributable task edits into the allocated worktree as a patch, never a
 stash. Establish attribution from the pre-edit contents and starting Git state,
@@ -183,10 +115,6 @@ require the affected checks again.
 Keep the original edits through pending or failed delivery; only reconciliation
 removes them. Preserve all other work and report anything left behind.
 
-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 below.
-
 Build in the task worktree's own default build directory, never in one
 another checkout builds in, even one build at a time: tools such as Cargo take
 one checkout's outputs as fresh for the other. When the shared repository-local
@@ -216,7 +144,6 @@ release build caches when parking or after a failed run, use:
 ```sh
 python3 "$DEVLYN_SHARED_DIR/task-complete.py" clean-scratch \
   --receipt '<returned receipt.json>' --writers-stopped
-# For managed receipts, use the saved resume with --operation-id <saved ID>.
 ```
 
 This empties only the prospectively owned scratch, preserves its directory
@@ -321,8 +248,7 @@ the next allocation or resume after the restart.
 On native Windows, locking and file durability are supported, but the helper cannot prove writer cessation and reports `writer observation unsupported on this platform; retain workspace`. Even `--writers-stopped` cannot authorize deletion without that observation: retain the workspace, its task refs and external receipt/custody, report delivery separately, and preserve the receipt-based resume command. A merged or on-base delivery therefore reports `CLEANUP_PENDING` (delivery `COMPLETE`) with `workspace_cleanup` naming the reason and resume. Do not kill unknown processes or force worktree removal to make completion pass.
 
 The receipt directory holds byte-verified `custody/`, `manifest.json` and a guarded
-`refs/devlyn/completed/<id>` recovery ref (new managed allocations use
-`<id>.<operation>` so branch reuse preserves earlier recovery refs). Check evidence is copied there
+`refs/devlyn/completed/<id>` recovery ref. Check evidence is copied there
 before publication; removal rechecks it, the recovery ref and the merge or accepted commit on base.
 Ignored build output and other ignored files are disposable under native
 non-force worktree removal. The tree's `.devlyn/` files are byte/mode-verified

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

@@ -56,7 +56,7 @@ Verify DEVLYN_SHARED_DIR/role-config.py and DEVLYN_SHARED_DIR/engine-doctor.sh b
 
 ## Subcommands
 
-- `executor <name>` — run the status command with `--set-executor <name>`. It refuses a name with no `_shared/adapters/<name>.md`, or whose adapter declares `executor: no`, and lists the valid names. An engine whose CLI is not available is still pinned, with a warning: pins are promises, and dispatch stops with `BLOCKED:<name>-unavailable` until it is installed.
+- `executor <name>` — run the status command with `--set-executor <name>`. It refuses a name with no `_shared/adapters/<name>.adapter.md`, or whose adapter declares `executor: no`, and lists the valid names. An engine whose CLI is unavailable is still pinned, with a warning: pins are promises, and dispatch stops with `BLOCKED:<name>-unavailable` until installed.
 - `clear` — run the status command with `--clear`: it removes the executor pin and the inactive keys, preserves unrelated keys, and deletes an empty file.
 - `pair` and `role` were removed with the retired pipeline roles: say so and change nothing.
 

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

@@ -106,7 +106,7 @@ For read-only consumers, `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" inspect -
 
 `status`, `add` and `drain` write the repository's Git directory, and auto/pr delivery needs network access, so a sandboxed host runs them with escalation or full access.
 
-Follow [loop.md](references/loop.md). The executor is the configured route, the `.devlyn/engines.json` `executor` pin or else this CLI, checked per `_shared/engine-preflight.md`. Pass its argv after `--`. `<git dir>` is the output of `git rev-parse --path-format=absolute --git-common-dir`, where the executor commits and writes its submission; the drain fills `{worktree_git_dir}` with the task worktree's own Git directory, which Codex's sandbox keeps read-only unless that exact directory is listed:
+See [loop.md](references/loop.md) for an unclear result or `--worktree-root`. The executor is the configured route, the `.devlyn/engines.json` `executor` pin or else this CLI, checked per `_shared/engine-preflight.md`. Pass its argv after `--`. `<git dir>` is the output of `git rev-parse --path-format=absolute --git-common-dir`, where the executor commits and writes its submission; the drain fills `{worktree_git_dir}` with the task worktree's own Git directory, which Codex's sandbox keeps read-only unless that exact directory is listed:
 
 | Executor | argv |
 |---|---|
@@ -116,7 +116,7 @@ Follow [loop.md](references/loop.md). The executor is the configured route, the
 Another engine needs an argv that starts one fresh non-interactive session able, without prompts, to edit, run commands and commit in its task worktree and to write the packet's submission file. `<prompt>` carries the absolute binding values, while `{packet}` stays literal for the drain to fill:
 
 ```text
-Execute the devlyn loop task packet {packet}: read its workerPrompt when present; read methodology.defaults.path when named and apply those verified defaults, with explicit user and native owner/project instructions taking precedence, except a Devlyn managed block (devlyn:instructions markers), which those defaults replace; work only in its owned worktree under the installed instructions; meet its obligations, then write its submission and any review records as "Executor exchange" and "Review records" in <DEVLYN_SKILL_DIR>/references/loop.md specify. Use the literal DEVLYN_SKILL_DIR and DEVLYN_SHARED_DIR bindings in workerPrompt when present; otherwise set DEVLYN_SKILL_DIR=<DEVLYN_SKILL_DIR> and DEVLYN_SHARED_DIR=<DEVLYN_SHARED_DIR> from these literal values. Never use inherited environment values. Never push, open a pull request or merge: the drain delivers.
+Execute the devlyn loop task packet {packet}: read its workerPrompt when present; read methodology.defaults.path when named and apply those verified defaults, with explicit user and native owner/project instructions taking precedence, except a Devlyn managed block (devlyn:instructions markers), which those defaults replace; work only in its owned worktree under the installed instructions; meet its obligations, then write its submission and any review records as <DEVLYN_SKILL_DIR>/references/executor.md specifies. Use the literal DEVLYN_SKILL_DIR and DEVLYN_SHARED_DIR bindings in workerPrompt when present; otherwise set DEVLYN_SKILL_DIR=<DEVLYN_SKILL_DIR> and DEVLYN_SHARED_DIR=<DEVLYN_SHARED_DIR> from these literal values. Never use inherited environment values. Never push, open a pull request or merge: the drain delivers.
 ```
 
 ```sh

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

@@ -0,0 +1,62 @@
+# Loop executor
+
+## Executor exchange
+
+The packet (`<receipt dir>/packet.json`) carries everything a fresh executor needs:
+
+| Field | Meaning |
+|---|---|
+| `task`, `title`, `kind` | Queue identity and deliverable description. |
+| `worktree`, `branch`, `receipt`, `scratch` | Absolute owned worktree, branch, receipt and disposable build directory. |
+| `allocation_base`, `inputs_sha` | Allocation base and the committed-inputs commit. |
+| `contract`, `expected`, `meta` | `{path, sha256}` of the committed task contract, expected acceptance and meta-prompt. |
+| `requirements`, `review_requirements` | Requirement IDs and those needing review evidence. |
+| `shared_constraints` | The meta-prompt's `Constraints and exclusions`. |
+| `dependencies` | `{task, receipt, source_sha}` of each accepted prerequisite. |
+| `schema_version`, `harness` | New packets use version 2 and the bound release reference, or null for legacy unbound queues. Existing v1 packets execute unchanged. |
+| `methodology` | `projectInstructions`: `{path, sha256}` of instruction bytes at the inputs commit. `defaults`: `{source: "release", path, sha256}` from the verified binding; for an unbound queue `{source: "skill", path, sha256}` of the installation's own `_shared/runtime-principles.md`. Read the named defaults; explicit user and native owner/project instructions take precedence, except a Devlyn managed block (devlyn:instructions markers), which the defaults replace. No native engine applicability is inferred from filenames. |
+| `workerPrompt` | `{path, sha256}` of the task’s worker instructions, or null for legacy unbound queues. Read it before working. |
+| `delivery` | `local-only`, `auto` or `pr`. |
+| `evidence_dir`, `runner` | Where loop evidence lives (`<worktree>/.devlyn/loop`, ignored by Git) and the runner argv. |
+| `submission`, `obligations` | Where to write the submission, and the completion obligations. |
+
+Writable tool caches go under `scratch`, for example `npm_config_cache=<scratch>/npm`: Codex's sandbox keeps caches in HOME read-only.
+
+Build in the worktree's default build directory, never one redirected into `scratch` or shared with another checkout: drain re-runs the checks without your environment.
+
+Run `runner` (`acceptance.py run --packet <packet>`) on the committed candidate before review. It prints `{"result": <path>, "passed": ..., "reasons": [...]}`; listing a wholly clean result (empty `reasons`) lets drain reuse its outcomes. Then write the submission:
+
+```json
+{
+  "schema_version": 1,
+  "task": "<identity>",
+  "source_sha": "<candidate commit on the owned branch>",
+  "runner_results": ["<worktree>/.devlyn/loop/runs/<n>/result.json"],
+  "reviews": ["<worktree>/.devlyn/reviews/<name>.json"],
+  "assumptions": ["<each assumption, recorded once>"],
+  "blockers": []
+}
+```
+
+`schema_version`, `task` and `source_sha` are required. A blocker `{"kind": "failed" | "needs-review", "detail": "<concrete question or cause>"}` records `[F]` with that reason and runs no checks; material ambiguity becomes `needs-review`, never a weakened acceptance. Only when all that stops the task is a cause a later run can clear (network, service, login, usage limit), write no submission: name it in your final message, and the next drain runs the task again; any other blocker is submitted.
+
+## Review records
+
+Each `review_requirements` ID needs review evidence: a JSON record under `<worktree>/.devlyn/`, listed in the submission's `reviews`, in this shape:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "devlyn-review",
+  "task": "<identity>",
+  "engine": "<engine>",
+  "model": "<exact model id>",
+  "source_sha": "<reviewed commit>",
+  "contract_sha256": "<packet.contract.sha256>",
+  "expected_sha256": "<packet.expected.sha256>",
+  "requirements": ["R3"],
+  "findings": [{"id": "F1", "binding": true, "disposition": "resolved", "requirement": "R3", "summary": "<finding>"}]
+}
+```
+
+A record counts only when it binds this task, the candidate source and both contract digests; any other well-formed record is reported under `ignored_reviews` (a source change invalidates earlier reviews). A listed review or runner record that is unreadable or not this shape fails acceptance with its path named; keys a review record or finding adds beyond this shape are ignored. The counted records' `requirements` must cover `review_requirements`. Each finding's `disposition` is `open`, `resolved` or `rejected` (`rejected` needs a `reason`); an open binding finding blocks acceptance. The loop requires no particular engine or number of reviewers.

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

@@ -28,7 +28,7 @@ The host supplies the executor and maps its configured engine to the argv; the l
    - 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. 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.** Verify the bound release, defaults, packet and worker prompt before execution or recovery; changed or missing resources refuse dispatch. 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.
+5. **Exchange one packet.** Verify the bound release, defaults, packet and worker prompt before execution or recovery; changed or missing resources refuse dispatch. 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 its output files, 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.
@@ -63,61 +63,4 @@ Codex projection writers place `.devlyn-harness-projection.json` at the copied p
 
 ## Executor exchange
 
-The packet (`<receipt dir>/packet.json`) carries everything a fresh executor needs:
-
-| Field | Meaning |
-|---|---|
-| `task`, `title`, `kind` | Queue identity and deliverable description. |
-| `worktree`, `branch`, `receipt`, `scratch` | Absolute owned worktree, branch, receipt and disposable build directory. |
-| `allocation_base`, `inputs_sha` | Allocation base and the committed-inputs commit. |
-| `contract`, `expected`, `meta` | `{path, sha256}` of the committed task contract, expected acceptance and meta-prompt. |
-| `requirements`, `review_requirements` | Requirement IDs and those needing review evidence. |
-| `shared_constraints` | The meta-prompt's `Constraints and exclusions`. |
-| `dependencies` | `{task, receipt, source_sha}` of each accepted prerequisite. |
-| `schema_version`, `harness` | New packets use version 2 and the bound release reference, or null for legacy unbound queues. Existing v1 packets execute unchanged. |
-| `methodology` | `projectInstructions`: `{path, sha256}` of instruction bytes at the inputs commit. `defaults`: `{source: "release", path, sha256}` from the verified binding; for an unbound queue `{source: "skill", path, sha256}` of the installation's own `_shared/runtime-principles.md`. A task whose executor would get no principles at all (no defaults and no committed CLAUDE.md/AGENTS.md) waits with that reason instead of running. Read the named defaults; explicit user and native owner/project instructions take precedence, except a Devlyn managed block (devlyn:instructions markers), which the defaults replace. No native engine applicability is inferred from filenames. |
-| `workerPrompt` | `{path, sha256}` of the task’s worker instructions, or null for legacy unbound queues. Read it before working. |
-| `delivery` | `local-only`, `auto` or `pr`. |
-| `evidence_dir`, `runner` | Where loop evidence lives (`<worktree>/.devlyn/loop`, ignored by Git) and the runner argv. |
-| `submission`, `obligations` | Where to write the submission, and the completion obligations. |
-
-Writable tool caches go under `scratch`, for example `npm_config_cache=<scratch>/npm`: Codex's sandbox keeps caches in HOME read-only.
-
-Build in the worktree's default build directory, never one redirected into `scratch` or shared with another checkout: drain re-runs the checks without your environment. Allocation may have warmed it (`build_dirs` in the receipt).
-
-Run `runner` (`acceptance.py run --packet <packet>`) on the committed candidate before review. It prints `{"result": <path>, "passed": ..., "reasons": [...]}`; listing a wholly clean result (empty `reasons`) lets drain reuse its outcomes. Then write the submission:
-
-```json
-{
-  "schema_version": 1,
-  "task": "<identity>",
-  "source_sha": "<candidate commit on the owned branch>",
-  "runner_results": ["<worktree>/.devlyn/loop/runs/<n>/result.json"],
-  "reviews": ["<worktree>/.devlyn/reviews/<name>.json"],
-  "assumptions": ["<each assumption, recorded once>"],
-  "blockers": []
-}
-```
-
-`schema_version`, `task` and `source_sha` are required. A blocker `{"kind": "failed" | "needs-review" | "blocked-infrastructure", "detail": "<concrete question or cause>"}` records `[F]` with that reason and runs no checks; material ambiguity becomes `needs-review`, never a weakened acceptance.
-
-## Review records
-
-Each `review_requirements` ID needs review evidence: a JSON record under `<worktree>/.devlyn/`, listed in the submission's `reviews`, in this shape:
-
-```json
-{
-  "schema_version": 1,
-  "kind": "devlyn-review",
-  "task": "<identity>",
-  "engine": "<engine>",
-  "model": "<exact model id>",
-  "source_sha": "<reviewed commit>",
-  "contract_sha256": "<packet.contract.sha256>",
-  "expected_sha256": "<packet.expected.sha256>",
-  "requirements": ["R3"],
-  "findings": [{"id": "F1", "binding": true, "disposition": "resolved", "requirement": "R3", "summary": "<finding>"}]
-}
-```
-
-A record counts only when it binds this task, the candidate source and both contract digests; any other well-formed record is reported under `ignored_reviews` (a source change invalidates earlier reviews). A listed review or runner record that is unreadable or not this shape fails acceptance with its path named; keys a review record or finding adds beyond this shape are ignored. The counted records' `requirements` must cover `review_requirements`. Each finding's `disposition` is `open`, `resolved` or `rejected` (`rejected` needs a `reason`); an open binding finding blocks acceptance. The loop requires no particular engine or number of reviewers.
+Executor exchange and Review records are in [executor.md](executor.md).