amico cloud: extract the thin cloud client from RemoteExecutor (amico-run dissolution, buildable slice)

[aarontrowbridge]

Important

Problem — All cloud interfacing lives as inline fetch calls inside RemoteExecutor (packages/amico-run/src/remote_executor.ts): submit/status/stats/pulse/frames/abort, reachable only through the launch path. There is no reusable client, no amico cloud verb, and no way for anything but a launch to talk to the cloud. The Aug 17 rethink memo (vault-aaron/notes/note-20260817-autoresearch-pulse-stack-amico-run-rethink.md, v2.1 refined) dissolves amico-run into five verbs (AUTHOR · EXECUTE · VERIFY · REMEMBER · METER) and keeps exactly one piece of cloud code: a thin amico cloud client. The design is durable in the vault but on no board — and both #373 (WS5 campaign machinery) and #390 (autoresearch rail) build directly on this seam.

Approach — Extract the submit→poll→mirror logic from RemoteExecutor once as a thin amico cloud client callable from any agent shell: submit script/spec → poll → mirror artifacts → return records. The code is FakeCloud-tested today; this is extraction plus a verb surface, not new design. RemoteExecutor then delegates to the client. This is the memo's buildable-now slice — it does not wait for Piccolo-side machinery.

Scope — in: the client module + amico cloud verb surface + FakeCloud test migration + RemoteExecutor delegation · out: the record-returning half (derived spec records / ResultSpec / referee invocation — blocked on P6a in the Piccolo 2.1 queue), launch-path deletion (memo migration step 5, last, only after the runner emits the full run convention), MCP tool wrappers (memo §9 flags it open; working answer is no — a bash CLI is transparent and agent-friendly).

Acceptance Criteria

• amico cloud exists as a verb: submit a script to the configured cloud (~/.amico/cloud.json), poll status, mirror artifacts into a local run dir — the submit→poll→mirror path with zero RemoteExecutor-private code
• The client is a reusable module; RemoteExecutor delegates to it rather than carrying its own fetches (no behavior change — the FakeCloud wire-shape tests and the slow live smoke still pass unchanged)
• Receipt accounting still flows: remote runs still emit the GPU receipt accounting: remote runs emit spend rows; ledger gpu sums them (#425) #430 ledger rows (pure-spend records) through the extracted path
• Works against FakeCloud in CI; the live smoke degrades honestly when the endpoint is unreachable (Cloud endpoint unresolvable (NXDOMAIN) — the harmoniqsapis.com domain has NO nameservers; HP lane down #423 NXDOMAIN is the current reality)

Key Decisions

• Extraction, not rearchitecture: the wire-shape workarounds the executor comments document move with the code, kept once.
• The client accepts scripts today (the current payload already carries them); spec-record submission arrives with P6a.
• Bash CLI over MCP tools for v1 (memo §9 open question, working answer no).

Constraints & Invariants

• Receipt records stay pure spend — no fidelity field (they must never pollute priors).
• No behavior change to the launch path in this slice; the launch path is deleted only in the memo's final migration step.

Prior Art

• Design of record: note-20260817-autoresearch-pulse-stack-amico-run-rethink.md (§4 dissolution map, §9 open questions); theme 6 of plan-20260816-193000-piccolo2-open-core-split.md
• The seam analysis: session "Amico cloud API rework status check" (2026-08-20)
• Complementary, already landed: GPU receipt accounting: remote runs emit spend rows; ledger gpu sums them (#425) #430 (GPU receipt accounting — the ledger half this client feeds); Jack's Cloud runner observability contract: /health, /quota, /instances + gpu_sku/gpu_seconds in receipts #424 (observability contract — /health, /quota, /instances are exactly the client's status/quota surface)

Source

Aug 17 amico-run rethink (ses_ff345cd3…) → memo v2.1 → this issue. Blocked-by: nothing (buildable now). Blocks: the dissolution's later slices; feeds #373 and #390.