devlyn-cli 4.3.0 → 4.3.3

package/bin/skill-history.json

@@ -80,6 +80,7 @@
       "69a3fa5c1e7c5358cf7571936c8c09f5cc1d13999c8490ac10533af2091c4226",
       "6a523474b70ba99aff5472020cdde9ca1e7c91f8ee65db03c9e712adfac6d31d",
       "6d1a5458b23196b6f6fde6b7e9dc097ed173cb5914de439e512a032ca1892812",
+      "6e70044cab5a3fb1f78b7148c2111e4298ce8f5f8e902220430ca316bb61255d",
       "6fa2b5e089dcd00613c6e9800d2e763da9e5b2c80e6a7ef5d54d5ad7113e8399",
       "71fb125e20420d6f3fcd3396093fcdc8d552bab9626c3cbd962351e0d19adac8",
       "725395f70eec7e2ceae1f3aa122893433923b098a1e0d6202dd410979ef4eea0",
@@ -146,6 +147,7 @@
       "d3b40b9f0e15bf90ca557c0198a8fe5ff1d046b9aaa54b181c743d8e006f9c34",
       "d424feceffc005f220e33a19cac73f33bd40d120cc14da33725b8a990704bcf6",
       "d7388e36d76647a89ce52de615271928cf9fc78f980df399d2bc2e6d6675ec82",
+      "d85fa24b9b2c439742c9a62d5d4e07a031a1cfe6024bbc06f98eff7063424179",
       "dac3da11ea5686382f5c9892a0b8e4ec25e625e5946283d8e2ad944aa84e1df2",
       "db867d1fd98058bb20e41e942abd95f08fbaa9465928025f69f0a0308fa71514",
       "dd0bfdfd2db0b5f9ddef75d1b9ce3247698739fc551d292366dccd506fef6a36",
@@ -320,6 +322,7 @@
       "0dc69c20434966015176d83baa6f95b3421f9e13d0b1bd608a22f0560eae1049",
       "0fe9b270d670f70da9d2535969b6117684b7c1517806b3029ebaf9624da8006c",
       "1582c202d361af927c2d0843d4bcb72ccc98a0a2a9d8344d118d680f70f7e1e4",
+      "19207315f23c9a12bf2ced0e4e79bb7dfdc7cc5d0c9dd94095d9c6dfe1e8fea8",
       "1d8c3bd31c8b755acd0c3c9f416acb5024dfa99fbf5e2c14d8d6df00a24fe9b4",
       "300d1af60cc53285935dc4b5b370e157707218d844a4303b96d7826eef36ed43",
       "302b1a6c109087dce02ed6af184d6aeeca6cecfd40ebe638beecf8bdf21cf59c",

package/config/skills/_shared/harness-store.py

@@ -52,7 +52,8 @@ def release_ref(value):
 
 def verify_release(root):
     root = Path(root)
-    script = "const r=require(process.argv[1]);r.runJson(()=>r.verifyRelease(process.argv[2]));"
+    # As harness-status verifies it: an npm-installed package keeps npm's own .bin shims, which are checked.
+    script = "const r=require(process.argv[1]);r.runJson(()=>r.verifyRelease(process.argv[2],{npmInstall:true}));"
     result = subprocess.run(["node", "-e", script, str(root / "bin/release.js"), str(root)], capture_output=True, text=True, encoding="utf-8")
     require(result.returncode == 0, f"release verification failed: {root}: {result.stderr.strip()}")
     try:

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

@@ -108,13 +108,16 @@ removes them. Preserve all other work and report anything left behind.
 
 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 a Cargo workspace's
+one checkout's outputs as fresh for the other. When the shared repository-local
+Git config `devlyn.warmBuildDirs` is true, or it is unset and the Cargo workspace's
 Cargo.toml sets `[workspace.metadata.devlyn] warm-build-dirs = true`,
 allocation seeds that directory from a built checkout of the repository, so
 the first build does not rebuild every dependency; `build_dirs` in its result
 and receipt says what it did, and a skip means an ordinary cold build. The
-opt-in is the workspace's: seeding keeps dependency outputs that may hold the
-other checkout's paths, and those follow that checkout's later rebuilds. `warm-build-dirs.py <worktree>` does the same for a
+Git setting takes precedence on this machine: false disables and invalid values
+skip; global, system, include and per-worktree values are not consulted. Seeding
+keeps dependency outputs that may hold the other checkout's paths, and those
+follow that checkout's later rebuilds. `warm-build-dirs.py <worktree>` does the same for a
 worktree made without allocation. A warmed directory leaves with the worktree
 after merge, so a pending, failed or local-only task keeps it.
 

