AirCoding/AirPlan/docs/architecture/adr/ADR-0005-use-independent-worker-processes-and-ndjson-ipc.md

ADR-0005: Use Independent Worker Processes And NDJSON IPC

• Status: Accepted
• Date: 2026-05-27

Context

A single agent process doing all work would cause context explosion, reduce responsiveness, and make parallel execution fragile. AirCoding needs workers that can be monitored, retried, cancelled, and recovered independently.

Decision

Run Executor, Reviewer, Debugger, Compactor, and ExperienceMiner as independent Bun child processes. Use NDJSON over stdio for IPC.

IPC messages use:

kind: event
kind: control
kind: log

The Scheduler owns process lifecycle, heartbeat monitoring, timeout handling, and WorkerResult collection.

Consequences

• Main Agent remains responsive.
• Workers have bounded task context.
• Scheduler can detect lost workers through heartbeat/process state.
• stdout is reserved for protocol; stderr is crash/fatal fallback.
• Worker loops may be role-specific rather than one generic shared loop.