Reliability hardening for use-local-agent (no API breaks)

[aidenybai]

Summary

Deep audit of use-local-agent surfaced 10 confirmed reliability bugs and 3 hardening gaps. This PR fixes every one of them, end-to-end-validated against real subprocesses, with no public API changes beyond a single new exported error type (AgentStdinClosedError) and one new optional config knob (pendingUpdateBufferLimit).

All 42 existing unit tests still pass. 14 new unit tests + a 5-scenario real-subprocess harness lock the fixes in.

Bugs fixed

P0 — confirmed hangs / leaks / lost signals

1. SIGKILL escalation never fires in connect.dispose() and runCommand. child.killed flips to true as soon as the signal is sent, regardless of whether the process actually died. So the inner setTimeout-then-SIGKILL block was always short-circuited and a stubborn agent could hang agent.close() forever. Replaced with a real child.exitCode === null && child.signalCode === null check via a new isProcessAlive helper.

2. initialize hung the full timeout when the subprocess crashed early. A child that died 5ms after spawn (auth crash, ENOENT, segfault) made us wait the entire 30s default timeout before throwing a misleading AgentInitTimeoutError. Now races against connectionResult.closed and rejects with AgentConnectionClosedError — including the captured stderr tail — within tens of ms.

3. Fatal stderr signals during init were silently dropped. Auth-failure / usage-limit lines printed during initialize fired onFatalError into an empty listener set because the LocalAgent listener was registered after construction. Construction would then proceed normally and the user would see a misleading AgentInitError later. Now the dispatcher buffers the first fatal error and fromConnectResult checks the buffer immediately after init resolves.

4. EPIPE on stdin could escalate to uncaughtException. No error listeners on child.stdin/stdout/stderr; certain Node versions emit 'error' synchronously in the writable's _write before the callback fires. Added no-op error listeners on every stream and a AgentStdinClosedError typed-error path for writes against a dead subprocess.

5. stderr line buffer was unbounded. A 10 MiB single-line stack trace could buffer in memory before flushing. Now capped at 64 KiB via appendCapped.

6. runCommand stdout/stderr buffers were unbounded. Capped at 1 MiB each (truncating from the front so the most recent output is preserved — mirrors ACP terminal semantics).

7. Inactivity-watchdog timer leaked on prompt-validation failure. When the prompt contained image/audio/resource without the required capability, state.activeStream was cleared but inactivityTimer was not. Now cleared explicitly.

8. Per-session pending-update buffer was unbounded. Notifications buffered before the first prompt grew without limit. Now capped at 1000 by default (configurable via the new pendingUpdateBufferLimit option). On overflow the oldest are dropped and a single raw event surfaces _meta.droppedNotifications on the next prompt drain.