package/config/skills/_shared/warm-build-dirs.py

@@ -31,6 +31,9 @@ a crate that compiled a path in where the reading above does not see it) still n
 donor's files: when the donor rebuilds or removes them, the recipient can change behavior
 without a warning. That is why a workspace opts in, with `[workspace.metadata.devlyn]
 warm-build-dirs = true` in its Cargo.toml, once its dependencies do not use such paths.
+The repository's shared local Git config `devlyn.warmBuildDirs` overrides that opt-in on
+this machine: true enables, false disables, unset uses Cargo.toml, and invalid values skip.
+Global, system, include and per-worktree config values are not consulted.
 
 The donor is only read: its dev build lock is taken from an existing lock file opened read-only,
 without waiting, while the layouts are cloned. The whole operation has a time limit. Every skip
@@ -89,6 +92,14 @@ class Skip(Exception):
     """An expected reason not to warm; the build starts cold."""
 
 
+class CommandFailed(Skip):
+    """A command failed; retain its exit code and diagnostics for callers."""
+
+    def __init__(self, argv, result):
+        self.result = result
+        super().__init__(f"{' '.join(map(str, argv[:3]))} failed: {(result.stderr or result.stdout).strip()[-400:]}")
+
+
 class Unsafe(Exception):
     """A safety check failed; nothing was published and the donor was not written."""
 
@@ -120,7 +131,7 @@ def run(argv, *, cwd, deadline, env=None):
     except subprocess.TimeoutExpired as exc:
         raise TimeUp(f"{' '.join(map(str, argv[:3]))} timed out") from exc
     if result.returncode != 0:
-        raise Skip(f"{' '.join(map(str, argv[:3]))} failed: {(result.stderr or result.stdout).strip()[-400:]}")
+        raise CommandFailed(argv, result)
     return result.stdout
 
 
@@ -166,7 +177,19 @@ def no_symlink_between(root, path):
 def destination(work, deadline, stack):
     """The worktree's own Cargo target directory and a descriptor for its parent, when it can be warmed."""
     found = metadata(work, deadline)
-    if ((found.get("metadata") or {}).get("devlyn") or {}).get("warm-build-dirs") is not True:
+    setting = "git config --local devlyn.warmBuildDirs"
+    try:
+        enabled = git(work, "config", "--local", "--type=bool", "--get", "devlyn.warmBuildDirs", deadline=deadline)
+    except CommandFailed as exc:
+        if exc.result.returncode != 1:
+            error = (exc.result.stderr or exc.result.stdout or str(exc)).splitlines()[0]
+            raise Skip(f"cannot read {setting}: {error}") from exc
+        enabled = None
+    except OSError as exc:
+        raise Skip(f"cannot read {setting}: {exc}") from exc
+    if enabled == "false":
+        raise Skip(f"turned off: {setting} is false")
+    if enabled != "true" and ((found.get("metadata") or {}).get("devlyn") or {}).get("warm-build-dirs") is not True:
         raise Skip("not enabled: the workspace's Cargo.toml has no [workspace.metadata.devlyn] warm-build-dirs = true")
     if any(key in os.environ for key in REDIRECTS) and metadata(work, deadline, env=without_redirects()) != found:
         raise Skip("the target directory comes from this environment, which later commands may not share")
