FE-875: App runtime probe — boot, probe, classify

[kostandinang]

Stack Context

Stacks on FE-872 (#218). Fifth Arc-1 frontier -- the concrete reachability mechanism behind integration-oracle (without it, "reachable" collapses to "a test imports the module"). Slices 1 + 2 both land here.

What?

Boot the host app from the cook worktree and exercise it over the wire -- the app-execution analogue of test-runner.ts.

• Slice 1 -- probe (runProbe, app-probe.ts): boot -> poll readiness -> hit one HTTP feature endpoint -> classify, always tearing the process down. reachable (< 400), not-reachable (booted but endpoint absent/erroring -- the FE-800 orphan), infra (never booted). A spawn error bails fast instead of polling to timeout.
• Slice 2 -- spec resolution (buildProbeSpec, app-probe.ts): resolve a ProbeTarget (boot argv + paths) into a runnable ProbeSpec by allocating a free port and assembling the ready/feature URLs. The boot test's hand-rolled port dance becomes the production primitive it now dogfoods.

Why?

Verification today only runs the test runner in the worktree, so "reachable" degrades to "a test imports the module" and the FE-800 orphan survives. The harness owns the deterministic, unshortcuttable check; the boot argv + paths are inputs (cook-time grounding supplies them later) -- no per-stack boot engine. The port can't be hardcoded: under parallel cook each slice boots its own app and a fixed port collides, so port->URL binding is the one harness-owned piece (best-effort ephemeral, loopback-only, acknowledged TOCTOU window -- no retry framework).

Tests

Real seeded node:http apps in tmp worktrees, no mocks: reachable; booted-but-404 -> orphan; immediate-exit / missing-binary -> infra; teardown leaves no process. Plus buildProbeSpec: port allocated + URLs assembled, caller env layered under PORT, distinct ports across 8 concurrent allocations. (Also hardens the FE-743 wall-clock timing test, which flaked under the CPU contention real-process tests add -- tolerance now scales with serialMs.)

Deferred

Mode-awareness + where the ProbeTarget argv/paths come from (architect intent + cook grounding) = integration-oracle (#6).

Co-authored-by: Amp amp@ampcode.com

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-881: Cook agent loads the target repo's sandbox-scoped skills #227
• FE-883: Orchestrator operational improvements (serve reliability + Opus 4.8) #224
• FE-878: Brunch serve — one-shot plan-then-cook capstone #222
• FE-877: Brownfield promotion — commit the cook result onto cook/<runId> #221
• FE-876: Integration oracle — reachability gate + grounding seam #220
• FE-875: App runtime probe — boot, probe, classify #219 👈 (View in Graphite)
• FE-872: Install-failure classification — infra-vs-test split #218
• FE-871: Brunch toolchain detection — detect + plan-emitter wiring #214
• FE-867: Agent extension host — dual-mode pi-harness contract #213
• FE-864: Orchestrator improvements umbrella — brownfield feature delivery from spec #212 : 1 other dependent PR (#223 )
• FE-843: Expand cook toolchain profiles, selected at plan time #198
• FE-841: Embed pi as an in-process SDK to drop the external pi CLI dependency #194 : 1 other dependent PR (#211 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
New orchestrator module and types only; not yet wired into the cook net. Real-process integration tests may add CI load; timing assertion change is test-only.

Overview
Adds the app runtime probe (FE-875): harness code that boots a real app in the cook worktree and checks one HTTP feature endpoint, so reachability is not reducible to “a unit test imports the module.”

runProbe spawns the boot argv, polls a readiness URL, hits the feature URL, and returns reachable (HTTP <400), not-reachable (app up but endpoint missing — the FE-800 orphan), or infra (boot/probe failure), mirroring FE-872’s infra vs test split. Boot processes are always torn down (SIGTERM → SIGKILL). Readiness and feature fetch calls use AbortSignal.timeout so a server that accepts connections but never responds cannot hang the cook.

buildProbeSpec turns a ProbeTarget (boot argv + path strings) into a ProbeSpec: it picks a free loopback port, sets PORT in env (overriding caller PORT), and builds ready/feature URLs — the piece the harness owns so parallel cooks do not collide on a hardcoded port.

New types live in types.ts (ProbeSpec, ProbeTarget, ProbeResult, ProbeOutcomeKind). Integration with integration-oracle and cook-time ProbeTarget sourcing is still deferred; PLAN.md records slices 1–2 as landed.

Also relaxes the engine contract parallel-vs-serial timing assertion to scale with serialMs so real-process probe tests do not flake under CPU contention.

^{Reviewed by Cursor Bugbot for commit f32bdf1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 56fa05d. Configure here.}