@magnusekdahl/parallix 1.3.0 → 1.3.2

package/README.md

@@ -145,11 +145,13 @@ px active task-042
 
 # Land it: runs configured integration gates, squash-merges to
 # the primary branch, updates board state, removes the branch
-# and worktree.
+# and worktree. In this repo that means a fast general verifier
+# during earlier phases and a stricter lifecycle E2E gate before
+# integrate lands.
 px integrate task-042
 ```
 
-The verification gate that runs at each checkpoint is whatever you declare in `workflow.config.json` (this repo declares `npm test`), so the workflow adopts your existing CI rather than replacing it.
+The verification gate that runs at each phase is whatever you declare in `workflow.config.json`. In this repo that dispatcher is `./scripts/verify-local.sh {{area}}`: earlier phases use the fast general suite, while `px integrate` calls `verify-local.sh integrate`, which resolves repo-side integration gates from `config/integration-pipelines.json` and runs the stricter pre-merge checks there.
 
 ## Use cases
 

package/config/integration-pipelines.json

@@ -4,6 +4,11 @@
       "command": "./scripts/verify-local.sh static-analysis",
       "order": 1,
       "run_last": false
+    },
+    "workflow": {
+      "command": "node test/e2e-mission-lifecycle.test.js",
+      "order": 50,
+      "run_last": true
     }
   }
 }

package/docs/adr/0048-fail-closed-harness-defense-against-agent-hallucinations.md

@@ -0,0 +1,161 @@
+# ADR 0048: Fail-closed harness defense against agent hallucinations
+
+Status: Accepted
+Date: 2026-06-29
+
+Related: ADR 0041 (integration pipeline gates), ADR 0047 (NEL budget), task-1268 (shift-left verification), task-1335 (harden publish path)
+
+## Context
+
+Parallix already has meaningful defenses against agent hallucinations and incomplete work, but they are fragmented across commands and missions rather than expressed as one coherent harness policy. The repo has exact-tree verification proof (task-1335), handoff pre-checks, gatekeeper mandatory-artifact checks (gatekeeper.js), integration-time gates (ADR 0041), and a narrow auto-repair path (repair-handoff.js). It also has open work on shift-left verification (task-1268).
+
+What it does not yet have is one explicit answer to a repository-level question: **given a failed or incomplete agent handoff, which failure classes should auto-repair, which should auto-send-back to the implementer, and which genuinely require human intervention?**
+
+The current `repair-handoff.js` handles only two mechanical error classes (dirty mission artifacts, branch behind primary) and one relaunchable content error (empty goal-check table). All other failures — including genuine gate failures on code issues, the single largest consumer of human time — strand with a generic "not automatically repairable" message that requires manual re-invocation.
+
+This ADR consolidates the existing evidence, classifies the failure modes, and recommends a fully backlog-tracked implementation plan for fail-closed harness behavior. Nothing in the recommended control set is left as an untracked "defer later" idea: every control gets an explicit backlog task, even when the runtime outcome remains "human required".
+
+## Inputs
+
+This decision draws on four prior Parallix artifacts:
+
+1. **Task-1268** (`backlog/tasks/task-1268 - Shift-left.md`): Shift-left verification concept — run the verification gate mechanically before each review round, auto-bounce on failure without consuming a reviewer cycle. Key insight: the machinery exists (`captureVerifiedTreeProof` / `assertVerifiedTreeProof` in `lib/core/verification.js`), but enforcement before review rounds is missing.
+
+2. **Task-1335** (`backlog/completed/task-1335 - Harden-parallix-self-hosting-publish-path...md`): Exact-tree verification proof, implemented and completed. Established the principle that a verification proof must be tied to the exact tree being published — a green run from a different checkout, commit, or pre-squash state cannot satisfy the guard.
+
+3. **ADR 0041** (`docs/adr/0041-integration-pipeline-gates.md`): Integration-time pipeline gates with per-area dispatch, config-driven gate plan, and `--no-integration-gates` escape hatch. Established the pattern of gate execution before squash-merge.
+
+4. **ADR 0047** (`docs/adr/0047-per-mission-change-size-budget.md`): NEL budget with observational capture at handoff. Demonstrates the pattern of observational instrumentation without enforcement — a template for what NOT to do when enforcement is needed.
+
+## Inventory of Existing Checks
+
+The following checks are currently implemented across the harness lifecycle. Each is mapped to the failure class it catches.
+
+### Before Handoff
+
+| # | Check | Location | Failure Class |
+|---|-------|----------|---------------|
+| 1 | Verification gate at checkpoint | `lib/commands/checkpoint.js:44` | Unverifiable test claims (Class 1) |
+| 2 | Checkpoint existence validation | `lib/commands/active.js:386-391` | Missing artifacts (Class 3) |
+| 3 | Checkpoint committed check | `lib/commands/active.js:407-414` | Uncommitted state (Class 4) |
+
+### During Handoff
+
+| # | Check | Location | Failure Class |
+|---|-------|----------|---------------|
+| 4 | Mission branch verification | `lib/commands/handoff.js:37-39` | Git blockers (Class 5) |
+| 5 | MISSION.md existence | `lib/commands/handoff.js:42-44` | Missing artifacts (Class 3) |
+| 6 | MISSION.md uncommitted check | `lib/commands/handoff.js:96-99` | Uncommitted state (Class 4) |
+| 7 | Auto-checkpoint generation | `lib/commands/handoff.js:103-126` | Missing artifacts — auto-repair (Class 3) |
+| 8 | Goal Check heading validation | `lib/commands/handoff.js:141-147` | Incomplete evidence (Class 4) |
+| 9 | Goal Check evidence rows | `lib/commands/handoff.js:152-179` | Incomplete evidence (Class 4) |
+| 10 | Verification gate execution | `lib/commands/handoff.js:200-209` | Gate failure (Class 1, 6) |
+| 11 | Rebase onto primary | `lib/commands/handoff.js:214-229` | Git blockers (Class 5) |
+| 12 | Gatekeeper mandatory artifacts | `lib/commands/handoff.js:322-335` | Missing artifacts (Class 3) |
+| 13 | Declared gates execution | `lib/commands/handoff.js:429-480` | Gate failure (Class 2, 6) |
+
+### Before Review
+
+| # | Check | Location | Failure Class |
+|---|-------|----------|---------------|
+| 14 | Mission dir + branch + status | `lib/review/review-commands.js:367-401` | State violations (Class 8) |
+| 15 | PR existence and state | `lib/review/review-commands.js:403-430` | Infra blockers (Class 7) |
+| 16 | Verification gate | `lib/review/review-commands.js:438-445` | Gate failure (Class 1, 6) |
+
+### During Integration
+
+| # | Check | Location | Failure Class |
+|---|-------|----------|---------------|
+| 17 | Integration preflight | `lib/commands/integrate.js:500-504` | Multiple classes |
+| 18 | Integration gates | `lib/commands/integrate.js:507-534` | Gate failure (Class 6) |
+| 19 | Exact-tree proof capture | `lib/commands/integrate.js:742-749` | Unverifiable claims (Class 1) |
+| 20 | Exact-tree proof assertion | `lib/commands/integrate.js:753-757` | Stale proof (Class 1) |
+
+### Repair Path
+
+| # | Mechanism | Location | Coverage |
+|---|-----------|----------|----------|
+| 21 | Auto-commit mission artifacts | `lib/commands/repair-handoff.js:130-191` | Dirty mission files only (Class 5) |
+| 22 | Auto-rebase | `lib/commands/repair-handoff.js:194-223` | Simple rebase only (Class 5) |
+| 23 | Agent relaunch (empty goal-check) | `lib/commands/active.js:462-483` | Single error sub-class only (Class 4) |
+
+**Total: 23 check points across 5 lifecycle phases.**
+
+## Failure Classification
+
+Eight failure classes have been identified, each classified as auto-repair, auto-send-back, or human-only:
+
+| # | Failure Class | Proposed | Rationale |
+|---|---------------|----------|-----------|
+| 1 | Unverifiable "tests passed" claims | **Auto-send-back** | Gate exit code is deterministic; agent prose is never sufficient |
+| 2 | Malformed or non-runnable declared gates | **Auto-repair** | Static validation (file existence, syntax) can catch before execution |
+| 3 | Missing mandatory mission artifacts | **Auto-send-back** | Unambiguously the implementer's responsibility; no human judgment needed |
+| 4 | Incomplete checkpoint evidence | **Auto-send-back** | Agent-fixable content errors; fix prompt already exists for one sub-class |
+| 5 | Mechanical git/handoff blockers | **Auto-repair** (mission-only); **Human-only** (shared files) | Mission conflicts auto-resolvable; shared-file conflicts require judgment |
+| 6 | Genuine gate failure (code issues) | **Auto-send-back** | Gate output sufficient for agent to diagnose; highest-ROI improvement |
+| 7 | Forgejo/infra blockers | **Human-only** | No agent relaunch will fix infrastructure issues |
+| 8 | Task state machine violations | **Human-only** | State confusion requires human determination of correct state |
+
+## Decision Matrix: Candidate Harness Controls
+
+Seven candidate controls are evaluated and prioritized. The classification column answers backlog treatment, not runtime disposition: every control below is scheduled work with an explicit task.
+
+| # | Candidate Control | Complexity | ROI | Risk | Backlog Treatment |
+|---|-------------------|-----------|-----|------|-------------------|
+| C1 | Pre-review-round gate enforcement with auto-bounce | Medium | High | Low — gate machinery already exists; enforcement is the missing piece | **Implement now** (`TASK-1385`) |
+| C2 | Gate-failure auto-send-back with captured output | Low | High | Low — capture stdout/stderr, build fix prompt, relaunch with retry limit | **Implement now** (`TASK-1387`) |
+| C3 | Error classifier and dispatch table replacing generic strand | Medium | Medium | Low — refactor, not new behavior; existing repair-handoff.js is the seam | **Implement now** (`TASK-1389`) |
+| C4 | Declared-gate pre-validation (syntax + file existence) | Low | Medium | Low — static check before execution | **Implement next wave** (`TASK-1386`) |
+| C5 | Gatekeeper auto-send-back with agent relaunch | Low | Medium | Medium — must avoid relaunch loops when artifacts genuinely cannot be created | **Implement next wave** (`TASK-1388`) |
+| C6 | Forgejo/infrastructure blocker classification and operator handoff | Low | Low | Low — mostly classification and operator guidance, but still worth making explicit | **Implement next wave** (`TASK-1392`) |
+| C7 | Pre-review checkpoint evidence reference validation | Medium | Low | Medium — keep the check mechanical and avoid semantic-quality scoring | **Implement next wave** (`TASK-1393`) |
+
+### Implement Now (C1, C2, C3)
+
+**C1: Pre-review-round gate enforcement** (task-1268 / task-1385). Run the configured verification gate mechanically before each review round. On gate failure, auto-bounce to the implementer with the gate output as a fix prompt. No reviewer cycle consumed. This is the single highest-impact control because it closes the fail-open path where an agent can hand off with a green gate, receive review feedback, "fix" the code, and re-submit without the gate re-running.
+
+**C2: Gate-failure auto-send-back** (task-1387). When the verification gate fails at handoff time (`handoff.js:200-209`), capture the gate stdout/stderr, classify the error as "genuine gate failure — code issue", and relaunch the implementer with the captured output. Limit relaunch attempts to 2 to prevent infinite loops. This is the highest-ROI single control because it eliminates the most common human-intervention scenario: manually copying gate output and re-invoking the agent.
+
+**C3: Error classifier and dispatch table** (task-1389). Replace the binary `isRelaunchableError` / `isDirtyError` / `isBehind` classification in `repair-handoff.js` with a structured error classifier that maps each error message pattern to a failure class and a dispatch action (auto-repair, auto-send-back with prompt, or human-only with clear message). This is foundational work that makes C1 and C2 cleaner to implement.
+
+### Implement Next Wave (C4, C5, C6, C7)
+
+**C4: Declared-gate pre-validation** (`TASK-1386`). Validate that gate commands reference existing files and are syntactically valid before executing them. This stays after C1-C3 only because the earlier controls close larger fail-open paths first, not because C4 is optional.
+
+**C5: Gatekeeper auto-send-back** (`TASK-1388`). When gatekeeper detects missing mandatory artifacts and the task strands in `active`, auto-send-back to the implementer with explicit artifact creation instructions. The auto-checkpoint generation at `handoff.js:103-126` already covers one sub-case, but the remaining cases still deserve explicit automation and therefore explicit backlog tracking.
+
+**C6: Forgejo/infrastructure blocker classification and operator handoff** (`TASK-1392`). Label Forgejo and related infrastructure failures as "infrastructure — human required", preserve the existing runtime outcome, and make the operator message deterministic and actionable. Human-required runtime behavior is still harness work and therefore still gets a backlog task.
+
+**C7: Pre-review checkpoint evidence reference validation** (`TASK-1393`). Validate that checkpoint evidence rows cite real file:line references, ADR references, or test names rather than placeholder prose. The task must stay mechanical: it should verify reference shape and existence, not attempt to score evidence quality semantically.
+
+## Implementation Order
+
+```
+C3 (error classifier) → C2 (gate-failure send-back) → C1 (pre-review gate) → C4 → C5 → C6 → C7
+```
+
+C3 first because it provides the dispatch framework that C1 and C2 plug into. C2 before C1 because C2 is lower complexity and higher immediate ROI (handoff-time gate failures are already the blocking point; pre-review-round enforcement adds a new check point). C4-C7 remain sequenced backlog work rather than untracked ideas.
+
+## Consequences
+
+### Positive
+
+- The most common human-intervention scenario (copying gate output and re-invoking agent) is eliminated by C2
+- The fail-open path between review rounds is closed by C1 (task-1268)
+- Error handling moves from binary (repairable / not) to a classified dispatch table (C3)
+- Each failure class has an explicit owner (auto-repair, auto-send-back, or human)
+
+### Negative
+
+- Automatic relaunching (C2) increases compute cost per failed handoff (bounded by retry limit)
+- The error classifier (C3) adds a maintenance surface — new error patterns must be classified
+- Pre-review gate enforcement (C1) adds wall-time to each review round (bounded by gate duration)
+
+## See Also
+
+- Task-1268: Shift-left verification concept (backlog)
+- Task-1335: Exact-tree verification proof (completed)
+- ADR 0041: Integration pipeline gates
+- ADR 0047: NEL budget (observational pattern)
+- `lib/commands/repair-handoff.js`: Current repair path
+- `lib/commands/active.js:426-498`: Automated handoff-and-repair flow

package/docs/adr/index.md

@@ -17,5 +17,7 @@ ADR 0023 remains in WrGroceries and is cross-referenced here instead of copied.
 - `docs/adr/0046-npm-publish-process-and-security.md` — Adopt public npm registry publication for `@magnusekdahl/parallix` alongside the local tarball path; zero-dependency security posture, manual publish process, and rollback considerations
 - `docs/adr/0047-per-mission-change-size-budget.md` — Change the mission size-estimation basis from agent-usage % to **Net Engineering Lines (NEL)** — code+test diff, excluding docs and workflow/admin bookkeeping (the +0.65 reverse-causation confound). Draft estimate becomes a NEL bucket (0–80 / 81–235 / 235+, the empirical risk terciles); capture actual NEL at handoff to calibrate the estimate. No enforcement until the draft bucket is shown reliable.
 
+- `docs/adr/0048-fail-closed-harness-defense-against-agent-hallucinations.md` — Fail-closed harness defense against agent hallucinations: error classification, auto-send-back policy, and prioritized implementation plan for closing fail-open paths in the handoff/review/integrate lifecycle
+
 ## Cross-reference
 - `docs/adr/0023-ai-sdlc-configuration.md` remains in WrGroceries at `/home/magnus/code/visualBoard-task-1302/docs/adr/0023-ai-sdlc-configuration.md`.

package/docs/authority-reference.md

@@ -153,7 +153,7 @@ Complete when: mission reviewed, landing from the correct integration checkout,
 
 - **Config location:** `config/integration-pipelines.json`
 - **Schema:** `{"gates": {"<area>": {"command": "<shell-command>", "order": <number>, "run_last": <boolean>}}}`
-- **Supported areas:** `server`, `auth-server`, `web-client`, `web-e2e`
+- **Supported areas:** `lib`, `workflow`, `server`, `auth-server`, `web-client`, `web-e2e`, `docs`, `android`, `kubernetes`
 - **Ordering:** Gates are executed in ascending `order` value; `run_last: true` ensures the gate runs after all others (regardless of order value)
 - **Change detection:** Gates are only invoked for areas with changed files in the mission branch vs the primary branch
 - **Opt-out:** `px integrate <slug> --no-integration-gates` skips all integration gates
@@ -163,16 +163,19 @@ Example config:
 ```json
 {
   "gates": {
-    "server": {"command": "./server/updateStaging.sh", "order": 1, "run_last": false},
-    "auth-server": {"command": "./auth-server/updateStaging.sh", "order": 2, "run_last": false},
-    "web-client": {"command": "SKIP_E2E=1 ./web-client/updateStaging.sh", "order": 3, "run_last": false},
-    "web-e2e": {"command": "./web-client/scripts/run-playwright-stage.sh", "order": 4, "run_last": true}
+    "lib": {"command": "./scripts/verify-local.sh static-analysis", "order": 1, "run_last": false},
+    "workflow": {"command": "node test/e2e-mission-lifecycle.test.js", "order": 50, "run_last": true}
   }
 }
 ```
 
 If the config file is missing or empty, `px integrate` logs `integration-gates: no config present, skipping` and proceeds without error.
 
+In this repo, `workflow.config.json` points verification at `./scripts/verify-local.sh {{area}}`. That gives Parallix two validation layers:
+
+- earlier phases such as draft/active/review run the repo's fast general verifier (`all`, currently `npm test`)
+- `px integrate` invokes `verify-local.sh integrate`, which resolves the stricter integration gate plan from `config/integration-pipelines.json` after the target tree is exact
+
 ## 5. Checkpoint Model
 
 Each completed checkpoint must produce: (1) checkpoint doc under the configured mission base dir for the repo (`missions/<slug>/` in this repo), (2) non-generic `Next action:`, (3) passing relevant gate, (4) commit on `mission/<slug>`. Checkpoint docs make resume and handoff deterministic.

package/lib/agents/agents.js

@@ -51,6 +51,7 @@ exports.isInvalidAgentConfigError = isInvalidAgentConfigError;
 exports.updateAgentBlock = updateAgentBlock;
 exports.resolveBlocklistTargetPath = resolveBlocklistTargetPath;
 exports.resolveNoOutputWatchdogConfig = resolveNoOutputWatchdogConfig;
+exports.shouldPersistLaunchFailureBlock = shouldPersistLaunchFailureBlock;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
@@ -63,9 +64,11 @@ const limit_hit_js_1 = require("./limit-hit.js");
 const storage = __importStar(require("../core/storage.js"));
 const product_config_js_1 = require("../core/product-config.js");
 const persistent_data_migration_js_1 = require("../core/persistent-data-migration.js");
+const node_module_1 = require("node:module");
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = (0, node_module_1.createRequire)(__filename);
+const sessions = _require('../tools/sessions');
 // Launchers whose CLI accepts a per-call resume flag threaded by startAgent.
 // Each launcher outputs a session resume hint at the end of its run (e.g.
 // "codex resume <id>", "opencode -s ses_<id>",
@@ -107,6 +110,17 @@ const KNOWN_AGENT_NAMES = Object.freeze([
     'human'
 ]);
 exports.KNOWN_AGENT_NAMES = KNOWN_AGENT_NAMES;
+const NON_BLOCKING_LAUNCH_ERROR_PATTERNS = Object.freeze([
+    /\b(?:invalid|unknown|unsupported|unrecognized)\s+model\b/i,
+    /\bmodel\s+(?:identifier|id)\s+(?:is\s+)?invalid\b/i,
+    /\b(?:model\s+not\s+found|no\s+such\s+model)\b/i,
+    /\bunknown\s+option\b/i,
+    /\bauth(?:entication)?\b/i,
+    /\bunauthorized\b/i,
+    /\bforbidden\b/i,
+    /\bapi\s+key\b/i,
+    /\bread-only file system\b/i
+]);
 function workflowLauncherStatus(agent) {
     const resolver = RESOLVERS[agent];
     if (!resolver) {
@@ -148,6 +162,21 @@ function commandInPath(name) {
     });
     return result.status === 0 && result.stdout.trim().length > 0;
 }
+function shouldPersistLaunchFailureBlock(agent, result) {
+    if (!result || agent === 'custom') {
+        return false;
+    }
+    const combined = [
+        result.stderr || '',
+        result.stdout || '',
+        result.error?.message || '',
+        result.error?.code || ''
+    ].join('\n');
+    if (!combined.trim()) {
+        return true;
+    }
+    return !NON_BLOCKING_LAUNCH_ERROR_PATTERNS.some(pattern => pattern.test(combined));
+}
 function buildInvalidAgentConfigError(configPath, scope, originalError) {
     const location = node_path_1.default.resolve(configPath);
     const detail = originalError && originalError.message ? originalError.message : 'invalid JSON';
@@ -790,10 +819,10 @@ async function startAgent(step, opts = { prompt: '' }) {
             });
             tried.add(chosen || '');
             launched.add(chosen || '');
-            // Block non-custom agents on non-limit failures so selectAgent excludes them
-            // on the next retry iteration, and the review-loop fallback path can activate.
-            // custom (opencode/local AI) is excluded — exit 1 is a temporary local error.
-            if (chosen !== 'custom') {
+            // Block retry candidates only when the failure looks transient. Deterministic
+            // setup/config errors (invalid model id, auth failure, read-only HOME, etc.)
+            // should fall through to the next family without poisoning agents.local.json.
+            if (shouldPersistLaunchFailureBlock(chosen || '', result)) {
                 const blockUntil = (0, limit_hit_js_1.formatBlockUntil)(new Date(Date.now() + limit_hit_js_1.DEFAULT_FALLBACK_HOURS * 60 * 60 * 1000));
                 try {
                     const blockResult = updateAgentBlockFn(chosen || '', blockUntil);
@@ -803,6 +832,9 @@ async function startAgent(step, opts = { prompt: '' }) {
                     log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${err.message}`));
                 }
             }
