Skip to content

fix(cli): flush stdout before exit so large output is not truncated - #87

Merged
kanfil merged 1 commit into
mainfrom
fix/stdout-flush
Nov 9, 2026
Merged

kanfil merged 1 commit into
mainfrom
fix/stdout-flush

Conversation

@kanfil

@kanfil kanfil commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Problem

The Publish run for the v2.12.0 tag (42608148983) failed on macos-latest, 20 and skipped the npm publish job — v2.12.0 is not on npm.

Failure: not ok 306 - iter-8: workflow help documents the provider flags — the captured output ended after the Step Types panel, missing Provider Flags and Examples, yet the exit code was 0.

Root cause

process.exit() terminates immediately and drops writes still queued in libuv. stdout connected to a pipe is asynchronous on POSIX, so a bin that prints and exits can lose the tail of its output when the pipe buffer is small. The same SHA passed the push CI run — it is timing/platform dependent, not a code regression in the release.

Reproduced deterministically: a child writing 1.43 MB then process.exit(0) delivered only 889 KB through exec; adding a flush delivered all 1.43 MB. On Linux the 9.5 KB help output fits the 64 KB pipe buffer, which is why only macOS failed.

Fix

  • src/cli.mjs — new flushStdio() that waits for queued stdout/stderr writes
  • bin/adlc-cli.mjs, bin/adlc-skills-cli.mjs — await flushStdio() before process.exit()
  • src/dispatcher.mjs — body-path output writes synchronously to fd 1. Same bug class, higher stakes: the dispatcher is copied standalone into projects and exits right after writing, and skill bodies run up to ~55 KB, so a session_start injection could be silently truncated (dropped instructions). Fail-open preserved (a closed stdout never throws).

Tests (TDD)

  • tests/bins.test.mjs — pins the flush contract with a 1.4 MB payload through a pipe (RED: flushStdio is not a function)
  • tests/events.test.mjs — pins a 200 KB skill-body injection arriving whole (RED: body truncated at 146,176 bytes)

Local: npm test 948/948 + cross-session e2e green, test:evals 8/8, format:check clean.

Release follow-up (not in this PR)

After this merges, v2.12.0 still needs its npm publish — options are re-running the Publish workflow for the existing tag, or cutting v2.12.1 from the fix. Will confirm with the code owner.

process.exit() terminates immediately and drops writes still queued in
libuv. stdout to a pipe is asynchronous on POSIX, so a bin that prints and
then exits can lose the tail of its output when the pipe buffer is small.
The Publish run for v2.12.0 (42608148983) hit exactly that on macOS:
`workflow help` stopped after the "Step Types" panel, so the
"iter-8: workflow help documents the provider flags" test failed and the
npm publish job was skipped.

- src/cli.mjs: add flushStdio(), which waits for queued stdout/stderr
  writes before the process exits
- bin/adlc-cli.mjs, bin/adlc-skills-cli.mjs: await it before process.exit
- src/dispatcher.mjs: body-path output uses a synchronous write to fd 1.
  The dispatcher is copied standalone into projects and exits right after
  writing; skill bodies run tens of KB, so a session_start injection could
  be silently truncated the same way.

Tests: bins.test.mjs pins the flush contract with a 1.4 MB payload;
events.test.mjs pins a 200 KB body injection arriving whole (RED before the
fix: truncated at 146,176 bytes).

@kanfil kanfil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

factory-review verdict — PR #87 fix/stdout-flush

Reviewed revision: head bdceb8777be022073090c5a69ac8e44342f076a8 · base 0af872f4f308223f1641c0d076e2dda202c0d512 · merge-base 0af872f4f308223f1641c0d076e2dda202c0d512 (checkout: detached exact head SHA, read-only review)
Outcome: merge-ready — 0 Important, 2 nits (advisory, non-blocking). All 10 CI checks pass (ubuntu/macos/windows × node 18/20/22 + e2e-skip-agent).

Pass results (per REVIEW.md)

pass: bugs (Important) — PASS, no findings.

  • src/cli.mjs flushStdio(): awaits both stdout/stderr via empty-write-behind-queue trick; the writableLength === 0 fast path plus always-resolve catch keeps it fail-open so the real exit code is never masked. Correct placement — both bins await it after main() returns, when no further writes can be queued.
  • src/dispatcher.mjs writeStdout(): writeSync(1, …) loop handles partial writes (offset += n), converts once via Buffer.from(text, "utf-8"), and swallows errors fail-open so a closed stdout never breaks the agent session. Body path (up to ~55 KB bodies) plus all three JSON-envelope paths route through it; the spawnSync script path (result.stdout → writeOutput) is covered too. The regression test proves a 200 KB body arrives whole where it previously truncated at 146,176 bytes.
  • tests/bins.test.mjs 1.4 MB flush contract and tests/events.test.mjs 200 KB body test are correctly scoped (large payloads, maxBuffer raised, tail markers asserted).

pass: security (Important) — PASS, no findings. No injection surface (no new inputs, commands, or deserialization); no secrets touched; Buffer.from on in-memory skill text only; sync fd 1 write bypasses nothing security-relevant.

pass: spec-compliance (Important) — PASS, no findings. Fix matches the stated root cause (Publish run 42608148983: macOS pipe truncation of workflow help, exit code 0 masking it) and the fail-open dispatcher requirement. No PRD/AD API or contract change.

pass: quality (Nit) — 2 nits.

  1. (Nit) Identical 2-line process.exit() comment duplicated in bin/adlc-cli.mjs and bin/adlc-skills-cli.mjs — consider a shared note or referencing flushStdio()'s docblock only.
  2. (Nit) writeStdout loop has no zero-byte-write guard: a writeSync returning 0 without throwing would spin. Practically impossible on a blocking fd (it blocks rather than returning 0), but a if (n === 0) break; would make the loop total.

Verdict

No blocking findings. Safe to merge subject to human code-owner approval (this review never approves — advisory only).

Run: pr87-review1 · Target: #87

@kanfil
kanfil merged commit 90efac3 into main Nov 9, 2026
10 checks passed
@kanfil
kanfil deleted the fix/stdout-flush branch November 9, 2026 13:50
kanfil added a commit that referenced this pull request Nov 9, 2026
release: v2.12.1 — flush stdout before exit (#87)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant