claude-dev-env 2.3.0 → 2.4.0

package/skills/autoconverge/workflow/converge.codex-gate.test.mjs

@@ -178,7 +178,118 @@ test('the Codex gate prompt runs the review wrapper against the PR base branch',
   assert.match(codexPrompt, /parse_codex_findings/, 'expected findings to come from the shared parser');
 });
 
-test('the CODEX phase stamps codexCleanAt on clean and clears it on skip/down', () => {
+test('the Codex gate prompt passes an explicit generous timeout so a slow-but-healthy review is not cut short', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /timeout_seconds=\$\{CONFIG\.codexReviewTimeoutSeconds\}/,
+    'expected the driver to pass CONFIG.codexReviewTimeoutSeconds, overriding the too-small wrapper default',
+  );
+});
+
+test('CONFIG.codexReviewTimeoutSeconds exceeds the observed real Codex runtime', () => {
+  const match = convergeSource.match(/codexReviewTimeoutSeconds:\s*(\d+)/);
+  assert.notEqual(match, null, 'expected CONFIG.codexReviewTimeoutSeconds to be defined');
+  const budgetSeconds = Number(match[1]);
+  assert.ok(
+    budgetSeconds >= 900,
+    `expected a budget comfortably above the ~683s measured Codex runtime, got ${budgetSeconds}`,
+  );
+});
+
+test('the Codex gate prompt runs the review in the background rather than the default foreground timeout', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /run_in_background/i,
+    'expected the review driver to run in the background — the foreground tool timeout caps below the review runtime and would kill a healthy review',
+  );
+  assert.match(
+    codexPrompt,
+    /result file/i,
+    'expected the driver to persist its outcome to a result file the agent reads once the background run finishes',
+  );
+});
+
+test('the Codex gate prompt waits for the background review inside the same turn with a bounded Monitor loop', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(codexPrompt, /Monitor tool/, 'expected a same-turn Monitor wait for the background review');
+  assert.match(codexPrompt, /until-loop/, 'expected a bounded until-loop that re-checks the result file');
+  assert.match(codexPrompt, /codexReviewPollIntervalSeconds/, 'expected a named poll interval in the wait protocol');
+  assert.match(codexPrompt, /codexReviewMaxPolls/, 'expected a named attempt budget in the wait protocol');
+  assert.match(
+    codexPrompt,
+    /Do NOT end this turn/i,
+    'expected an explicit instruction against ending the schema-bearing turn to await the background run',
+  );
+});
+
+test('the Codex background-review poll budget covers the review timeout', () => {
+  const intervalMatch = convergeSource.match(/codexReviewPollIntervalSeconds:\s*(\d+)/);
+  const pollsMatch = convergeSource.match(/codexReviewMaxPolls:\s*(\d+)/);
+  const timeoutMatch = convergeSource.match(/codexReviewTimeoutSeconds:\s*(\d+)/);
+  assert.notEqual(intervalMatch, null, 'expected codexReviewPollIntervalSeconds in CONFIG');
+  assert.notEqual(pollsMatch, null, 'expected codexReviewMaxPolls in CONFIG');
+  assert.notEqual(timeoutMatch, null, 'expected codexReviewTimeoutSeconds in CONFIG');
+  const intervalSeconds = Number(intervalMatch[1]);
+  const maxPolls = Number(pollsMatch[1]);
+  const timeoutSeconds = Number(timeoutMatch[1]);
+  assert.ok(
+    intervalSeconds * maxPolls >= timeoutSeconds,
+    `expected the poll budget ${intervalSeconds * maxPolls}s to cover the ${timeoutSeconds}s review timeout`,
+  );
+});
+
+test('the Codex gate prompt returns codex_down when the background poll budget is spent', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /full poll budget is spent with no result file[\s\S]*?down:true/,
+    'expected a spent-budget branch that returns the codex_down schema shape',
+  );
+});
+
+test('meta Codex gate phase describes codex_down as a non-blocking skip that logs a note', () => {
+  const phaseStart = convergeSource.indexOf("title: 'Codex gate'");
+  const phaseEnd = convergeSource.indexOf("title: 'Finalize'");
+  assert.notEqual(phaseStart, -1, 'expected a Codex gate phase in meta');
+  const codexPhaseDetail = convergeSource.slice(phaseStart, phaseEnd);
+  assert.match(codexPhaseDetail, /codex_down/, 'expected the phase detail to name codex_down');
+  assert.match(
+    codexPhaseDetail,
+    /codex_down, the gate skips without blocking/,
+    'expected codex_down to be described as a non-blocking skip',
+  );
+  assert.match(
+    codexPhaseDetail,
+    /logged as a note/,
+    'expected the codex_down skip to be logged as a note so the bypass stays visible',
+  );
+  assert.doesNotMatch(
+    codexPhaseDetail,
+    /holds the PR as a draft with a codex-down blocker/,
+    'codex_down must not be described as holding the PR draft with a blocker',
+  );
+});
+
+test('CODEX_SCHEMA down.description describes codex_down as a skipped, bypassed gate recorded as a note', () => {
+  const schemaStart = convergeSource.indexOf('const CODEX_SCHEMA =');
+  const schemaEnd = convergeSource.indexOf('const COPILOT_VERIFY_VERDICTS =');
+  assert.notEqual(schemaStart, -1, 'expected CODEX_SCHEMA to exist');
+  const schemaSource = convergeSource.slice(schemaStart, schemaEnd);
+  const downLineStart = schemaSource.indexOf('down: {');
+  const downLine = schemaSource.slice(downLineStart, schemaSource.indexOf('\n', downLineStart));
+  assert.match(downLine, /codex_down/, 'expected the down description to name codex_down');
+  assert.match(downLine, /skipped and bypassed/, 'expected codex_down to be described as a skipped, bypassed gate');
+  assert.match(downLine, /recorded as a note/, 'expected codex_down to be recorded as a note');
+  assert.doesNotMatch(
+    downLine,
+    /holds the PR as a draft with a codex-down blocker/,
+    'the down description must not claim codex_down holds the PR draft as a blocker',
+  );
+});
+
+test('the CODEX phase stamps codexCleanAt on clean and clears it on an opt-out, usage, or down skip', () => {
   const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
   const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
   assert.notEqual(codexPhaseStart, -1, 'expected a CODEX phase block');
@@ -192,6 +303,36 @@ test('the CODEX phase stamps codexCleanAt on clean and clears it on skip/down',
   assert.match(codexPhase, /kind === 'down'[\s\S]*codexDown = true[\s\S]*codexCleanAt = null/);
 });
 
+test('the CODEX phase skips a genuine codex_down gracefully, recording a note and advancing to mark-ready', () => {
+  const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
+  const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
+  const codexPhase = convergeSource.slice(codexPhaseStart, finalizePhaseStart);
+  const downBranchStart = codexPhase.indexOf("codexOutcome.kind === 'down'");
+  const downBranchEnd = codexPhase.indexOf("codexOutcome.kind === 'fix'", downBranchStart);
+  assert.notEqual(downBranchStart, -1, 'expected a codex_down branch in the CODEX phase');
+  assert.notEqual(downBranchEnd, -1, 'expected a fix branch after the down branch');
+  const downBranch = codexPhase.slice(downBranchStart, downBranchEnd);
+  assert.match(downBranch, /codexNote =/, 'a genuine codex_down records a transparent note');
+  assert.match(downBranch, /codexDown = true/, 'the down branch sets the bypass flag so mark-ready skips the required Codex gate');
+  assert.match(downBranch, /codexCleanAt = null/, 'the down branch clears any codex-clean stamp');
+  assert.match(
+    downBranch,
+    /phase = 'FINALIZE'/,
+    'a genuine codex_down advances to mark-ready with the gate bypassed rather than blocking the run',
+  );
+  assert.doesNotMatch(downBranch, /blocker =/, 'a genuine codex_down must not record a blocker');
+  assert.doesNotMatch(downBranch, /\bbreak\b/, 'the down branch continues rather than breaking the loop');
+});
+
+test('the workflow return object includes codexNote so the final report surfaces the Codex skip', () => {
+  const assembleStart = convergeSource.indexOf('const assembleResult =');
+  assert.notEqual(assembleStart, -1, 'expected assembleResult to exist');
+  const assembleEnd = convergeSource.indexOf('})', assembleStart);
+  assert.notEqual(assembleEnd, -1, 'expected the assembleResult object to close');
+  const assembleSource = convergeSource.slice(assembleStart, assembleEnd);
+  assert.match(assembleSource, /codexNote,/, 'expected codexNote among the returned notes');
+});
+
 test('the CODEX phase routes findings through applyFixes and re-enters CONVERGE', () => {
   const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
   const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
@@ -267,8 +408,8 @@ test('runConvergenceCheck tells the finalize agent to persist codex_clean_at for
 test('CONFIG expands home for the codex-review scripts directory', () => {
   assert.match(
     convergeSource,
-    /const homeDirectory = \(process\.env\.HOME \|\| process\.env\.USERPROFILE/,
-    'expected home to be resolved from process.env before CONFIG path use',
+    /const homeDirectory = \([\s\S]*?homeDirectoryPayload\.homeDirectory/,
+    'expected home to be sourced from the workflow args payload (the sandbox exposes no process)',
   );
   assert.match(
     convergeSource,
@@ -282,6 +423,25 @@ test('CONFIG expands home for the codex-review scripts directory', () => {
   );
 });
 
+test('no process global is read unguarded (the workflow sandbox exposes no process)', () => {
+  const unguardedProcessLines = convergeSource
+    .split('\n')
+    .filter((sourceLine) => sourceLine.includes('process.') && !sourceLine.includes('typeof process'));
+  assert.deepEqual(
+    unguardedProcessLines,
+    [],
+    'every process.* read must sit on a line guarded by typeof process; the Bun workflow sandbox has no process global',
+  );
+});
+
+test('the home directory is sourced from the workflow args payload', () => {
+  assert.match(
+    convergeSource,
+    /const homeDirectoryPayload = normalizeRunInput\(args\)/,
+    'expected homeDirectory to read args (the only channel into the process-less sandbox), parsed via normalizeRunInput',
+  );
+});
+
 test('meta lists the Codex gate phase between Copilot and Finalize', () => {
   const copilotPhaseIndex = convergeSource.indexOf("title: 'Copilot gate'");
   const codexPhaseIndex = convergeSource.indexOf("title: 'Codex gate'");
@@ -294,6 +454,18 @@ test('SKILL.md names Codex among the terminal confirmation gates', () => {
   assert.match(skillSource, /Codex/i);
 });
 
+test('SKILL.md documents codexNote in the workflow return shape', () => {
+  const returnShapeMatch = skillSource.match(/`\{ converged, rounds, finalSha, blocker,[^`]*\}`/);
+  assert.ok(returnShapeMatch, 'expected the documented return shape literal in SKILL.md');
+  assert.match(returnShapeMatch[0], /codexNote/);
+});
+
+test('SKILL.md final-report template surfaces the codexNote so a bypassed Codex gate stays visible', () => {
+  const reportBlockMatch = skillSource.match(/\/autoconverge exit:[\s\S]*?```/);
+  assert.ok(reportBlockMatch, 'expected the final-report template block in SKILL.md');
+  assert.match(reportBlockMatch[0], /Codex: <codexNote>/);
+});
+
 test('stop-conditions.md documents the Codex gate skip paths as non-blockers', () => {
   assert.match(stopConditionsSource, /Codex/i);
   assert.match(stopConditionsSource, /codex/i);

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -815,6 +815,25 @@ test('preamble attributes the known-temp-var resolution to a third cwd-scoped au
   );
 });
 
+test('preamble forbids bash rm on a repo-path build cache and points cleanup at Remove-Item', () => {
+  const text = preambleText().replace(/\s+/g, ' ');
+  assert.match(
+    text,
+    /\.mypy_cache|\.pytest_cache|__pycache__/,
+    'expected the preamble to name a gitignored build cache agents must not rm',
+  );
+  assert.match(
+    text,
+    /never delete it|leave it in place/i,
+    'expected the preamble to tell agents to leave a gitignored cache rather than rm it',
+  );
+  assert.match(
+    text,
+    /Remove-Item -Recurse -Force -Confirm:\$false/,
+    'expected the preamble to point a genuine delete at the PowerShell Remove-Item form',
+  );
+});
+
 test('SKILL.md does not attribute the known-temp-var resolution to the standalone or compound paths', () => {
   assert.doesNotMatch(
     skillSource.replace(/\s+/g, ' '),

package/skills/autoconverge/workflow/converge.mjs

@@ -18,17 +18,28 @@ export const meta = {
     { title: 'Converge', detail: 'A deterministic static sweep runs first each round; then code-review, bug-audit, and self-review run in parallel on the same HEAD; one clean-coder applies all fixes; the loop repeats until every lens is clean on a stable HEAD' },
     { title: 'Bugbot gate', detail: 'A terminal confirmation gate that runs once the internal lenses are clean; when Bugbot is disabled or unavailable it spawns no agent and passes, otherwise it fetches Bugbot\'s verdict and routes any finding back into Converge' },
     { title: 'Copilot gate', detail: 'When the quota pre-check reports Copilot out of premium-request quota or unavailable, skip the gate with no agent spawned; otherwise request a Copilot review and poll up to the configured cap, then route findings by tier — self-healing findings flow back into Converge, and each code-concern finding goes to its own verifier agent that must execute a check against HEAD: a confirmed finding (defect reproduced by a run command) joins the fix round carrying its repro, a refuted finding (correct behavior demonstrated by a run command) is replied-to and resolved with the check evidence, and only inconclusive findings return blocker user-review for the orchestrator to gate on rather than auto-fixing or marking the PR ready; when Copilot is down or out of quota log a notice and proceed with the gate bypassed' },
-    { title: 'Codex gate', detail: 'A conditional-required terminal gate that runs after Bugbot and Copilot: when CLAUDE_REVIEWS_DISABLED lists codex, when weekly usage is at or below the shared probe threshold (or null), or when the wrapper classifies codex_down, the gate skips without blocking; when usage is above the threshold it runs the codex-review wrapper against the PR base branch, routes findings into the fix path, and on a clean pass records the codex-clean HEAD for the convergence check' },
+    { title: 'Codex gate', detail: 'A conditional-required terminal gate that runs after Bugbot and Copilot: when CLAUDE_REVIEWS_DISABLED lists codex, when weekly usage is at or below the shared probe threshold (or null), or when the wrapper classifies codex_down, the gate skips without blocking (a codex_down skip is logged as a note so the bypass stays visible); when usage is above the threshold it runs the codex-review wrapper against the PR base branch, routes findings into the fix path, and on a clean pass records the codex-clean HEAD for the convergence check' },
     { title: 'Finalize', detail: 'Run check_convergence.py; mark draft=false on a full pass' },
   ],
 }
 
-const homeDirectory = (process.env.HOME || process.env.USERPROFILE || '').replace(/\\/g, '/')
+const homeDirectoryPayload = normalizeRunInput(args)
+const homeDirectoryFromEnv = typeof process !== 'undefined' && process.env ? process.env.HOME || process.env.USERPROFILE || '' : ''
+const homeDirectory = (
+  (homeDirectoryPayload && typeof homeDirectoryPayload.homeDirectory === 'string'
+    ? homeDirectoryPayload.homeDirectory
+    : '') ||
+  homeDirectoryFromEnv ||
+  ''
+).replace(/\\/g, '/')
 
 const CONFIG = {
   maxIterations: 20,
   maxConsecutiveNoLensRounds: 3,
   copilotMaxPolls: 8,
+  codexReviewTimeoutSeconds: 2400,
+  codexReviewPollIntervalSeconds: 120,
+  codexReviewMaxPolls: 21,
   sharedScripts: '$HOME/.claude/skills/pr-converge/scripts',
   prLoopScripts: '$HOME/.claude/_shared/pr-loop/scripts',
   codexScripts: `${homeDirectory}/.claude/skills/codex-review/scripts`,
@@ -49,7 +60,7 @@ const HEADLESS_EDIT_PREAMBLE =
   '- Never place a destructive-command literal inside a Bash command — not in echo, not in a heredoc, and not as an argument to python -c, node -e, or awk. To exercise or verify destructive_command_blocker (or any hook) behavior, run the committed test suite, e.g. python -m pytest <test_file>, which passes the command strings as in-language data rather than as a shell command.\n' +
   '- When a commit message, or a PR / issue / review-comment body, must describe destructive-command behavior, write that text to a file and pass it by path (git commit -F <file>, gh ... --body-file <file>); never inline it with git commit -m or gh ... -b, where the literal lands in the Bash command and stalls you.\n' +
   '- Keep scratch files and cleanup inside the OS temp dir; never target a repository or worktree path.\n' +
-  '- rm shape rules — the hook grants several rm auto-allow paths. The simplest one accepts a standalone Bash call whose target resolves inside the ephemeral namespace (/tmp, /temp, the OS temp root, or the run worktree); a compound path accepts an rm joined with benign reporting segments when every rm target is an absolute ephemeral path. Both of those paths fail closed on $(...) command substitution and on backtick subshells. The compound path additionally fails closed on any $ in the target — including $CLAUDE_JOB_DIR. The standalone path declines a $-bearing target only when the literal path is not already under an ephemeral root, so it does not by itself stop a $VAR that expands inside an ephemeral root. A third, broad path matches only when the command itself declares an ephemeral working directory (it cds into one, or runs under one): that cwd-scoped path resolves the target against the declared cwd, fails closed on $(...) , backticks, and unknown variables, and resolves the known temporary variables TEMP, TMP, TMPDIR, and CLAUDE_JOB_DIR to the OS temp root, so under that declared ephemeral cwd a bare $CLAUDE_JOB_DIR/tmp/<name> target and a relative target after a cd are auto-allowed. Even so, prefer a Python helper for any cleanup whose path is variable-built or whose setup/teardown spans multiple steps: author the helper file and run it as python <file>.py, which keeps every destructive literal out of a Bash command string entirely and never depends on which auto-allow path matches.\n' +
+  '- rm shape rules — the hook grants several rm auto-allow paths. The simplest one accepts a standalone Bash call whose target resolves inside the ephemeral namespace (/tmp, /temp, the OS temp root, or the run worktree); a compound path accepts an rm joined with benign reporting segments when every rm target is an absolute ephemeral path. Both of those paths fail closed on $(...) command substitution and on backtick subshells. The compound path additionally fails closed on any $ in the target — including $CLAUDE_JOB_DIR. The standalone path declines a $-bearing target only when the literal path is not already under an ephemeral root, so it does not by itself stop a $VAR that expands inside an ephemeral root. A third, broad path matches only when the command itself declares an ephemeral working directory (it cds into one, or runs under one): that cwd-scoped path resolves the target against the declared cwd, fails closed on $(...) , backticks, and unknown variables, and resolves the known temporary variables TEMP, TMP, TMPDIR, and CLAUDE_JOB_DIR to the OS temp root, so under that declared ephemeral cwd a bare $CLAUDE_JOB_DIR/tmp/<name> target and a relative target after a cd are auto-allowed. Outside those ephemeral paths, run no bash rm at all: an rm on a repo or worktree path — most often a build cache like .mypy_cache, .pytest_cache, or __pycache__ left by ruff, mypy, or pytest — is not auto-allowed and stalls you on a prompt no human can answer. A gitignored build cache is harmless, so never delete it — leave it in place. For any genuine delete outside the ephemeral namespace, use the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), which the blocker never sees because it watches only the Bash tool. For any cleanup whose path is variable-built or whose setup/teardown spans multiple steps, author a Python helper and run it as python <file>.py, which keeps every destructive literal out of a Bash command string entirely.\n' +
   '- If a step appears to require a real destructive command, use a non-destructive equivalent or report it as a blocker instead of running it.\n\n' +
   'WAITS AND POLLS — foreground sleep is blocked in this headless harness: a bare Bash "sleep N" or a PowerShell "Start-Sleep" is denied, and a wait you move to a background process — then end your turn to await it — never resumes, because a schema-bearing agent runs for a single turn. Therefore:\n' +
   '- Perform every required delay or poll-interval wait inside this same turn by pairing the Monitor tool with a bounded until-loop: the Monitor tool streams its events to you while you keep working, and the until-loop re-runs the step condition on the interval the step names, up to the attempt budget the step names, exiting the moment the condition holds or the budget is spent — consume the Monitor notifications as they arrive rather than ending your turn to await them. Never end your turn to wait for something to finish.\n' +
@@ -561,7 +572,7 @@ function runConvergenceCheck(context) {
   if (context.copilotDown) reviewerOptOutTokens.push('copilot')
   if (context.codexDown) reviewerOptOutTokens.push('codex')
   if (context.bugteamPostBlocked) reviewerOptOutTokens.push('bugteam')
-  const jobDirName = process.env.CLAUDE_JOB_DIR
+  const jobDirName = typeof process !== 'undefined' && process.env ? process.env.CLAUDE_JOB_DIR : undefined
   const needsCodexCleanExportFallback = Boolean(context.codexCleanAt) && !jobDirName
   if (needsCodexCleanExportFallback && !reviewerOptOutTokens.includes('codex')) {
     reviewerOptOutTokens.push('codex')
@@ -692,7 +703,7 @@ const CODEX_SCHEMA = {
   properties: {
     sha: { type: 'string', description: 'PR HEAD SHA this gate evaluated' },
     clean: { type: 'boolean', description: 'true when Codex reported no findings on sha, or when the gate skipped without requiring a review' },
-    down: { type: 'boolean', description: 'true when Codex is down (wrapper classifies codex_down) or opted out via the codex token — the gate is bypassed' },
+    down: { type: 'boolean', description: 'true when the wrapper classifies codex_down (the gate is skipped and bypassed, recorded as a note) or when Codex is opted out via the codex token — the gate is bypassed' },
     skipped: { type: 'boolean', description: 'true when the gate did not run the review wrapper (opt-out token or usage at/below the shared threshold)' },
     skipReason: {
       type: 'string',
@@ -2072,9 +2083,11 @@ function runCodexGate(head) {
       `3. Resolve the PR base branch (the review target is HEAD vs base, never an invented commit range). Run exactly:\n` +
       `   gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .base.ref\n` +
       `   Capture the printed base branch name.\n\n` +
-      `4. Run the codex-review wrapper against that base. From the PR worktree root, run a short Python driver that imports the skill scripts (add "${CONFIG.codexScripts}" to sys.path) and:\n` +
+      `4. Run the codex-review wrapper against that base. A real Codex review routinely runs about 11-12 minutes — longer than the default 2-minute tool timeout and longer than the 10-minute foreground tool ceiling — so it MUST run in the background, or the tool timeout kills it mid-review and it is misreported as codex_down. From the PR worktree root, write a short Python driver to a temp file that imports the skill scripts (add "${CONFIG.codexScripts}" to sys.path) and:\n` +
       `   - creates a temp run-state directory under the OS temp dir\n` +
-      `   - calls run_codex_review.run_codex_review(repository_directory=<repo root Path>, run_state_directory=<temp Path>, base_branch=<base ref from step 3>)\n` +
+      `   - calls run_codex_review.run_codex_review(repository_directory=<repo root Path>, run_state_directory=<temp Path>, base_branch=<base ref from step 3>, timeout_seconds=${CONFIG.codexReviewTimeoutSeconds})\n` +
+      `   - writes the outcome (outcome_class, exit_code, and the agent_message when completed) as JSON to a result file under the OS temp dir, then exits\n` +
+      `   Run that driver with the Bash tool in the background (run_in_background: true), never in the foreground — the foreground tool timeout caps below the review runtime and would kill a healthy review. Do NOT end this turn to await the background run — a schema-bearing turn that ends never resumes, so the result would never be collected. Wait for the background run to finish inside this same turn per the WAITS AND POLLS rule: pair the Monitor tool with a bounded until-loop that re-checks whether the result file has been written, on a ${CONFIG.codexReviewPollIntervalSeconds}-second interval up to ${CONFIG.codexReviewMaxPolls} attempts (interval x attempts covers the ${CONFIG.codexReviewTimeoutSeconds}-second review budget), consuming the Monitor notifications as they arrive; arm the Monitor with persistent:true (or a timeout_ms of at least interval x attempts) so it is not timed out before the review lands. If the full poll budget is spent with no result file written, return {sha:${'`'}${head}${'`'}, clean:false, down:true, skipped:false, skipReason:'', findings:[]} and stop. When the background run finishes, read the result file and map its outcome:\n` +
       `   - when outcome_class is codex_down (or classify_codex_run on a non-zero exit reports codex_down) -> return {sha:${'`'}${head}${'`'}, clean:false, down:true, skipped:false, skipReason:'', findings:[]} and stop\n` +
       `   - when outcome_class is completed: parse findings with parse_codex_findings.parse_codex_findings(agent_message)\n` +
       `     - empty findings -> return {sha:${'`'}${head}${'`'}, clean:true, down:false, skipped:false, skipReason:'', findings:[]}\n` +
@@ -2536,6 +2549,7 @@ let copilotDown = input.copilotDisabled || false
 let codexDown = false
 let codexCleanAt = null
 let copilotNote = null
+let codexNote = null
 let standardsNote = null
 let cleanAuditNote = null
 let hasStandardsFollowUpFiled = false
@@ -2549,6 +2563,7 @@ const assembleResult = (outcomeFields) => ({
   ...outcomeFields,
   standardsNote,
   copilotNote,
+  codexNote,
   cleanAuditNote,
   reuseNote,
   deferredPrs,
@@ -2840,7 +2855,8 @@ while (iterations < CONFIG.maxIterations) {
       continue
     }
     if (codexOutcome.kind === 'down') {
-      log('Codex gate: Codex classified codex_down — bypassing the terminal Codex gate and proceeding to mark-ready with the gate bypassed.')
+      codexNote = `Codex was unreachable this run (the codex-review wrapper classified codex_down — a Codex CLI error, or a review that ran past its timeout budget). The terminal Codex gate was skipped with the gate bypassed so a Codex outage does not hinder convergence; Codex runs again on the next convergence.`
+      log(`Codex gate: ${codexNote}`)
       codexDown = true
       codexCleanAt = null
       phase = 'FINALIZE'

package/skills/autoconverge/workflow/converge_multi.mjs

@@ -109,11 +109,14 @@ function classifyMultiInput(rawArgs) {
  * fan-out honors it: bugbotDisabled skips the Bugbot phase, and copilotDisabled
  * short-circuits the Copilot quota gate when the account is out of premium
  * requests. An entry that omits an opt-out defaults it to false so the child
- * runs that phase.
+ * runs that phase. homeDirectory is a run-level value forwarded to every child
+ * so the child can build its codex-review scripts path: the workflow sandbox
+ * exposes no process global, so the child reads home from its args, not env.
  * @param {object} prEntry one validated element of the args.prs array
+ * @param {string} homeDirectory the run-level home directory for every child
  * @returns {object} the args object passed to the converge.mjs child run
  */
-function childRunInput(prEntry) {
+function childRunInput(prEntry, homeDirectory) {
   return {
     owner: prEntry.owner,
     repo: prEntry.repo,
@@ -121,6 +124,7 @@ function childRunInput(prEntry) {
     repoPath: prEntry.repoPath,
     bugbotDisabled: Boolean(prEntry.bugbotDisabled),
     copilotDisabled: Boolean(prEntry.copilotDisabled),
+    homeDirectory,
   }
 }
 
@@ -137,7 +141,7 @@ const childResults = await parallel(
   input.prs.map((eachPr) => async () => {
     const childOutcome = await workflow(
       { scriptPath: input.convergeScriptPath },
-      childRunInput(eachPr),
+      childRunInput(eachPr, input.homeDirectory),
     )
     return {
       owner: eachPr.owner,

package/skills/autoconverge/workflow/converge_multi.run-input.test.mjs

@@ -138,6 +138,11 @@ test('childRunInput defaults bugbotDisabled to false when the entry omits it', (
   assert.equal(childRunInput(validEntry(101)).bugbotDisabled, false);
 });
 
+test('childRunInput forwards the run-level home directory to the child run', () => {
+  const childArgs = childRunInput(validEntry(101), '/home/dev');
+  assert.equal(childArgs.homeDirectory, '/home/dev');
+});
+
 test('the malformed-input blocker return carries an empty allDeferredPrs list', async () => {
   const blockerOutcome = await runMultiWorkflowBody(
     'not json at all',

package/skills/fresh-branch/CLAUDE.md

@@ -8,5 +8,7 @@ Creates a new branch from fresh-fetched `origin/main` inside an isolated worktre
 |---|---|
 | `SKILL.md` | Phases, checklist, execute-vs-read for the CLI, gotchas |
 | `scripts/create_fresh_branch.py` | Deterministic CLI: fetch base, `git worktree add -b`, JSON stdout |
+| `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
 | `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
 | `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |

package/skills/fresh-branch/SKILL.md

@@ -113,7 +113,9 @@ Further edits for the new branch belong in `worktree_path`, not in the caller's
 | `SKILL.md` | This hub: phases, checklist, constraints, gotchas |
 | `CLAUDE.md` | Package map for agents browsing the skill folder |
 | `scripts/create_fresh_branch.py` | **Execute** — deterministic fetch + worktree branch CLI |
+| `scripts/fresh_branch_git_commands.py` | Git command helpers behind the CLI (fetch, ref checks, worktree add) |
 | `scripts/test_create_fresh_branch.py` | Real-repo tests for agent/path/CLI behavior |
+| `scripts/test_fresh_branch_git_commands.py` | Real-repo tests for the git command helpers |
 | `scripts/fresh_branch_scripts_constants/` | Named constants for the CLI |
 
 ## Folder map