@tranhoangnguyen0310/pi-flow-external 5.4.0-external.0 → 5.4.1-external.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [5.4.1-external.0] - 2026-10-23
+
+### Fixed
+- Bounded-repair now rejects non-Codex harnesses before starting any editor. Supporting edit and readonly permissions alone does not provide the shell access and structured output required by QA.
+- Repair guidance now states the Codex-only limit and requires checks compatible with its read-only sandbox. Regression tests cover rejection before edits and default/explicit Codex execution.
+
 ## [5.4.0-external.0] - 2026-10-23
 
 ### Added

package/docs/orchestration-playbook.md

@@ -44,7 +44,9 @@ Example for parallel-sweep.js:
 
 Before launch the parent should explain the split, selected harnesses, permissions, which checks run in parallel, and what evidence will come back. Foreground is the default when the result is needed next.
 
-The example pins Codex because it supports the explicit readonly tier (and edit for the repair recipe); **it does not automatically switch backends**. Set harness to a verified available backend that enforces the required tier. Antigravity supports only danger, so these restricted examples do not work on it.
+The example pins Codex because it supports the explicit readonly tier; **it does not automatically switch backends**. For the read-only recipes, set harness to a verified available backend that enforces the required tier. Antigravity supports only danger, so these restricted examples do not work on it.
+
+**Bounded repair is Codex-only.** It rejects other harnesses before any editor starts. Supporting edit and readonly tiers is not enough: QA must also have shell access and structured output. OpenCode rejects the required schema, while Claude, Muse, and named Pi harnesses cannot shell-run tests at readonly. Before launch, confirm Codex is available and the checks can run in its read-only sandbox; checks that need workspace writes or network access may fail. Do not silently raise permissions to run them.
 
 ## What good behavior looks like
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "5.4.0-external.0",
+  "version": "5.4.1-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/skills/pi-flow-orchestration/SKILL.md

@@ -34,9 +34,9 @@ Read [pattern-selection.md](references/pattern-selection.md) for failure modes a
 - [parallel-sweep.js](recipes/parallel-sweep.js) — independent scopes, partial failures kept.
 - [branch-and-converge.js](recipes/branch-and-converge.js) — parallel discovery with explicit evidence handoff into a final synthesis.
 - [adversarial-review.js](recipes/adversarial-review.js) — draft and independent critique (not a self-review).
-- [bounded-repair.js](recipes/bounded-repair.js) — authorized edits, structured checks, limited iterations.
+- [bounded-repair.js](recipes/bounded-repair.js) — Codex-only authorized edits, structured checks, limited iterations. Other harnesses are rejected before any child starts.
 
-These are adaptable **examples**, not new runtime functions. Copy a recipe into a trusted saved workflow root or pass its text as the script to external_workflow, and pass JSON inputs through the tool's args. A scriptPath must be inside an allowed workflow root; a package skill directory is not automatically such a root. Recipes assume Codex as a restricted-permission demonstration backend, not an automatic fallback. Set harness inputs to an available backend that enforces the required tier.
+These are adaptable **examples**, not new runtime functions. Copy a recipe into a trusted saved workflow root or pass its text as the script to external_workflow, and pass JSON inputs through the tool's args. A scriptPath must be inside an allowed workflow root; a package skill directory is not automatically such a root. Recipes assume Codex as a restricted-permission demonstration backend, not an automatic fallback. For the read-only recipes, set harness inputs to an available backend that enforces the required tier. Bounded repair requires Codex: QA needs both shell access at readonly and structured output. Before launch, confirm Codex is available and the specified checks can run in its read-only sandbox; checks that need workspace writes or network access may fail.
 
 ## Flow rules that prevent common failures
 

package/skills/pi-flow-orchestration/recipes/bounded-repair.js

@@ -18,7 +18,11 @@ if (typeof input.checks !== "string" || !input.checks.trim()) throw new Error("a
 if (!Number.isInteger(input.maxAttempts) || input.maxAttempts < 1 || input.maxAttempts > 3) {
   throw new Error("args.maxAttempts must be an authorized number in 1-3");
 }
-const harness = input.harness || "codex"; // Must enforce both edit and readonly.
+// shortcut: Codex-only QA; expand after verifying shell access and structured output at readonly.
+const harness = input.harness === undefined ? "codex" : input.harness;
+if (harness !== "codex") {
+  throw new Error('bounded-repair requires harness "codex" for shell checks and structured QA; no agents started');
+}
 const attempts = [];
 let feedback = "";
 for (let attempt = 1; attempt <= input.maxAttempts; attempt++) {

package/skills/pi-flow-orchestration/references/runtime-rules.md

@@ -19,7 +19,7 @@ Use the installed version's external_help({topic:"workflow"}) and external_help(
 - Claude readonly and edit have native tool restrictions, not kernel isolation; headless shell is denied at those tiers. Codex supports read-only and workspace-write OS sandboxes. Do not promise the same security guarantee across backends.
 - For inspection-only work, prefer a harness that can enforce readonly. A prompt saying "don't edit" alone is insufficient.
 - Do not execute parallel edits in the same working tree unless the parent has verified disjoint ownership and no shared-file changes. No built-in worktree isolation or merge arbitration exists in Flow.
-- A repair recipe needs the user to authorize edits and the expected fix/test cycle. Do not auto-retry failed children or expand permission without authorization.
+- A repair recipe needs the user to authorize edits and the expected fix/test cycle. The bundled bounded-repair recipe accepts only Codex and rejects other harnesses before starting children: QA requires shell access at readonly plus structured output, not just support for the permission tiers. Confirm the checks can run in Codex's read-only sandbox before editing. Do not auto-retry failed children or expand permission without authorization.
 
 ## Context and handoff