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

Property	Required	Rationale
Array-form args	Yes	No shell-string commands (injection risk, quoting hell)
cwd or git -C	Yes	Never rely on inherited process.cwd()
stdin: 'ignore'	Yes	A never-closed stdin pipe under Bun/Windows can block child exit (v7.3.3)
timeout: <ms>	Yes	No subprocess is "always fast" on every platform
stdout/stderr bounded	Yes	Never leave piped stream unattended on long-running child
proc.kill() in finally	Yes	Outer withTimeout lets awaiter proceed but doesn't abort child