bot-agents/.agents/memory/bot-agents-child-processes.md

description

description
Child processes use plain node:child_process spawn (explicit stdio, uid/gid, whole env); src/processes/child.ts has exitCode (128+signo) and echo; no execFile maxBuffer

Every call site calls spawn from node:child_process itself, with everything explicit:

• uid/gid of the profile for anything an agent profile runs (each profile is its own UID, 20000+). Never drop them.
• env is the whole environment the child gets (a sanitized one for agents); nothing from the coordinator is merged in.
• stdio: stdin is "ignore" so an agent CLI never waits on input (only codex login --with-api-key pipes the token in). Output that is not read is "ignore"; output that is read is "pipe" and streamed.
• No execFile/exec: their maxBuffer (1 MiB) kills a chatty child. Read piped streams incrementally instead.

src/processes/child.ts holds what the call sites share:

• exitCode(child): call it right after spawn. It settles on exit (not close, which a daemonized grandchild can hold open), maps a signal to 128 + signo as a shell does, and rejects on a failed start. The rejection is pre-caught so it is not reported as unhandled before the caller awaits it.
• echo(stream, chunk): writes and waits for drain when the buffer is full, so echoing never outruns a slow reader.

Tests use spawnSync for short commands.

Other port details:

• src/common/errors.ts isNotFound checks ENOENT (file) or ESRCH (process).
• Temporary files are an exclusive wx create with mode 0600.
• src/common/json.ts holds type guards used instead of as casts on parsed JSON.
• process and Buffer must come from node: imports: no-restricted-globals in scripts/project-lint.ts enforces it (lint-parity-never-shrinks).

Related: how each agent CLI reports bad credentials is in agent-cli-auth-failures.