refactor(cli): move the async leaves and the calibration child runner onto Effect

[Makisuo]

The CLI is already Effect at the command layer — Effect CLI v4, Context.Service for MapleConfig/Mode, Schema.TaggedError throughout — but raw async below it. Most of that raw code is straight-line filesystem work that happens to use await and is fine as-is. Three spots are not, and this converts those.

Scope is deliberately tiered. src/server/{checkpoints,archives,local-store-migrations} (~15k lines) and serve.ts stay raw; see Out of scope below.

Why these three

• Nothing was interruptible. runCandidateChild was a hand-rolled new Promise with a settled flag, a setTimeout watchdog and a 500ms setInterval disk poller. Ctrl-C mid-calibration left the poller running and the spawned process group orphaned — nothing killed it.
• Failures were silently discarded. credential-store.ts swallowed every error in a bare catch, and its callers used Effect.promise, which discards failures again. A broken keychain was indistinguishable from "not logged in".
• A latent self-kill. const pgid = child.pid ?? 0, then process.kill(-pgid, "SIGKILL"). -0 is 0, and POSIX kill(0, sig) signals the caller's own process group — the CLI would have SIGKILLed itself.

What changed

Leaves (each had only Effect callers, so no bridging seams were introduced):

• core/credential-store.ts → ChildProcessSpawner. MapleConfig captures the spawner in make, the way it already captures fs, so MapleConfigValues signatures stay R = never.
• commands/auth.ts stdin → Stdio.stdin.
• core/update.ts → ChildProcess for tar/xattr, FileSystem for the fs work.

Calibration child-process path (commands/archive.ts) — runCandidateChild, runBoundCalibrationMatrix, runCalibrationMatrix and the handler, converted as one unit. The watchdog and poller become a forked killer fiber; the group reap becomes a scope finalizer so it also runs on interruption and defects.

No new dependencies: BunServices.layer was already in MainLayer and provides ChildProcessSpawner, FileSystem, Stdio.

Reviewer notes

Three near-misses worth a look, since each would have been a silent regression:

1. Terminal.readLine is the wrong primitive for piped stdin. It waits for a readline "line" event and never resolves on EOF, so printf tok | maple auth login --with-token would hang forever. Stdio.stdin terminates at EOF and splitLines flushes the trailing partial line. Verified against the real runtime for no-trailing-newline, extra-lines, CRLF and empty input.
2. handle.exitCode fails with a PlatformError on signal death, and every watchdog kill is a signal death. That is collapsed to a null code, so a killed candidate lands in the same code !== 0 branch as before. Without it, one killed candidate would abort all six signals instead of eliminating a single matrix cell.
3. mapFsError detected EACCES via a bare .code, which a PlatformError does not expose — the actionable "re-run the installer" message would have vanished for every converted fs call. It now also checks the PermissionDenied reason tag and the wrapped cause.

Behaviours deliberately preserved verbatim: fail-closed peak-RSS parsing, nonzero exit failing even when a metrics JSON line is present, the 1600-char diagnostic truncation, the fail-loud disk-poll read error (its catch lives inside the poll, so a read error can't silently kill the poller and downgrade fail-loud to fail-late), and gating completion on the pipes draining rather than on exit.

Two intentional deviations:

• core/executor.ts was left alone. Its throw new Error sits behind WarehouseSqlClient.insert, a Promise<void> port owned by @maple/query-engine, and the executor already wraps it in Effect.tryPromise with mapWarehouseError. Converting it would change the shape without changing the behaviour.
• The closing reconcile keeps its ArchiveError rather than being orDied into a defect, and a close failure now only decides the outcome when the matrix itself succeeded — so unlike the original finally, it no longer masks the matrix error.

A bug this turned up

Exercising the refactored credential path against a real keychain surfaced a pre-existing bug (present before this branch — the original Bun.spawn version reproduces it identically): on macOS, maple auth login recorded credentialStore: "keychain" and stored an empty password, so the token was lost. saveRemoteCredential skips the file fallback whenever the keychain write reports success, so the next command saw no token and the user looked logged out.

security add-generic-password -w with no argument does not read the secret from stdin as the old comment claimed. It prompts for it — which is what keeps the secret out of the process list — and then asks for it to be retyped. A single piped line fails that confirmation, and security stores an empty password and exits 0 anyway. The secret is now fed twice, and the write is verified by reading it back, so a partial write falls back to file storage instead of silently losing the token.

This is exactly the class of failure the old bare catch was hiding, which is why it is fixed here rather than filed separately.

Testing

typecheck, oxlint, oxfmt --check and bun test (493 pass) are green in apps/cli.

New coverage for code this branch converted that previously had none:

• runCandidateChild — four tests (signal death, nonzero exit alongside a valid metrics JSON line, the group kill, output written immediately before exit). It was an unexported promise closure reachable only from the shell probes. The group-kill test is mutation-verified: swapping the reap for a child-only kill makes it fail.
• extractTar and mapFsError. The mapFsError test is mutation-verified too — it fails against the old bare .code check, confirming a PlatformError really does hide EACCES.

Manual, against the real runtime:

• Keychain write/read/delete round-trip on a throwaway origin (no automated test: it would either touch a developer's real login keychain or need a fake spawner whose partial stub test/ cannot typecheck).
• maple auth login --with-token with a token piped without a trailing newline — the case Terminal.readLine would hang on — plus empty stdin, extra lines and CRLF.

Native probes, run locally against a binary compiled from this branch, all passing:

Probe	Result
native-archive-calibrate-probe.sh	PASS — 24 results, held-out validation, six-metric predicted-vs-observed within tolerance, manifest identity verified, no debris
native-archive-calibrate-crash-probe.sh	PASS — SIGKILL at the sampling boundary reconciled, unrelated pin survived
native-checkpoint-smoke.sh	PASS
native-archive-smoke.sh	PASS

Out of scope

checkpoints.ts pins/locks/restore, durable-files.ts, serve.ts, and the archives/migrations bulk. Every conversion here obeys one direction — Effect wraps raw, raw never wraps Effect — and those modules are called from six still-promise-based callers, so converting them would mean either compatibility shims or a 15k-line diff. Splitting withMaintenanceLock / withRestoredCheckpoint into acquireRelease shapes is the natural next tier; it also unblocks runCalibrateSample.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[github-actions]

🍁 Maple PR preview

Note

Preview resources were removed when this pull request closed.

Final commit 67e9479 · View workflow run