Subprocess Safety

Subprocess Safety

Read, in order:

1. AGENTS.md (Invariant 3: subprocesses)
2. docs/engineering-invariants.md (subsection 3)
3. .agents/skills/writing-tests/SKILL.md if tests are touched
4. .opencode/skills/generated/mock-to-internals-migration/SKILL.md if converting mock.module to _internals

Codex-specific execution notes:

• This skill consolidates AGENTS.md Invariant 3 into an actionable checklist.
• The canonical spawn shape and six required properties are non-negotiable per AGENTS.md.
• The CI quality job enforces these via bun run check:invariants (Check 1: subprocess timeout).
• Violations are advisory in CI but blocking in code review.

When to use this skill

• You are adding, modifying, or reviewing a subprocess call (bunSpawn, spawn, spawnSync, child_process.execFile, etc.)
• You are writing or updating tests that exercise subprocess-dependent code
• A PR review flags a subprocess call missing timeout, cwd, or cleanup

Scope

This skill applies to all files that spawn child processes:

• src/utils/git*.ts
• src/hooks/*.ts
• src/tools/*.ts
• src/services/*.ts
• src/plugins/*.ts
• src/index.ts (init-path subprocesses)
• Any test file (tests/**) that stubs or exercises subprocess code

Canonical spawn shape

Every subprocess call MUST follow this pattern:

const PER_CALL_TIMEOUT_MS = 10_000; // module-level constant (choose an appropriate value)

const proc = bunSpawn(['git', '-C', dir, 'rev-parse', '--show-toplevel'], {
  stdin: 'ignore',
  cwd: dir,
  timeout: PER_CALL_TIMEOUT_MS,
  // stdout/stderr: piped, bounded, or ignored
});
try {
  const result = await proc;
  // process result
} finally {
  proc.kill(); // best-effort cleanup
}

Six required properties

execFile callback vs execFileSync distinction

child_process.execFile (callback form) and child_process.execFileSync have different default stdio behavior:

Key differences from the canonical spawn pattern:

1. proc.kill() in finally (line 69): Applicable to callback-form execFile. The function returns a ChildProcess reference (matching the canonical spawn pattern per Node.js docs). The child reference enables kill() before that point for timeout safety, and failing to call proc.kill() in finally can leave orphaned children when combined with an outer withTimeout. The timeout option triggers internal SIGTERM, but is not a substitute for explicit kill in finally — always kill the child in finally.

2. stdin: 'ignore' (line 66): Technically default-safe for callback execFile (stdin is piped, not inherited). However, always add stdio: ['ignore', 'pipe', 'pipe'] for defense-in-depth and consistency with execFileSync calls. Note: Bun's TypeScript definitions do not include stdio in ExecFileOptions — use execOpts as any when passing stdio to callback-form execFile.

3. execFileSync should always use stdio: ['ignore', 'pipe', 'pipe'] to prevent the stdin-inheritance hang on Windows/Bun (v7.3.3).

Windows-specific notes

• .cmd extensions: npm/bun binaries on Windows are .cmd wrappers. Resolve the executable path explicitly using which/where or the project's cross-platform helper. Do NOT enable shell: true or shell-mediated execution to work around PATH resolution.
• PATH differences: cmd.exe and PowerShell resolve PATH differently. Test on Windows, not just macOS/Linux.
• child_process.spawn('bin', ...) does not behave identically to running under cmd.exe. Use array-form args and explicit cwd.
• fs.renameSync cannot overwrite existing directories on Windows. Use a remove-then-rename pattern or fs.rename with error handling.

gh CLI Subprocess Patterns

The gh CLI is a common subprocess in this repo (scripts/release-notes-fragments.mjs, CI workflows). It follows the same six required properties as all subprocesses, plus several gh-specific patterns.