fix(adapters): a process that fails to start fails its cell, not the run by seancdavis · Pull Request #64 · netlify/axis

seancdavis · 2026-09-04T14:27:09Z

Summary

This is the other half of #63. That one stops a null byte from reaching spawn(). This one asks what happens when a child process can't start at all, for any reason.

Today, spawn() throwing synchronously (bad args) and the child emitting error (an ENOENT, a binary that isn't there) were both unhandled in the base adapter. Either one escapes adapter.run() as a plain Error, not a ScoringError, so scoring lets it propagate per the fail-loud rule — and axis run dies without a meaningful report. Every other cell in the run had a perfectly good transcript and got nothing.

Now both cases become a failed run for that one cell, with metadata.error set. callJudge already knows how to withhold a failed run, so nothing downstream changes and fail-loud still applies to real bugs.

What changed

src/adapters/base/agent-adapter.ts: spawn() is wrapped in try/catch and returns a failed AgentOutput through a small failedToStart() helper. A child.on("error") listener resolves the exit promise. The spawn error sits second in the error precedence chain — after getResult().metadata.error, before stderr.
Two tests: a synchronous TypeError from spawn() and an ENOENT error event both resolve with metadata.error set and a non-zero exit code. createMockProcess gained an optional error to emit.
AGENTS.md: a "fails to start" bullet under Error Handling, and the precedence chain updated to match.

Not covered: ACP adapters have their own spawn path in acp-adapter.ts. A start failure there still crashes the run. I'd rather do that as a follow-up than widen this one.

Linear: EX-3027

…axis spawn() throws synchronously for unusable arguments (e.g. a null byte in an arg). Wrap it in try/catch and return a failed AgentOutput through the same metadata shape the normal exit path builds, instead of letting the exception escape adapter.run() and kill the whole run. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

…rashing axis Node emits `error` on the child (not a throw) when the process cannot be started asynchronously, e.g. `spawn test-bin ENOENT`. Listen for it alongside `close` in the exit promise and surface the message through the existing error-precedence chain, ahead of stderr and the generic default. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

…crash Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

…s fixture Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

netlify · 2026-09-04T14:27:15Z

✅ Deploy Preview for axisproject ready!

Name	Link
🔨 Latest commit	`28b7ff1`
🔍 Latest deploy log	https://app.netlify.com/projects/axisproject/deploys/6aa015837263020008a36c81
😎 Deploy Preview	https://deploy-preview-64--axisproject.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-09-04T14:27:15Z

✅ Deploy Preview for axis-docs ready!

Name	Link
🔨 Latest commit	`28b7ff1`
🔍 Latest deploy log	https://app.netlify.com/projects/axis-docs/deploys/6aa015838122bb0008aeda17
😎 Deploy Preview	https://deploy-preview-64--axis-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-09-04T14:27:18Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 08b481db-923e-4d62-b7c0-c8a2eca22366

📥 Commits

Reviewing files that changed from the base of the PR and between 2cd440f and 28b7ff1.

📒 Files selected for processing (3)

AGENTS.md
src/adapters/base/agent-adapter.ts
test/unit/adapters/base/agent-adapter.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

netlify/blueprints (manual)

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Summary

Summary by CodeRabbit

Bug Fixes
- Runs now fail gracefully when starting a process encounters an error.
- Synchronous startup failures return structured error details instead of throwing.
- Child-process error events are handled promptly, preventing runs from hanging.
- Error messages now correctly prioritize process startup and execution failures.

Walkthrough

The adapter now converts synchronous spawn() failures into structured failed results. It also handles child-process error events and includes their messages in error precedence. Tests cover null-byte spawn failures and ENOENT child-process errors. Documentation reflects the updated behavior.

Priority: ⬇️ Low — Defer this adapter error-handling change because it is a narrow low-severity fix for process-start failures, with no broader product impact supplied.

Estimated code review effort: 2 (Simple) | ~10 minutes

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 28b7f

Spawn failures now produce structured failed runs instead of terminating the run, with focused coverage for synchronous throws and child-process error events. No merge-blocking risk remains.

Suggested reviewers: sean-roberts

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the primary change: process-start failures now fail the affected cell instead of terminating the entire run.
Description check	✅ Passed	The description directly explains the synchronous and asynchronous spawn-failure handling, tests, documentation updates, and ACP adapter scope.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1 unsupported.)

Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch seandavis/ex-3027-spawn-failure-fails-cell

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

Warning

Repository analysis: Could not refresh netlify/axis because repository setup failed. Please try the review again.

_{Comment @coderabbitai help to get the list of available commands.}

…wn-failure-fails-cell # Conflicts: # test/unit/adapters/base/agent-adapter.test.ts

seancdavis and others added 4 commits September 4, 2026 10:14

docs: note that a process that fails to start is a failed run, not a …

ce36b29

…crash Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

refactor: drop the stale precedence comment and reuse the mock-proces…

41299da

…s fixture Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S6cesfFBiaNe5ttYyXpLce

seancdavis mentioned this pull request Sep 4, 2026

fix(adapters): deliver the prompt over stdin so a null byte can't crash the judge #63

Merged

sean-roberts approved these changes Sep 4, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into seandavis/ex-3027-spa…

28b7ff1

…wn-failure-fails-cell # Conflicts: # test/unit/adapters/base/agent-adapter.test.ts

seancdavis merged commit c1b6991 into main Sep 8, 2026
10 checks passed

seancdavis deleted the seandavis/ex-3027-spawn-failure-fails-cell branch September 8, 2026 14:19

Navigation Menu

fix(adapters): a process that fails to start fails its cell, not the run - #64

fix(adapters): a process that fails to start fails its cell, not the run#64
seancdavis merged 5 commits into
mainfrom
seandavis/ex-3027-spawn-failure-fails-cell

seancdavis commented Sep 4, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 4, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

seancdavis commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Uh oh!

netlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for axisproject ready!

Uh oh!

netlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for axis-docs ready!

Uh oh!

coderabbitai Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

seancdavis commented Sep 4, 2026 •

edited

Loading

netlify Bot commented Sep 4, 2026 •

edited

Loading

netlify Bot commented Sep 4, 2026 •

edited

Loading

coderabbitai Bot commented Sep 4, 2026 •

edited

Loading