feat: durable media output history, one safe opener, and aether doctor v2

[AetherAI3]

What this fixes

Three defects that share a shape: state you can lose without being told.

output open 101 was ambiguous. vision.ts wrote index: entries.length + 1, and retention trims the array to 100 — so the 101st generation and every one after it all claimed 101. The resolver returned whichever came first.

A corrupt history looked like an empty one. readLog() was catch { return [] }. Parse failure, disk failure and "no generations yet" were indistinguishable.

The index could be lost outright. saveLog() was a bare writeFileSync over the only copy — no lock, no fsync, no backup. Two Agent turns writing at once silently dropped one side; an interrupted write could truncate everything.

Opening anything went through a shell. execSync(`${cmd} "${entry.filepath}"`) for files, cmd /c start "" <url> for URLs. A filename containing ", & or a backtick was a command-injection primitive. The Windows file path was also simply broken — start is a cmd builtin, not an executable.

aether doctor reported one axis. "The backend URL is well-formed" and "the backend answered just now" both rendered as a green pass, and an unrun check showed skip beside real passes.

Implementation map

Area	Files
Shared primitives	src/core/durable_store.ts (new), src/core/opener.ts (new)
Media history v2	src/core/media_history.ts (new), src/core/media_history_store.ts (new), src/core/vision.ts, src/core/browser.ts
Command surfaces	src/commands/output.ts, src/commands/media.ts, src/commands/slash_media.ts
Doctor v2	src/core/health.ts (new), src/core/diagnostics.ts, src/core/doctor_live.ts (new), src/core/doctor_repair.ts (new), src/commands/doctor.ts
Injectable for the receipt proof	src/core/custody.ts (optional trailing path param; every existing call site unchanged)

Media history v2

Root document is versioned: schemaVersion, generation, nextSequence, updatedAt, entries[]. Each entry carries an artifactId (UUID, generated once, never changes) and a sequence — a persistent monotonic alias serialised as a decimal string, so output open 285 stays convenient without the counter ever being derived from entries.length. Trimming happens after allocation, so retention can never lower the next reference.

Migration. v1 arrays migrate on first read. An index that is a positive integer and unique across the whole legacy set keeps its value; duplicate, missing, zero, negative and non-integer indexes are reallocated above the survivors in stable chronological order. Repairs land before the document is committed, so the resolver never picks a first match. Repeated migrations of the same input are deterministic.

Durability. Every write is one locked transaction: acquire an owner-stamped cross-process lock → read the best valid generation → allocate under the lock → validate → write a same-directory temp → fsync → stage a backup of the previous generation → atomic rename → re-read and confirm the committed generation → release in finally. The temp is always a sibling of the target, because a temp on another volume turns rename into copy+delete.

Recovery. Reads try primary → backup → rebuild from the output directory, and return a state (ok / migrated / recovered-backup / rebuilt / degraded) with a warning the CLI prints above results. An unreadable primary is preserved as .corrupt.<timestamp>; a document with a newer schemaVersion is left strictly alone and refuses both append and clear. Rebuilt entries derive stable IDs from file facts, so re-running a rebuild does not mint a fresh duplicate set, and they are labelled recovered with prompt and model left empty rather than invented.

Resolution. Sequence → full artifact ID → unique ID prefix → unique filename. Ambiguity lists its candidates instead of guessing.

Safe opener

One implementation for files and URLs, shared by media, auth login and github connect. Validates first — http/https only, no embedded credentials, files must exist and be regular files or directories — then hands the target to explorer.exe / open / xdg-open as an argument array with shell: false. Paths are resolved to absolute, which also removes the leading-dash case. doctor --live proves this exact code path.

Doctor v2

Three axes per check. An axis nobody exercised reports not-checked, never a pass; verified now can only be stamped from the current run; a surface this build genuinely lacks (Actions dispatch, Predator) reports n/a with the reason.

Agent transport
  configured     yes
  reachable      yes
  verified now   yes · 15:42:08

Fast is strictly read-only — no network, model, session, opener launch, credential refresh or write. New checks: media index, opener (validated and command-selected without spawning), GitHub, Protocol-C receipt storage.