+            else {
+                log(fmt.status('INFO', `Skipping blocklist write for ${fmt.agent(chosen || '')}; launch failure looks like a deterministic config/setup error.`));
+            }
             chosen = undefined;
             continue;
         }

package/lib/agents/agents.ts

@@ -10,9 +10,11 @@ import { detectLimitHit, formatBlockUntil, DEFAULT_FALLBACK_HOURS } from './limi
 import * as storage from '../core/storage.js';
 import { resolveAgentModel } from '../core/product-config.js';
 import { migrateAgentBlocklists } from '../core/persistent-data-migration.js';
+import { createRequire } from 'node:module';
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = createRequire(__filename);
+const sessions = _require('../tools/sessions');
 
 interface LauncherStatus {
   agent: string;
@@ -22,6 +24,14 @@ interface LauncherStatus {
   reason?: string;
 }
 
+interface LaunchResultLike {
+  stdout?: string;
+  stderr?: string;
+  status?: number | null;
+  signal?: string | null;
+  error?: {code?: string, message?: string} | null;
+}
+
 type AgentConfig = { blocklist?: {[key: string]: any}, steps?: {[key: string]: any} };
 
 interface StartAgentOptions {
@@ -100,6 +110,18 @@ const KNOWN_AGENT_NAMES = Object.freeze([
   'human'
 ]);
 
+const NON_BLOCKING_LAUNCH_ERROR_PATTERNS = Object.freeze([
+  /\b(?:invalid|unknown|unsupported|unrecognized)\s+model\b/i,
+  /\bmodel\s+(?:identifier|id)\s+(?:is\s+)?invalid\b/i,
+  /\b(?:model\s+not\s+found|no\s+such\s+model)\b/i,
+  /\bunknown\s+option\b/i,
+  /\bauth(?:entication)?\b/i,
+  /\bunauthorized\b/i,
+  /\bforbidden\b/i,
+  /\bapi\s+key\b/i,
+  /\bread-only file system\b/i
+]);
+
 function workflowLauncherStatus(agent: string): LauncherStatus {
   const resolver = RESOLVERS[agent];
   if (!resolver) {
@@ -146,6 +168,18 @@ function commandInPath(name: string) {
   return result.status === 0 && result.stdout.trim().length > 0;
 }
 
+function shouldPersistLaunchFailureBlock(agent: string, result: LaunchResultLike | null | undefined) {
+  if (!result || agent === 'custom') {return false;}
+  const combined = [
+    result.stderr || '',
+    result.stdout || '',
+    result.error?.message || '',
+    result.error?.code || ''
+  ].join('\n');
+  if (!combined.trim()) {return true;}
+  return !NON_BLOCKING_LAUNCH_ERROR_PATTERNS.some(pattern => pattern.test(combined));
+}
+
 function buildInvalidAgentConfigError(configPath: string, scope: string, originalError: {message?: string} | null) {
   const location = path.resolve(configPath);
   const detail = originalError && originalError.message ? originalError.message : 'invalid JSON';
@@ -869,10 +903,10 @@ async function startAgent(step: string, opts: StartAgentOptions = { prompt: '' }
       });
       tried.add(chosen || '');
       launched.add(chosen || '');
-      // Block non-custom agents on non-limit failures so selectAgent excludes them
-      // on the next retry iteration, and the review-loop fallback path can activate.
-      // custom (opencode/local AI) is excluded — exit 1 is a temporary local error.
-      if (chosen !== 'custom') {
+      // Block retry candidates only when the failure looks transient. Deterministic
+      // setup/config errors (invalid model id, auth failure, read-only HOME, etc.)
+      // should fall through to the next family without poisoning agents.local.json.
+      if (shouldPersistLaunchFailureBlock(chosen || '', result)) {
         const blockUntil = formatBlockUntil(new Date(Date.now() + DEFAULT_FALLBACK_HOURS * 60 * 60 * 1000));
         try {
           const blockResult = updateAgentBlockFn(chosen || '', blockUntil);
@@ -880,6 +914,8 @@ async function startAgent(step: string, opts: StartAgentOptions = { prompt: '' }
         } catch (err) {
           log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${(err as any).message}`));
         }
+      } else {
+        log(fmt.status('INFO', `Skipping blocklist write for ${fmt.agent(chosen || '')}; launch failure looks like a deterministic config/setup error.`));
       }
       chosen = undefined;
       continue;
@@ -926,5 +962,6 @@ export {
   isInvalidAgentConfigError,
   updateAgentBlock,
   resolveBlocklistTargetPath,
-  resolveNoOutputWatchdogConfig
+  resolveNoOutputWatchdogConfig,
+  shouldPersistLaunchFailureBlock
 };

package/lib/agents/claude.js

@@ -10,9 +10,11 @@ exports.__setSessionsForTest = __setSessionsForTest;
 const spawn_tee_js_1 = require("../core/spawn-tee.js");
 const claude_telemetry_js_1 = require("./claude-telemetry.js");
 Object.defineProperty(exports, "extractClaudeTelemetryFromStdout", { enumerable: true, get: function () { return claude_telemetry_js_1.extractClaudeTelemetryFromStdout; } });
+const node_module_1 = require("node:module");
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = (0, node_module_1.createRequire)(__filename);
+const sessions = _require('../tools/sessions');
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
 let _spawnAndTee = spawn_tee_js_1.spawnAndTee;
 let _sessions = sessions;

package/lib/agents/claude.ts

@@ -1,8 +1,10 @@
 import { spawnAndTee } from '../core/spawn-tee.js';
 import { extractClaudeTelemetryFromStdout } from './claude-telemetry.js';
+import { createRequire } from 'node:module';
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = createRequire(__filename);
+const sessions = _require('../tools/sessions');
 
 interface ClaudeInvocationOptions {
   prompt: string;

package/lib/agents/codex.js

@@ -21,9 +21,11 @@ const node_path_1 = __importDefault(require("node:path"));
 const spawn_tee_js_1 = require("../core/spawn-tee.js");
 const codex_telemetry_js_1 = require("./codex-telemetry.js");
 Object.defineProperty(exports, "extractCodexTelemetry", { enumerable: true, get: function () { return codex_telemetry_js_1.extractCodexTelemetry; } });
+const node_module_1 = require("node:module");
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = (0, node_module_1.createRequire)(__filename);
+const sessions = _require('../tools/sessions');
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
 let _spawnAndTee = spawn_tee_js_1.spawnAndTee;
 let _sessions = sessions;

package/lib/agents/codex.ts

@@ -3,9 +3,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnAndTee } from '../core/spawn-tee.js';
 import { extractCodexTelemetry } from './codex-telemetry.js';
+import { createRequire } from 'node:module';
 // tools/sessions is still CJS (not converted in this wave); require keeps it
 // untyped (any) without pulling a non-included .js into the typecheck program.
-const sessions = require('../tools/sessions');
+const _require = createRequire(__filename);
+const sessions = _require('../tools/sessions');
 
 interface CodexInvocationOptions {
   prompt: string;

package/lib/agents/opencode.js

@@ -17,11 +17,13 @@ const spawn_tee_js_1 = require("../core/spawn-tee.js");
 const opencode_telemetry_js_1 = require("./opencode-telemetry.js");
 const opencode_export_js_1 = require("./opencode-export.js");
 const limit_hit_js_1 = require("./limit-hit.js");
+const node_module_1 = require("node:module");
 // tools/sessions and core/subagent-limit are still CJS (not converted in this
 // wave); require keeps them untyped (any) without pulling non-included .js into
 // the typecheck program.
-const sessions = require('../tools/sessions');
-const { buildSubagentLimitPrefix } = require('../core/subagent-limit');
+const _require = (0, node_module_1.createRequire)(__filename);
+const sessions = _require('../tools/sessions');
+const { buildSubagentLimitPrefix } = _require('../core/subagent-limit');
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
 let _spawnAndTee = spawn_tee_js_1.spawnAndTee;
 let _captureExport = opencode_export_js_1.captureOpencodeExport;
@@ -93,7 +95,7 @@ function checkJsonFormatSupport() {
         return _jsonFormatSupported;
     }
     try {
-        const { spawnSync } = require('node:child_process');
+        const { spawnSync } = _require('node:child_process');
         const result = spawnSync('opencode', ['--format', 'json', '--help'], {
             timeout: 3000,
             stdio: ['ignore', 'pipe', 'pipe'],

package/lib/agents/opencode.ts

@@ -2,11 +2,13 @@ import { spawnAndTee } from '../core/spawn-tee.js';
 import { extractOpencodeTelemetryFromExport } from './opencode-telemetry.js';
 import { captureOpencodeExport } from './opencode-export.js';
 import { detectLimitHit } from './limit-hit.js';
+import { createRequire } from 'node:module';
 // tools/sessions and core/subagent-limit are still CJS (not converted in this
 // wave); require keeps them untyped (any) without pulling non-included .js into
 // the typecheck program.
-const sessions = require('../tools/sessions');
-const { buildSubagentLimitPrefix } = require('../core/subagent-limit');
+const _require = createRequire(__filename);
+const sessions = _require('../tools/sessions');
+const { buildSubagentLimitPrefix } = _require('../core/subagent-limit');
 
 interface BuildOpencodeInvocationOptions {
   prompt: string;
@@ -105,7 +107,7 @@ function checkJsonFormatSupport() {
     return _jsonFormatSupported;
   }
   try {
-    const { spawnSync } = require('node:child_process');
+    const { spawnSync } = _require('node:child_process');
     const result = spawnSync('opencode', ['--format', 'json', '--help'], {
       timeout: 3000,
       stdio: ['ignore', 'pipe', 'pipe'],

package/lib/commands/active.js

@@ -32,12 +32,26 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.active = void 0;
+exports.buildExecutePrompt = buildExecutePrompt;
+exports.buildCheckpointContext = buildCheckpointContext;
+exports.runHandoffAndReview = runHandoffAndReview;
+exports.applyExecuteFallback = applyExecuteFallback;
+exports.selectLaunchAndRecord = selectLaunchAndRecord;
+exports.validateCheckpointsBeforeHandoff = validateCheckpointsBeforeHandoff;
+exports.attemptAgentRelaunch = attemptAgentRelaunch;
+exports.enforceExecuteCommitSafety = enforceExecuteCommitSafety;
+exports.unquoteGitStatusPath = unquoteGitStatusPath;
 // @ts-nocheck
 const git_js_1 = require("../core/git.js");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const fmt = __importStar(require("../core/fmt.js"));
-const missionStart = __importStar(require("./mission-start.js"));
+const mission_start_js_1 = __importDefault(require("./mission-start.js"));
 const agents = __importStar(require("../agents/agents.js"));
 const mission_utils_js_1 = require("../core/mission-utils.js");
 const handoff = __importStar(require("./handoff.js"));
@@ -53,7 +67,7 @@ const EXECUTE_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'execute
  * @param {{inferSlugFn?: Function, missionStartFn?: Function, resolveWorktreeFn?: Function, readAgentConfigOrExitFn?: Function, resolveTaskFileFn?: Function, buildCheckpointContextFn?: Function, buildExecutePromptFn?: Function, selectLaunchAndRecordFn?: Function, enforceExecuteCommitSafetyFn?: Function, runHandoffAndReviewFn?: Function, exitFn?: Function, logFn?: Function, errorFn?: Function}} [options]
  */
 async function active(args, options = {}) {
-    const { inferSlugFn = mission_utils_js_1.inferSlug, missionStartFn = missionStart, resolveWorktreeFn = mission_utils_js_1.resolveWorktree, readAgentConfigOrExitFn = agents.readAgentConfigOrExit, resolveTaskFileFn = backlog_js_1.resolveTaskFile, buildCheckpointContextFn = buildCheckpointContext, buildExecutePromptFn = buildExecutePrompt, selectLaunchAndRecordFn = selectLaunchAndRecord, enforceExecuteCommitSafetyFn = enforceExecuteCommitSafety, runHandoffAndReviewFn = runHandoffAndReview, exitFn = process.exit, logFn = fmt.log.info, errorFn = fmt.log.fail } = options;
+    const { inferSlugFn = mission_utils_js_1.inferSlug, missionStartFn = mission_start_js_1.default, resolveWorktreeFn = mission_utils_js_1.resolveWorktree, readAgentConfigOrExitFn = agents.readAgentConfigOrExit, resolveTaskFileFn = backlog_js_1.resolveTaskFile, buildCheckpointContextFn = buildCheckpointContext, buildExecutePromptFn = buildExecutePrompt, selectLaunchAndRecordFn = selectLaunchAndRecord, enforceExecuteCommitSafetyFn = enforceExecuteCommitSafety, runHandoffAndReviewFn = runHandoffAndReview, exitFn = process.exit, logFn = fmt.log.info, errorFn = fmt.log.fail } = options;
     const explicitSlug = args[0];
     const slug = inferSlugFn(explicitSlug);
     if (!slug) {
@@ -591,4 +605,8 @@ function enforceExecuteCommitSafety(opts) {
 }
 /** @type {typeof active & {buildExecutePrompt: typeof buildExecutePrompt, buildCheckpointContext: typeof buildCheckpointContext, runHandoffAndReview: typeof runHandoffAndReview, applyExecuteFallback: typeof applyExecuteFallback, selectLaunchAndRecord: typeof selectLaunchAndRecord, validateCheckpointsBeforeHandoff: typeof validateCheckpointsBeforeHandoff, attemptAgentRelaunch: typeof attemptAgentRelaunch, enforceExecuteCommitSafety: typeof enforceExecuteCommitSafety, unquoteGitStatusPath: typeof unquoteGitStatusPath}} */
 const _activeExport = Object.assign(active, { buildExecutePrompt, buildCheckpointContext, runHandoffAndReview, applyExecuteFallback, selectLaunchAndRecord, validateCheckpointsBeforeHandoff, attemptAgentRelaunch, enforceExecuteCommitSafety, unquoteGitStatusPath });
-module.exports = _activeExport;
+exports.active = _activeExport;
+exports.default = _activeExport;
+if (typeof module !== 'undefined') {
+    module.exports = _activeExport;
+}

package/lib/commands/active.ts

@@ -3,7 +3,7 @@ import { git, getWorktreeStatus } from '../core/git.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as fmt from '../core/fmt.js';
-import * as missionStart from './mission-start.js';
+import missionStart from './mission-start.js';
 import * as agents from '../agents/agents.js';
 import { findMissionDir, findCheckpoints, getFirstLine, resolveWorktree, inferSlug, getMissionYear, missionDirForSlug, isWorkflowGeneratedArtifact } from '../core/mission-utils.js';
 import * as handoff from './handoff.js';
@@ -662,4 +662,9 @@ function enforceExecuteCommitSafety(opts) {
 
 /** @type {typeof active & {buildExecutePrompt: typeof buildExecutePrompt, buildCheckpointContext: typeof buildCheckpointContext, runHandoffAndReview: typeof runHandoffAndReview, applyExecuteFallback: typeof applyExecuteFallback, selectLaunchAndRecord: typeof selectLaunchAndRecord, validateCheckpointsBeforeHandoff: typeof validateCheckpointsBeforeHandoff, attemptAgentRelaunch: typeof attemptAgentRelaunch, enforceExecuteCommitSafety: typeof enforceExecuteCommitSafety, unquoteGitStatusPath: typeof unquoteGitStatusPath}} */
 const _activeExport = Object.assign(active, { buildExecutePrompt, buildCheckpointContext, runHandoffAndReview, applyExecuteFallback, selectLaunchAndRecord, validateCheckpointsBeforeHandoff, attemptAgentRelaunch, enforceExecuteCommitSafety, unquoteGitStatusPath });
-export = _activeExport;
+export default _activeExport;
+export { _activeExport as active, buildExecutePrompt, buildCheckpointContext, runHandoffAndReview, applyExecuteFallback, selectLaunchAndRecord, validateCheckpointsBeforeHandoff, attemptAgentRelaunch, enforceExecuteCommitSafety, unquoteGitStatusPath };
+
+// CJS compat: ensure require() returns the function directly
+declare const module: { exports: any } | undefined;
+if (typeof module !== 'undefined') { module.exports = _activeExport; }

package/lib/commands/config.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = config;
 const fmt = __importStar(require("../core/fmt.js"));
 const product_config_js_1 = require("../core/product-config.js");
 // `node parallix config` — read-only. Prints the effective configuration:
@@ -68,4 +70,7 @@ async function config(_args = [], opts = {}) {
     }
     logFn(JSON.stringify((0, product_config_js_1.loadEffectiveConfig)(rootDir), null, 2));
 }
-module.exports = config;
+exports.default = config;
+if (typeof module !== 'undefined') {
+    module.exports = config;
+}

package/lib/commands/config.ts

@@ -44,4 +44,9 @@ async function config(_args: string[] = [], opts: ConfigOptions = {}) {
   logFn(JSON.stringify(loadEffectiveConfig(rootDir), null, 2));
 }
 
-export = config;
+export default config;
+export { config };
+
+// CJS compat: ensure require() returns the function directly
+declare const module: { exports: any } | undefined;
+if (typeof module !== 'undefined') { module.exports = config; }