amico cloud: extract the thin cloud client from RemoteExecutor (#460)

[aarontrowbridge]

Closes #460

What this does

The amico-run dissolution's buildable slice (memo note-20260817 §4): the cloud code that lived as inline fetches inside RemoteExecutor is extracted once into a thin, reusable client, and surfaced as an amico cloud verb — so any agent shell can submit → poll → mirror without going through the launch path. RemoteExecutor delegates; zero behavior change.

Layout

• src/cloud_client.ts — the client, two reusable layers:
  • CloudClient — the wire (submitScript / status / iterLines / pulseLines / frame / abort), carrying every documented wire-shape workaround exactly once: {stats}|{iters} bodies, {raw} key=value stats records, presigned-URL frames (base64 lane kept for older runners), 204 lanes, 401 → ConfigError.
  • CloudMirror — the local run-dir mirror: AMICODE_ITER/AMICODE_PULSE run.log delivery with high-water dedup, atomic iter_NNNNN.png frames, the run.log-mtime heartbeat, FINISHED, and the Receipt accounting: parse gpu_sku/gpu_seconds/cost_usd into the run ledger; surface in run status #425 GPU receipt (ledger row + receipt.toml) at settle. cloudRun() composes both into the full lifecycle — RemoteExecutor.submit()'s delegation target.
• src/cloud_verb.ts — amico cloud submit | status | mirror | abort | run (fleet/pasqal verb pattern: single-line JSON, ok/errors shape, exit 64 on usage/config faults; run uses the launch path's exit lanes 0/130/exit_code). Deliberately not a spine verb — that registry auto-publishes MCP tools, and the memo's working answer (§9) is bash CLI only.
• remote_executor.ts — now the Executor adapter: validates the submit contract (problem_spec routing, script existence, config, lab), delegates the rest. EXIT_INFERRED moved to the client with the terminal lanes; the package index re-exports it (extension imports unaffected). The wallclock ladder (explicit > env > 2h) lives once in wallclockCap.
• S31 — the sanctioned-network-edge exemption moved from remote_executor.ts to cloud_client.ts with the fetches; the executor module lost the exemption because it no longer makes network calls.

Acceptance criteria

• amico cloud exists as a verb — submit (script path or --spec's script_path; a problem_spec spec is refused exactly as the executor refuses it, until P6a), status (one poll), mirror (one-shot snapshot into a contract run dir; preflight refuses to mint a run dir for an unknown task). The composing run fell out cheaply and is included. Zero RemoteExecutor-private code in any of it.
• Reusable client module; RemoteExecutor delegates with no fetches of its own. No behavior change: the FakeCloud wire-shape tests, executor parity, scheduler, and the extension suites all pass unchanged (only edit: the relocated EXIT_INFERRED import split). The slow live smoke is untouched and still skip-gated.
• Receipt accounting flows through the extracted settle path — executor runs, cloud run, and one-shot cloud mirror all emit the GPU receipt accounting: remote runs emit spend rows; ledger gpu sums them (#425) #430 pure-spend ledger row (no fidelity field, by design).
• Works against FakeCloud in CI (+42 tests: client, verb, router seam); the live path degrades honestly — fetch failed (getaddrinfo ENOTFOUND …), one line, exit 64, the real cause surfaced rather than buried (Cloud endpoint unresolvable (NXDOMAIN) — the harmoniqsapis.com domain has NO nameservers; HP lane down #423 reality).

Notes for the director

• amico cloud mirror is one poll pass: a terminal task mirrors completely (Δ4 re-serves full history); a running task yields an honest snapshot with no FINISHED and a note in the JSON. The manifest's script_path is cloud://<task_id> for one-shot mirrors (run.schema.json requires a non-empty string; the script content lives in the cloud task).
• amico cloud abort preflights the channel with one status poll before posting — the abort POST is best-effort by contract and swallows network faults, so without the preflight an unreachable endpoint would report a false ok.
• The wire-shape drift history (2026-07-28: fake agreed with the client instead of the service, inspector stayed empty) moved with the code and the comments; the FakeCloud-vs-live-API pinning tests stay in remote_executor.test.ts untouched.
• One pre-existing failure on this machine, unrelated to this slice: test/agent_spawn.test.ts leaks the developer's real OPENCODE_CONFIG_CONTENT into a child-env assertion — confirmed failing on the clean tree at 845bb53.
• Out of scope per the issue: record-returning half (P6a), launch-path deletion, MCP wrappers, Cloud endpoint unresolvable (NXDOMAIN) — the harmoniqsapis.com domain has NO nameservers; HP lane down #423 DNS.

Summary by CodeRabbit

• New Features
  • Added the amico cloud command for submitting, monitoring, mirroring, running, and aborting cloud tasks.
  • Added JSON status and error reporting for cloud operations.
  • Cloud runs now support live logs, telemetry, frames, terminal states, and GPU receipt artifacts.
  • Local run directories can be created and synchronized from cloud tasks.
  • Added wall-clock limits and graceful abort handling for cloud runs.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8977f05d-1742-4035-a3ec-ba302204a606

📥 Commits

Reviewing files that changed from the base of the PR and between 845bb53 and 0372bce.

📒 Files selected for processing (10)

• packages/amico-run/src/amico.ts
• packages/amico-run/src/cloud_client.ts
• packages/amico-run/src/cloud_verb.ts
• packages/amico-run/src/index.ts
• packages/amico-run/src/remote_executor.ts
• packages/amico-run/test/amico.test.ts
• packages/amico-run/test/cloud_client.test.ts
• packages/amico-run/test/cloud_verb.test.ts
• packages/amico-run/test/remote_executor.test.ts
• packages/amico-run/test/s31.test.ts

---

📝 Walkthrough

Walkthrough

The change extracts cloud execution into cloud_client.ts, adds the amico cloud CLI with five subcommands, delegates RemoteExecutor to the shared client, and adds coverage for submission, polling, mirroring, aborts, receipts, lifecycle outcomes, and routing.

Changes

Cloud execution

Layer / File(s)	Summary
Cloud client contracts and wire methods packages/amico-run/src/cloud_client.ts	Adds centralized cloud HTTP methods, wall-clock resolution, telemetry and frame retrieval, abort handling, and GPU receipt parsing.
Run mirroring and lifecycle settlement packages/amico-run/src/cloud_client.ts, packages/amico-run/test/cloud_client.test.ts	Creates local mirror runs, writes telemetry, frames, heartbeats, receipts, and terminal state, and tests authoritative and inferred completion paths.
Cloud command workflows packages/amico-run/src/cloud_verb.ts, packages/amico-run/test/cloud_verb.test.ts	Adds submit, status, mirror, abort, and run, with argument validation, configuration handling, structured errors, lifecycle control, and exit codes.
Router, exports, and executor integration packages/amico-run/src/amico.ts, packages/amico-run/src/index.ts, packages/amico-run/src/remote_executor.ts, packages/amico-run/test/amico.test.ts, packages/amico-run/test/remote_executor.test.ts, packages/amico-run/test/s31.test.ts	Routes and exports the cloud client, delegates RemoteExecutor to cloudRun, and updates router and network-edge tests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested reviewers: rchari1

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch amico/issue-460-amico-cloud-client

---

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