--live runs the real proof: catalog fetch; dev session; sequence-numbered frames checked for strict monotonicity; pause → resume → steer, in that order, carrying the run nonce; a sandboxed tool write/read/compare/delete confined to a doctor temp dir regardless of what the server asks for; clean session close; a browser open confirmed by a loopback callback; GitHub identity; branch freshness; MCP broker; Protocol-C receipt round trip.

No billed probe. The create request carries purpose: "doctor" and max_uvt: 0. The loop runs only if the server echoes purpose: "doctor" with billable: false; anything else is closed immediately and reported unproven with the reason. Every usage/done frame is accounted, and a run that was billed — or left a session open — reports spend.none as an error.

Branch freshness never fetches. ls-remote plus local object queries. When origin has a commit this checkout has never seen, it says so rather than fetching to find out. A test asserts no mutating git verb is ever invoked.

MCP. A tool is called only when it declares itself readOnly and doctorSafe. No such annotation exists on the broker today, so the honest result is "reachable, and here is why no tool proof was possible".

--fix is a closed allowlist: create missing state dirs, tighten Aether-owned permissions, remove provably abandoned locks and transaction temps, rebuild the media index preserving the corrupt original, prune worktree metadata git already reports gone. It prints exact scope / action / risk / reversibility / backup and changes nothing without --yes; --dry-run shows the plan and stops. Each repair re-checks its own precondition at apply time, so a plan built against a stale report cannot force a mutation. The forbidden set is exported as data so every exclusion has a negative test.

--deep keeps its original read-only meaning and points at --live.

Threat cases covered

• filename containing " & ` $( ) ' and spaces cannot spawn a second process — asserted on the argument array, not a rendered string
• leading-dash filename cannot reach xdg-open as a flag
• URL schemes outside http/https rejected; embedded credentials rejected
• bare Windows drive path is not misclassified as a URL (new URL("C:\\x") parses with protocol c:)
• cross-volume rename avoided: the temp is always a sibling of the target
• the doctor sandbox tool call cannot touch anything outside its temp root
• doctor output and JSON redact token / JWT / AWS / Slack / private-key shapes and URL query strings; a test asserts the stored credential never appears in a live report
• --fix has a negative test per forbidden operation

Tests

npm run typecheck
npm test

922 pass, 0 fail (886 on the base commit; the two --deep network tests were replaced by read-only and live equivalents). New files: test/durable_store.test.ts, test/opener.test.ts, test/media_history.test.ts, test/media_history_store.test.ts, test/doctor_repair.test.ts, test/doctor_live.test.ts.

Notable coverage: 250 generations at retention 100 (no reference reused, nextSequence survives every trim); four concurrent writer processes spawned via real execFileSync children (no duplicate sequences, no lost entries, no leftover lock or temp); crash injection at every persistence transition; corrupt-primary → backup → rebuild → degraded; future-schema refusal; deterministic duplicate-101 migration; all seven branch-freshness states; billed-run and orphan-session detection; sandbox cleanup.

CI (.github/workflows/ci.yml) runs ubuntu-latest and windows-latest, covering the atomic-replace, locking, opener and path behaviour on both.

Migration and rollback

No action on upgrade. output open <number> keeps working; v1 logs migrate on first read and stay visible. Rollback is asymmetric: an older binary reads a v2 document as an unparseable array and would report an empty history. The v2 file is not destroyed, but a downgrade should be paired with restoring .genlog.json.bak or letting the rebuild path repopulate from disk.

The doctor JSON report is now schemaVersion: 2; scripts should read the three axes rather than a single status field.

Docs

COMMANDS.md doctor section rewritten; the /output row documents the new reference forms. Patch notes in RELEASE_NOTES.md and docs/releases/2026-08-14.md, indexed in docs/releases/README.md.

Known gap, stated rather than hidden

--live's agent-loop probes report unproven against today's server, because no non-billable doctor session exists yet. The client contract is implemented and documented (purpose: "doctor" + max_uvt: 0 out, purpose: "doctor" + billable: false back); the server half is an AETHER-CLOUD change (api/routes/agent_dev_session_routes.py) and is deliberately not in this PR. Until it lands, those checks say why they could not be proven instead of showing green.