9. (Folded into ACP reliability + spec coverage overhaul (use-local-agent) #1 — runCommand had the same SIGKILL bug; same fix.)

10. pendingConfigOptions consumed even when validation fails. First prompt that throws validation used to also consume the config-options state; the next successful prompt would never see them. Now: validate first, drain buffers/config only after validation passes.

P1 — additional hardening

11. Defensive stdout-noise filter. ACP says agents must write only ACP messages to stdout. In practice many CLIs print banners (✔ Connected to ...). Previously a single banner crashed the connection with an opaque AgentInitError from the JSON parser. Lines that don't begin with { are now routed to onStderr prefixed with [stdout-noise] and dropped from the JSON-RPC stream; valid JSON lines pass through unchanged.

12. AbortSignal already-aborted at prompt() invocation is honored without sending session/prompt. Previously we'd dispatch the prompt and immediately try to session/cancel it. Now we synthesize a finish event with stopReason: "cancelled" and never call the agent.

13. Permission requests can no longer double-resolve. A concurrent respond() from a stream-mode caller and a session-cleanup path used to race; cleanup now snapshots-and-clears the pending set before resolving.

Files

packages/use-local-agent/src/connect.ts                     [reliability fixes]
packages/use-local-agent/src/local-agent.ts                 [reliability fixes]
packages/use-local-agent/src/utils/run-command.ts           [reliability fixes]
packages/use-local-agent/src/constants.ts                   [new caps]
packages/use-local-agent/src/errors.ts                      [+AgentStdinClosedError]
packages/use-local-agent/src/index.ts                       [export new error]
packages/use-local-agent/src/utils/process-alive.ts         [NEW]
packages/use-local-agent/src/utils/cap-buffer.ts            [NEW]
packages/use-local-agent/src/utils/filter-stdout-noise.ts   [NEW]
packages/use-local-agent/src/testing/mock-agent.ts          [pass-through getFirstFatalError]
packages/use-local-agent/tests/reliability.test.ts          [NEW: 14 tests]
.changeset/reliability-hardening.md                         [NEW]

No adapter file is touched. Public adapter API, event types, and option fields are unchanged except for the additions above.

Evidence

Unit tests — all green

Test Files  9 passed (9)
     Tests  56 passed (56)

42 existing + 14 new. pnpm typecheck, pnpm lint, pnpm format:check all clean.

End-to-end against real subprocesses

A real-process harness drove the echo-agent fixture and 4 purpose-built fault-injection subprocesses. All 5 fixes confirmed in production-shaped paths:

[FIX #1: SIGKILL escalation] dispose() of an unresponsive child kills it within grace period
    close() returned in 2009ms
  ✓ close() completes within SIGTERM-grace + SIGKILL-fallback (got 2009ms)

[FIX #2: init-vs-exit race] subprocess that exits before initialize -> AgentConnectionClosedError fast
    error class: AgentConnectionClosedError, elapsed: 26ms
  ✓ rejects with AgentConnectionClosedError
  ✓ rejects within 3s (not waiting full 30s timeout); got 26ms

[FIX #3: fatal stderr during init] auth-failure stderr line surfaces as AgentUnauthenticatedError
    error class: AgentUnauthenticatedError, _tag: Unauthenticated
  ✓ rejects with AgentUnauthenticatedError

[FIX #4: EPIPE on stdin] writes after subprocess death do not crash host
    uncaught: (none)
  ✓ no uncaught exception escaped to host

[FIX #11: stdout-noise filter] CLI banner on stdout doesn't crash init
    agentInfo.name: noisy
    captured noise: ["[stdout-noise] ✓ Connected to upstream","[stdout-noise] Loading config..."]
  ✓ init succeeds despite stdout banners
  ✓ stdout banner routed to onStderr with [stdout-noise] prefix

✓ ALL RELIABILITY E2E TESTS PASSED

Bug #1 alone — without this fix, an agent that swallows SIGTERM would have hung agent.close() indefinitely on the host.

Existing echo-agent end-to-end

The package's existing real-subprocess paths (init, prompts, tool calls, usage, auth-required, cancel, subprocess exit) all still pass:

✓ init negotiates protocol and exposes agent info
✓ prompt streams text deltas
✓ tool_call + tool_call_update completed
✓ usage_update produces typed event
✓ auth_required JSON-RPC -> AgentUnauthenticatedError
✓ session/cancel resolves with cancelled stop reason
✓ subprocess exit -> AgentConnectionClosedError

Public API impact

• New export: AgentStdinClosedError (_tag: "StdinClosed").
• New option: LocalAgentConnectOptions.pendingUpdateBufferLimit?: number (default 1000).
• Everything else internal. Behavior visible to callers is strictly more correct (timeouts are tighter, error tags are more precise, no more silent drops, no more host-process crashes from EPIPE, no more hung subprocesses).

Risk

Low. The only behavioral surface visible to existing users is the stdout-noise filter, which is strictly additive (banners that previously crashed the connection now arrive as [stdout-noise] stderr lines instead). All other changes are correctness fixes for paths that were already broken; if anyone was relying on those broken paths they have a worse problem to begin with.

Changeset

A patch changeset is included at .changeset/reliability-hardening.md.

  

[aidenybai]

Superseded by #3. All reliability fixes from this PR (SIGKILL escalation, init-vs-exit race, EPIPE handlers, stdout-noise filter, run-command caps, pending-update cap, validation timer leak, perm settle gate, AgentStdinClosedError, the 14 reliability tests) were consolidated into the rename PR and are already on main at the new packages/spawn-agent/ paths. The remaining diff is purely path/identifier rename (LocalAgent -> SpawnAgent, local-agent.ts -> spawn-agent.ts).