β.1 — amico-run thin process orchestrator

[jack-champagne]

Phase: β — Schuster demo · Plan task: β.1 · Est: 3 pd · Suggested role: Dev A (Julia+Node critical path)

What to build

The D9 thin orchestrator: a Node CLI amico-run <script.jl> [--executor local] [--lab <id>] that spawns julia [--sysimage] <script>, writes manifest.toml (first) + the FINISHED sentinel ({status, exitCode}) from outside Julia, exposes Executor.submit(scriptPath, lab) → RunHandle (LocalExecutor only), and relays AMICODE_ITER lines + a final DONE summary. Passes the lab pointer (path/id) — never parses/merges params (D10).

Acceptance criteria

• A run produces a run dir conforming to the run-dir contract: manifest.toml first, FINISHED{status,exitCode} terminal, result.toml atomic (temp+rename). (S7)
• julia rc≠0 ⇒ FINISHED{status=failed, exitCode=rc}; clean run ⇒ FINISHED{status=completed}. (S7)
• No flag-parsing/SolveSpec-building, no MCP/callback-HTTP paths (grep rule). (S31)
• Exit 0 solved / 64 orchestrator-config-error / other = julia rc.

Key challenges to keep in mind that are making the time estimate higher

• It is absolutely critical that this components satisfies a proper interface for the extension to invoke AND also satisfies publishing data back into the extension correctly so that data can be catalogued, tracked, and provided to researchers using the extension (must be validated across a number of solves, systems, against schemas ideally.
• Needs to work with our pre-existing software stack as an runner/interface leading to possible integration / interface changes from our other software into this component
• Needs to be build in a way that is extensible on systems, solvers, quantum systems, and with our changing software stack (for the future)

Blocked by: none (keystone — everything reads the run-dir contract it emits)
Authoritative refs: plan §2 β.1 · PRD S7/S31 · decision D9/D10 · architecture

[Rchari1]

Implementation up at #7 — all four ACs covered (run-dir contract, FINISHED status mapping, S31 grep rule in CI, exit-code convention), plus the slow-tier evidence for the schema-validation challenge: X- and H-gate Piccolo solves through the real CLI, run dirs validated against the provisional schemas (fidelity > 0.9999). AC→test map in the PR body.