@@ -799,6 +822,78 @@ class WarmTests(unittest.TestCase):
         self.assertEqual([], list(self.staging.iterdir()))
         self.assertEqual("", self.git(self.work, "status", "--porcelain", "--untracked-files=all"))
 
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_local_git_true_seeds_without_cargo_opt_in(self):
+        self.write_fixture(workspace_metadata=None)
+        self.git(self.anchor, "config", "--local", "devlyn.warmBuildDirs", "true")
+        [result] = self.warm()
+        self.assertEqual("seeded", result["status"], result)
+        self.assertTrue((self.work / "target" / "debug" / "deps" / f"libserde-{'1' * 16}.rlib").is_file())
+        self.assert_nothing_left()
+
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_local_git_false_overrides_cargo_opt_in(self):
+        self.git(self.anchor, "config", "--local", "devlyn.warmBuildDirs", "false")
+        [result] = self.warm()
+        self.assertEqual("skipped", result["status"], result)
+        self.assertEqual("turned off: git config --local devlyn.warmBuildDirs is false", result["reason"])
+        self.assertFalse((self.work / "target").exists())
+        self.assert_nothing_left()
+
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_invalid_local_git_value_skips_with_git_error(self):
+        self.git(self.anchor, "config", "--local", "devlyn.warmBuildDirs", "invalid")
+        [result] = self.warm()
+        self.assertEqual("skipped", result["status"], result)
+        self.assertIn("git config --local devlyn.warmBuildDirs", result["reason"])
+        self.assertIn("fatal: bad boolean config value 'invalid' for 'devlyn.warmbuilddirs'", result["reason"])
+        self.assertFalse((self.work / "target").exists())
+        self.assert_nothing_left()
+
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_unset_local_git_value_uses_cargo_opt_in(self):
+        for opted_in in (False, True):
+            with self.subTest(opted_in=opted_in):
+                self.write_fixture(workspace_metadata={"devlyn": {"warm-build-dirs": opted_in}})
+                [result] = self.warm()
+                self.assertEqual("seeded" if opted_in else "skipped", result["status"], result)
+                if not opted_in:
+                    self.assertIn("not enabled", result["reason"])
+                self.assert_nothing_left()
+
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_other_git_config_failures_skip_with_first_error_line(self):
+        config = self.anchor / ".git" / "config"
+        config.write_text(config.read_text() + "\n[broken\nsecond bad line\n")
+        error = subprocess.run(["git", "-C", str(self.work), "config", "--local", "--type=bool",
+                                "--get", "devlyn.warmBuildDirs"], capture_output=True, text=True)
+        self.assertNotIn(error.returncode, (0, 1))
+        [result] = self.warm()
+        self.assertEqual("skipped", result["status"], result)
+        self.assertEqual(f"cannot read git config --local devlyn.warmBuildDirs: {error.stderr.splitlines()[0]}",
+                         result["reason"])
+        self.assertFalse((self.work / "target").exists())
+        self.assertEqual([], list(self.staging.iterdir()))
+
+    @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
+    def test_global_include_and_per_worktree_config_do_not_override_cargo(self):
+        global_config, included = self.root / "global-config", self.root / "included-config"
+        os.environ["GIT_CONFIG_GLOBAL"] = str(global_config)
+        self.git(self.anchor, "config", "--local", "include.path", str(included))
+        self.git(self.anchor, "config", "--local", "extensions.worktreeConfig", "true")
+        for opted_in in (False, True):
+            with self.subTest(opted_in=opted_in):
+                value = "false" if opted_in else "true"
+                for config in (global_config, included):
+                    config.write_text(f"[devlyn]\n\twarmBuildDirs = {value}\n")
+                self.git(self.work, "config", "--worktree", "devlyn.warmBuildDirs", value)
+                self.write_fixture(workspace_metadata={"devlyn": {"warm-build-dirs": opted_in}})
+                [result] = self.warm()
+                self.assertEqual("seeded" if opted_in else "skipped", result["status"], result)
+                if not opted_in:
+                    self.assertIn("not enabled", result["reason"])
+                self.assert_nothing_left()
+
     @unittest.skipIf(os.name == "nt", "warming is POSIX-only")
     def test_seeds_only_what_carries_over_and_never_writes_the_donor(self):
         before = self.snapshot(self.donor)

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

@@ -208,6 +208,15 @@ def unfinished(v):
     return any(ref.removeprefix(CAPTURES) not in v["records"] for ref in refs)
 
 
+def bindable(anchor, common):
+    """Whether a first add may bind its release: the queue reads and holds no unfinished work. A queue that cannot be read
+    is not proven settled, so the add captures unbound, as its skill source adds, and status and drain report why."""
+    try:
+        return not unfinished(view(anchor, common, pure=True))
+    except (LoopError, OSError):
+        return False
+
+
 def release_settled_binding(anchor, common, *, interrupted_add=False):
     """Remove the binding once nothing needs it. The bound release keeps one from an interrupted first add (no record
     yet) so its retry rebinds the same identity; another release (`interrupted_add`) drops that too, since a binding
@@ -1674,7 +1683,7 @@ def add(args):
         # The lock covers both first binding and first capture; an interrupted binding is authoritative on retry.
         if harness_call("read_binding", common) is None:
             invoking = harness_call("resolve", SKILLS)
-            if invoking is not None and not unfinished(view(anchor, common, pure=True)):
+            if invoking is not None and bindable(anchor, common):
                 write_json(common / "devlyn-loops/harness.json", invoking)
         tree = build_tree(anchor, None, files)
         if captured:

package/harness/AGENTS.md

@@ -0,0 +1,37 @@
+<!-- devlyn:instructions:begin sha256=019ab670237e90f2e40ea0dbff216bbf2b523a04419ca9c5f5f403482cf55874 -->
+Project-specific instructions outside this managed block take precedence over these defaults.
+
+# Project Instructions
+
+devlyn-cli installs the `devlyn-ideate` and `devlyn-engines` skills alongside the principles below, which are non-negotiable on every change — yours and any sub-agent's.
+
+## North Star
+
+This contract serves one goal: any capable engine — Claude, GPT/Codex, or a future adapter-equipped model — takes a user's intent (prompt, spec, or queue entry) end-to-end to shipped, engineer-quality software, hands-free, with consistent quality across engines. When rules below conflict or feel ambiguous in context, resolve toward this goal.
+
+## Core principles
+
+Seven rules govern every change. Cite them by name when a decision touches one.
+
+1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract. No config bypasses.
+2. **No overengineering** — smallest change that closes the goal. New abstractions require an observed failure mode they prevent. Subtractive-first: ask "what can I delete instead?" before writing anything new. Remove code your change makes unused; only report unrelated pre-existing dead code.
+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** — code that survives review at a non-trivial codebase. Zero CRITICAL, zero HIGH security/design findings on the shippable path.
+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.
+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:
+
+- **Root cause via flexible why-chain.** Keep asking "why?" until you find the violated invariant. **If the answer surfaces in 2 questions, stop.** If it takes 5 or 7, keep going. Strict counts are wrong; until-found is right.
+- **First-principles thinking.** Challenge the requirement before optimizing the answer. Surface unstated assumptions, ambiguities, tradeoffs, and simpler alternatives BEFORE implementing — do not silently pick one interpretation when multiple exist, do not hide confusion, push back when a simpler path is genuinely better. Most "we have to do X" assumptions are habit, not necessity. Reduce the problem to its irreducible truths and rebuild from there.
+- **Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.** — Saint-Exupéry. This is the operating definition of "done." A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
+
+## Quick Start
+
+- `devlyn-ideate` — loop designer and intent queue: `plan <intent or document>` writes a validated loop package, `add` queues its tasks, `status` (or no arguments) reports the queue, `drain` executes it serially.
+- Delivery — direct work edits the current checkout; deliver completed, verified requests with changes by project policy (default PR and merge), following `_shared/task-completion.md` in `.claude/skills/` or `.agents/skills/` (project, else `~`). With known concurrent writers, isolate before editing; on unexplained changes, pause writes until safe or isolated. An ideate drain delivers every task. Explicit limits win; commit alone stays local.
+- Executor — `devlyn-engines` shows it and pins it in `.devlyn/engines.json`. A pinned executor does the implementation work, direct or drained: when it is not you, delegate to it, and when it is unavailable stop with `BLOCKED:<engine>-unavailable`. Without a pin, you are the executor.
+
+Each skill's `SKILL.md` is the source of truth for its flags and workflow.
+<!-- devlyn:instructions:end -->

package/harness/CLAUDE.md

@@ -0,0 +1,37 @@
+<!-- devlyn:instructions:begin sha256=019ab670237e90f2e40ea0dbff216bbf2b523a04419ca9c5f5f403482cf55874 -->
+Project-specific instructions outside this managed block take precedence over these defaults.
+
+# Project Instructions
+
+devlyn-cli installs the `devlyn-ideate` and `devlyn-engines` skills alongside the principles below, which are non-negotiable on every change — yours and any sub-agent's.
+
+## North Star
+
+This contract serves one goal: any capable engine — Claude, GPT/Codex, or a future adapter-equipped model — takes a user's intent (prompt, spec, or queue entry) end-to-end to shipped, engineer-quality software, hands-free, with consistent quality across engines. When rules below conflict or feel ambiguous in context, resolve toward this goal.
+
+## Core principles
+
+Seven rules govern every change. Cite them by name when a decision touches one.
+
+1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract. No config bypasses.
+2. **No overengineering** — smallest change that closes the goal. New abstractions require an observed failure mode they prevent. Subtractive-first: ask "what can I delete instead?" before writing anything new. Remove code your change makes unused; only report unrelated pre-existing dead code.
+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** — code that survives review at a non-trivial codebase. Zero CRITICAL, zero HIGH security/design findings on the shippable path.
+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.
+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:
+
+- **Root cause via flexible why-chain.** Keep asking "why?" until you find the violated invariant. **If the answer surfaces in 2 questions, stop.** If it takes 5 or 7, keep going. Strict counts are wrong; until-found is right.
+- **First-principles thinking.** Challenge the requirement before optimizing the answer. Surface unstated assumptions, ambiguities, tradeoffs, and simpler alternatives BEFORE implementing — do not silently pick one interpretation when multiple exist, do not hide confusion, push back when a simpler path is genuinely better. Most "we have to do X" assumptions are habit, not necessity. Reduce the problem to its irreducible truths and rebuild from there.
+- **Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.** — Saint-Exupéry. This is the operating definition of "done." A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
+
+## Quick Start
+
+- `devlyn-ideate` — loop designer and intent queue: `plan <intent or document>` writes a validated loop package, `add` queues its tasks, `status` (or no arguments) reports the queue, `drain` executes it serially.
+- Delivery — direct work edits the current checkout; deliver completed, verified requests with changes by project policy (default PR and merge), following `_shared/task-completion.md` in `.claude/skills/` or `.agents/skills/` (project, else `~`). With known concurrent writers, isolate before editing; on unexplained changes, pause writes until safe or isolated. An ideate drain delivers every task. Explicit limits win; commit alone stays local.
+- Executor — `devlyn-engines` shows it and pins it in `.devlyn/engines.json`. A pinned executor does the implementation work, direct or drained: when it is not you, delegate to it, and when it is unavailable stop with `BLOCKED:<engine>-unavailable`. Without a pin, you are the executor.
+
+Each skill's `SKILL.md` is the source of truth for its flags and workflow.
+<!-- devlyn:instructions:end -->

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

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

package/native/claude/skills/_shared/.ruff.toml

@@ -0,0 +1,2 @@
+# Vendored devlyn helpers are checked by devlyn's own validation.
+exclude = ["*"]

package/native/claude/skills/_shared/adapters/claude.md

@@ -0,0 +1,15 @@
+# Claude adapter
+
+## Invocation
+
+A Claude executor starts as
+`claude -p "<prompt>" --dangerously-skip-permissions --add-dir "<common git dir>"`,
+where `<common git dir>` is `git rev-parse --path-format=absolute --git-common-dir`:
+a linked task worktree commits there.
+
+**Availability probe**: `command -v claude >/dev/null 2>&1`; record
+`claude --version` as evidence. The probe is necessary, not sufficient:
+`claude -p` needs network access to the Anthropic API, so in a network-denying
+sandbox (e.g. Codex CLI's default `workspace-write`) it fails even though the
+binary resolves. A drain blocks when the executor cannot start, and a task
+whose executor exits without a submission waits for the next drain.

package/native/claude/skills/_shared/adapters/codex.md

@@ -0,0 +1,14 @@
+# Codex adapter
+
+## Invocation
+
+A Codex executor runs through `_shared/codex-monitored.sh`, never a raw or piped
+`codex exec`: `bash "$DEVLYN_SHARED_DIR/codex-monitored.sh" <arguments for codex exec> "<prompt>"`.
+The `workspace-write` sandbox keeps `.git` read-only, so an executor that commits adds as
+writable roots the common Git directory (`git rev-parse --path-format=absolute --git-common-dir`)
+plus, in a linked worktree, its own Git directory (`git rev-parse --path-format=absolute --git-dir`),
+listed exactly because the sandbox protects it even under a listed parent. It also
+denies network, which installing a new dependency needs:
+`-s workspace-write -c 'sandbox_workspace_write.writable_roots=["<git dir>","<worktree git dir>"]' -c 'sandbox_workspace_write.network_access=true'`.
+Deliver a multiline prompt as exact file bytes: set `DEVLYN_CODEX_PROMPT_FILE=<file>`
+and pass the sole prompt argument `-`.

package/native/claude/skills/_shared/adapters/omp.md

@@ -0,0 +1,6 @@
+# oh-my-pi adapter
+
+executor: no
+
+Engine `omp`, the oh-my-pi CLI.
+Stub: model-call execution and failure handling have not been qualified.

package/native/claude/skills/_shared/codex-monitored.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# codex-monitored.sh — run `codex exec` in a monitored shape that keeps the
+# outer claude -p API stream from going silent during long Codex calls.
+#
+# WHY (iter-0009, post iter-0006/0007/0008):
+#   • iter-0007 isolation proved a single foreground `codex exec` Bash dispatch
+#     can starve the outer API stream of bytes during a 10+ min run; Anthropic's
+#     byte-level idle watchdog fires (~300s) and kills the orchestrator.
+#   • iter-0008 saw the orchestrator pick `codex exec ... 2>&1 | tail -200` from
+#     its own pattern prior — `tail` on a pipe buffers until EOF, suppressing
+#     ALL bytes. Same starvation, amplified.
+#   • iter-0008 also documented codex 0.124.0 reads stdin as a `<stdin>` block
+#     when the prompt is passed as an arg AND stdin is open; without
+#     `< /dev/null` the call hangs indefinitely.
+#
+# WHAT THIS WRAPPER DOES:
+#   1. Refuses to run if stdout is a pipe. Piping wrapper output to text tools
+#      (tail/head/awk/sed/grep without --line-buffered) re-introduces the
+#      iter-0008 starvation mechanism — the downstream tool buffers until EOF
+#      and the outer claude -p byte-watchdog never sees bytes. Exits 64 with a
+#      clear message so the orchestrator can self-correct on retry.
+#      (Round 2 finding #1 fix: shim alone does not defeat `| tail`; the
+#      wrapper must reject the pipe shape directly.)
+#   2. Closes stdin unless DEVLYN_CODEX_PROMPT_FILE supplies the sole prompt.
+#   3. Streams codex stdout to OUR stdout line-by-line — the caller reads
+#      stdout as the Codex reply, so we MUST NOT swallow it (e.g.
+#      `tail -n 200`). codex stderr forwards to OUR stderr.
+#   4. Emits a `[codex-monitored] heartbeat` line every CODEX_MONITORED_HEARTBEAT
+#      seconds (default 30s) on STDERR while codex is alive. Heartbeat-on-stderr
+#      keeps the orchestrator's combined-output stream non-silent without
+#      polluting the codex-reply view of stdout.
+#   5. Forwards SIGTERM/SIGINT from the outer watchdog to the codex child so a
+#      timeout actually reaps codex (otherwise process group kill races with
+#      backgrounded codex).
+#   6. Preserves codex's exact exit code.
+#
+# USAGE:
+#   bash codex-monitored.sh -C <repo> -s read-only "<prompt>"
+#   bash codex-monitored.sh resume --last
+#   (Args after the script name are passed verbatim to `codex exec`.)
+#
+# ENV OVERRIDES:
+#   CODEX_MONITORED_HEARTBEAT      — heartbeat interval seconds (default 30).
+#   CODEX_MONITORED_TIMEOUT_SEC    — optional hard timeout. When >0, kill the
+#                                     codex process group and exit 124.
+#   CODEX_BIN                      — real codex binary path. Default:
+#                                     CODEX_REAL_BIN when set, else `codex`.
+#                                     Set this when the shim has put us first
+#                                     on PATH.
+#   CODEX_MONITORED_ALLOW_PIPED    — set non-empty to skip the pipe-stdout
+#                                     refusal. Reserved for tests; don't use
+#                                     in skill prompts.
+#   DEVLYN_CODEX_PROMPT_FILE      — exact binary stdin prompt; requires sole `-`.
+
+set -uo pipefail
+
+# iter-0019 — solo_claude (L1) arm enforcement (defense in depth alongside
+# scripts/codex-shim/codex). If this env is set, the wrapper refuses to invoke
+# codex at all, regardless of how it was reached. Two enforcement points
+# protect against the case where one is bypassed: the shim catches PATH-based
+# resolution, and this wrapper catches direct-path invocations of
+# codex-monitored.sh that don't go through the shim.
+if [ -n "${CODEX_BLOCKED:-}" ]; then
+  printf '[codex-monitored] CODEX_BLOCKED=%s — refusing codex invocation (solo_claude / L1 arm enforcement). args: %s\n' \
+    "${CODEX_BLOCKED}" "$*" >&2
+  exit 126
+fi
+
+HEARTBEAT_SEC="${CODEX_MONITORED_HEARTBEAT:-30}"
+TIMEOUT_SEC="${CODEX_MONITORED_TIMEOUT_SEC:-0}"
+CODEX_BIN="${CODEX_BIN:-${CODEX_REAL_BIN:-codex}}"
+START=$(date +%s)
+TIMEOUT_FLAG=""
+CODEX_ARGS=("$@")
+
+for codex_arg in "${CODEX_ARGS[@]}"; do
+  case "$codex_arg" in
+    --dangerously-bypass-approvals-and-sandbox|--yolo)
+      printf '[codex-monitored] error: forbidden Codex bypass flag: %s\n' "$codex_arg" >&2
+      exit 64
+      ;;
+    danger-full-access|-s=danger-full-access|--sandbox=danger-full-access)
+      printf '[codex-monitored] error: forbidden Codex sandbox: danger-full-access\n' >&2
+      exit 64
+      ;;
+  esac
+done
+
+require_nonnegative_int() {
+  local name="$1"
+  local value="$2"
+  case "$value" in
+    ''|*[!0-9]*)
+      printf '[codex-monitored] error: %s must be a non-negative integer (got %s)\n' \
+        "$name" "$value" >&2
+      exit 64
+      ;;
+  esac
+}
+
+require_positive_int() {
+  local name="$1"
+  local value="$2"
+  require_nonnegative_int "$name" "$value"
+  if [ "$value" -le 0 ]; then
+    printf '[codex-monitored] error: %s must be > 0 (got %s)\n' \
+      "$name" "$value" >&2
+    exit 64
+  fi
+}
+
+require_positive_int CODEX_MONITORED_HEARTBEAT "$HEARTBEAT_SEC"
+require_nonnegative_int CODEX_MONITORED_TIMEOUT_SEC "$TIMEOUT_SEC"
+
+# --- Pipe-stdout refusal (iter-0009 R2 finding #1) -------------------------
+# `[ -p /dev/stdout ]` is the POSIX test for "is fd 1 a FIFO/pipe". Verified
+# correct on macOS via lsof: distinguishes piped (`| cat`) from redirected
+# (`> file`) and from claude-bash-tool capture (regular file). Without this
+# refusal, `bash WRAPPER ... 2>&1 | tail -200` would buffer wrapper output —
+# including the heartbeat on stderr after `2>&1` — until EOF, reproducing
+# the iter-0008 byte-watchdog kill.
+if [ -z "${CODEX_MONITORED_ALLOW_PIPED:-}" ] && [ -p /dev/stdout ]; then
+  cat >&2 <<'EOF'
+[codex-monitored] error: stdout is a pipe.
+
+Piping the wrapper to tail/head/awk/sed/grep buffers wrapper output until EOF,
+which starves the outer claude -p byte-watchdog (iter-0008 starvation mechanism)
+and kills the run after ~300s with empty transcript.
+
+Fix: invoke the wrapper directly so the bash tool captures its stdout. The
+wrapper streams full Codex output and emits a heartbeat on stderr; you do NOT
+need to truncate.
+
+  WRONG: bash codex-monitored.sh ... 2>&1 | tail -200
+  RIGHT: bash codex-monitored.sh ...
+
+If you absolutely must filter, use a line-buffered tool (e.g. `grep --line-buffered`)
+and set CODEX_MONITORED_ALLOW_PIPED=1 in the wrapper's environment.
+EOF
+  exit 64
+fi
+
+# --- Heartbeat + signal forwarding ----------------------------------------
+heartbeat_loop() {
+  local pid="$1"
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep "$HEARTBEAT_SEC"
+    if kill -0 "$pid" 2>/dev/null; then
+      local elapsed=$(( $(date +%s) - START ))
+      printf '[codex-monitored] heartbeat: elapsed=%ds\n' "$elapsed" >&2
+    fi
+  done
+}
+
+timeout_loop() {
+  local pid="$1"
+  local seconds="$2"
+  local flag="$3"
+  [ "$seconds" -gt 0 ] || return 0
+  sleep "$seconds"
+  if kill -0 "$pid" 2>/dev/null; then
+    : > "$flag"
+    printf '[codex-monitored] timeout: elapsed=%ds limit=%ds\n' \
+      "$(( $(date +%s) - START ))" "$seconds" >&2
+    kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+    sleep 5
+    kill -KILL -- "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+  fi
+}
+
+terminate_process_group() {
+  local pgid="$1"
+  local reason="$2"
+  if ! kill -0 -- "-$pgid" 2>/dev/null; then
+    return 0
+  fi
+  printf '[codex-monitored] reap: reason=%s pgid=%s\n' "$reason" "$pgid" >&2
+  kill -TERM -- "-$pgid" 2>/dev/null || true
+  local i
+  for i in 1 2 3 4 5; do
+    sleep 1
+    if ! kill -0 -- "-$pgid" 2>/dev/null; then
+      return 0
+    fi
+  done
+  kill -KILL -- "-$pgid" 2>/dev/null || true
+}
+
+terminate_monitor_group() {
+  local pid="$1"
+  kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+  kill -KILL -- "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+  wait "$pid" 2>/dev/null || true
+}
+
+forward_signal() {
+  local sig="$1"
+  if [ -n "${CODEX_PID:-}" ] && kill -0 "$CODEX_PID" 2>/dev/null; then
+    kill -"$sig" -- "-$CODEX_PID" 2>/dev/null || kill -"$sig" "$CODEX_PID" 2>/dev/null || true
+  fi
+  if [ -n "${HB_PID:-}" ]; then
+    terminate_monitor_group "$HB_PID"
+    HB_PID=""
+  fi
+  if [ -n "${WATCHDOG_PID:-}" ]; then
+    terminate_monitor_group "$WATCHDOG_PID"
+    WATCHDOG_PID=""
+  fi
+}
+
+cleanup() {
+  forward_signal TERM
+  [ -z "$TIMEOUT_FLAG" ] || rm -f "$TIMEOUT_FLAG"
+}
+
+trap 'forward_signal TERM; exit 143' TERM
+trap 'forward_signal INT; exit 130' INT
+trap cleanup EXIT
+
+printf '[codex-monitored] start: ts=%s heartbeat=%ds timeout=%ss bin=%s\n' \
+  "$(date -u +%FT%TZ)" "$HEARTBEAT_SEC" "$TIMEOUT_SEC" "$CODEX_BIN" >&2
+
+RECEIPT_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/invocation-receipt.py"
+# Native Python owns Windows PIDs and the timeout tree; MSYS PIDs are different.
+if [ "${OS:-}" = Windows_NT ]; then
+  exec python3 "$RECEIPT_HELPER" dispatch --binary "$CODEX_BIN" \
+    --timeout "$TIMEOUT_SEC" --heartbeat "$HEARTBEAT_SEC" -- "${CODEX_ARGS[@]}" < /dev/null
+fi
+
+# The dispatcher snapshots file input, seals actual argv, then execs in this group.
+set -m
+python3 "$RECEIPT_HELPER" dispatch --binary "$CODEX_BIN" \
+  --timeout "$TIMEOUT_SEC" --heartbeat "$HEARTBEAT_SEC" -- "${CODEX_ARGS[@]}" < /dev/null &
+CODEX_PID=$!
+printf '[codex-monitored] codex pid=%d\n' "$CODEX_PID" >&2
+
+heartbeat_loop "$CODEX_PID" &
+HB_PID=$!
+
+if [ "$TIMEOUT_SEC" -gt 0 ]; then
+  TIMEOUT_FLAG=$(mktemp "${TMPDIR:-/tmp}/codex-monitored-timeout.XXXXXX")
+  rm -f "$TIMEOUT_FLAG"
+  timeout_loop "$CODEX_PID" "$TIMEOUT_SEC" "$TIMEOUT_FLAG" &
+  WATCHDOG_PID=$!
+fi
+set +m
+
+wait "$CODEX_PID"
+EXIT=$?
+terminate_process_group "$CODEX_PID" "post-exit-descendants"
+CODEX_PID=""
+forward_signal TERM
+if [ -n "$TIMEOUT_FLAG" ] && [ -f "$TIMEOUT_FLAG" ]; then
+  EXIT=124
+fi
+
+if [ -n "${DEVLYN_CODEX_PROMPT_FILE:-}" ]; then
+  python3 "$RECEIPT_HELPER" complete-dispatch --exit-code "$EXIT" || exit 64
+fi
+
+printf '[codex-monitored] codex exited: code=%d elapsed=%ds\n' \
+  "$EXIT" $(( $(date +%s) - START )) >&2
+exit "$EXIT"