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

COMMANDS.md

@@ -150,18 +150,57 @@ Exports the cryptographic proof package for one audit entry. Find ids with
 aether receipt chat_8f3a...
 ```
 
-### `aether doctor [--deep]` — runtime diagnostics
-Runs an ordered set of structured checks — auth, network reachability,
-config integrity, MCP registry health, and more — and prints a pass/fail
-summary. `--deep` adds slower, bounded checks on top of the fast baseline.
-Exits `1` if any check fails, so it's safe to gate scripts on.
+### `aether doctor [--live | --fix]` — health, proof, and repair
+Every check answers three questions separately, so "configured" is never
+mistaken for "working":
+
+```
+Agent transport
+  configured     yes
+  reachable      yes
+  verified now   yes · 15:42:08
+```
+
+A check nobody exercised reports `not checked` — never a pass. A surface this
+build genuinely does not have reports `n/a` with the reason. Exits `1` if any
+check is an error, so it is safe to gate scripts on.
+
+**`aether doctor`** — fast and strictly read-only. No network call, no model
+call, no session, no opener launch, no credential refresh, no write. Covers
+runtime, workspace, git, transport config, auth config, tools, memory, MCP
+registry, persistence, the media output index, the opener, GitHub, and
+Protocol-C receipt storage.
+
+**`aether doctor --live`** — proves the paths end to end, right now:
+authenticated catalog fetch, a dev session, sequence-numbered frames,
+pause/resume/steer acknowledgement, a sandboxed tool write/read/compare/delete
+round trip, clean session close, a real browser open confirmed by a loopback
+callback, GitHub identity, branch freshness compared **without fetching**, the
+MCP broker, and a Protocol-C receipt round trip. Billing is accounted across
+the run and reported as `spend.none`; the agent loop runs only when the server
+confirms a non-billable doctor session, and is reported as unproven otherwise.
+`--no-ui` skips the browser proof on a headless box (reported as skipped, not
+passed).
+
+**`aether doctor --fix`** — a closed allowlist of local repairs, never a repair
+agent. Prints the exact scope, action, risk, reversibility and backup of every
+planned repair and changes nothing without `--yes`. It will not rotate
+credentials, spend UVT, invoke a model, edit source, mutate a git ref, dispatch
+Actions, run Predator, or call an MCP write tool.
 
 ```bash
-aether doctor
-aether doctor --deep
-aether doctor --json
+aether doctor                      # fast, read-only
+aether doctor --live               # end-to-end proof, no spend
+aether doctor --live --no-ui       # same, on a headless box
+aether doctor --fix --dry-run      # show the repair plan, change nothing
+aether doctor --fix --yes          # apply the plan
+aether doctor --fix --only media.rebuild --yes
+aether doctor --json               # schema-versioned report for automation
 ```
 
+`--deep` still means the read-only report it always meant; it now points at
+`--live` for the end-to-end proof.
+
 ### `aether mcp [list|doctor|repair]` — manage and diagnose MCP servers
 With no subcommand (in a TTY), opens the same interactive MCP manager as the
 `/mcp` slash command: an arrow-key menu over backend connections (OAuth/PAT
@@ -320,7 +359,7 @@ Requires an active orchestrator — switch with `/agent neo` or `/agent kronus`
 | `/sequence <prompt>` | Cinematic multi-shot video (routes to a cinematic model by default). |
 | `/animate <image_url\|file\|#n> [motion]` | Animate a still image into video. |
 | `/re-cut <edit>` | Re-edit the last generated video. |
-| `/output [open <n>\|clean]` | List, open, or clear recent generations. |
+| `/output [open <ref>\|clean]` | List, open, or clear recent generations. `<ref>` is a sequence number, a full artifact ID, or a unique ID prefix; an ambiguous reference lists its candidates instead of guessing. |
 | `/storyboard <prompt\|file> [--scenes --style]` | Multi-scene storyboard: parse → preview → `--generate`/`--animate`/`--render`. |
 
 ### HUD

RELEASE_NOTES.md

@@ -1,3 +1,44 @@
+# Aether Agent — your artifacts get an identity, and doctor stops guessing
+
+**August 14, 2026**
+
+Two things you can lose quietly — the record of what you generated, and the
+belief that your setup works — stop being losable.
+
+- **Every generated artifact gets a UUID** plus a persistent short reference.
+  The old log numbered entries by array length, so once retention trimmed to
+  100, the 101st generation and every one after it all answered to `101`.
+  `output open 101` picked whichever came first. That is gone.
+- **History cannot silently vanish.** Writes are locked across processes,
+  atomic, flushed, and backed up. A corrupt index recovers from backup or
+  rebuilds from the files still on disk — and always tells you which happened
+  instead of rendering an empty list. The unreadable copy is kept as evidence,
+  and an index written by a newer Aether is never overwritten.
+- **Opening a file or a URL no longer goes through a shell.** Both paths used
+  to build a command string, so a filename containing a quote or an `&` was an
+  injection primitive. One implementation now hands the target to the OS as an
+  argument array — and the Windows URL path actually works, which it did not
+  before.
+- **`aether doctor` answers three questions, not one.** Configured, reachable,
+  and verified-now are separate. A check nobody ran says `not checked`; a
+  surface this build does not have says `n/a` with the reason. Neither is a
+  green tick any more.
+- **`aether doctor --live` proves it** — a real session, sequence-numbered
+  frames, pause/resume/steer acknowledgement, a sandboxed tool round trip, a
+  browser open confirmed by a loopback callback, branch freshness compared
+  without fetching, and a Protocol-C receipt round trip. Billing is accounted
+  across the run: the agent loop runs only when the server confirms a
+  non-billable doctor session, and reports itself unproven otherwise.
+- **`aether doctor --fix`** shows its exact repair plan — scope, risk,
+  reversibility, backup — and changes nothing without `--yes`. It cannot rotate
+  credentials, spend, invoke a model, edit source, or move a git ref.
+
+Nothing to do on upgrade: `output open <number>` keeps working and existing
+history migrates on first read. Full detail in
+[docs/releases/2026-08-14.md](docs/releases/2026-08-14.md).
+
+---
+
 # Aether Agent — the API brain goes bidirectional
 
 **August 12, 2026**

docs/releases/2026-08-14.md

@@ -0,0 +1,111 @@
+# Release notes — 2026-08-14
+
+One lane landed: **custody of the things you can lose**. Generated artifacts get
+an identity that never moves, the media index stops being able to vanish
+quietly, opening a file or a URL stops going through a shell, and `aether
+doctor` stops answering "is it configured?" when you asked "does it work?".
+
+## Highlights
+
+- **Media output history v2** — every artifact gets a UUID plus a persistent
+  monotonic reference. `output open 101` used to be ambiguous once you passed
+  100 generations; it no longer can be.
+- **History that cannot silently disappear** — writes are locked, atomic,
+  fsync'd and backed up; a corrupt index recovers from backup or rebuilds from
+  disk, and always says which happened.
+- **One safe opener** — files and URLs are handed to the OS as an argument
+  array. The two old paths each built a shell string.
+- **`aether doctor` v2** — configured / reachable / verified-now are three
+  separate answers, and `--live` proves the whole path without spending
+  anything.
+- **`aether doctor --fix`** — a closed allowlist of local repairs that shows its
+  exact plan first and changes nothing without `--yes`.
+
+## Media output history
+
+The v1 log wrote `index: entries.length + 1`. Retention trims the array to 100,
+so the 101st generation — and every one after it — all claimed index `101`.
+`output open 101` resolved to whichever duplicate happened to come first.
+
+- Each artifact now carries a UUID that is generated once and never changes,
+  plus a `sequence` alias that keeps the short numeric reference convenient.
+  The counter is persisted, not derived from the retained window, so trimming
+  can never hand the same number out twice.
+- A reference resolves by sequence, full artifact ID, or a unique ID prefix. An
+  ambiguous reference lists its candidates instead of guessing.
+- Existing logs migrate on first read. Duplicate `101`s are repaired
+  deterministically before the migrated index is committed.
+- Writes run one locked transaction — read the best valid generation, allocate
+  under the lock, validate, write a same-directory temp, flush, stage a backup
+  of the previous generation, rename atomically, then re-read and confirm. Two
+  Agent turns writing at once can no longer drop each other's entry, and a
+  crash at any phase leaves either the old or the new generation intact.
+- Reads recover in order: primary, backup, then a rebuild from the files still
+  on disk. Every degraded outcome prints a warning above the results, so a lost
+  history never looks like an empty one. An unreadable index is preserved as
+  `.corrupt.<timestamp>` rather than overwritten, and an index written by a
+  newer Aether is left strictly alone.
+- Recovered entries are labelled as such. Prompt and model cannot be recovered
+  from a file on disk, so they stay empty instead of being invented.
+
+## Opening files and URLs
+
+Opening a generated file ran `execSync` on an interpolated shell string, and
+opening a URL spawned `cmd /c start "" <url>` on Windows. A filename containing
+a quote, an `&`, or a backtick was a command-injection primitive — and the
+Windows path was also broken, because `start` is a shell builtin, not an
+executable.
+
+Both now go through one implementation that validates the target first
+(http/https only, no embedded credentials, files must exist) and hands it to
+`explorer.exe` / `open` / `xdg-open` as an argument array with the shell
+disabled. `doctor --live` proves this exact code path.
+
+## `aether doctor`
+
+The old report had one axis: pass / warn / fail / skip. "The backend URL is
+well-formed" and "the backend answered just now" both rendered as a green
+`pass`. Now every check answers three questions independently, and an axis
+nobody exercised reports `not checked` rather than a pass:
+
+```
+Agent transport
+  configured     yes
+  reachable      yes
+  verified now   yes · 15:42:08
+```
+
+- **`aether doctor`** is fast and strictly read-only: no network call, no model
+  call, no session, no opener launch, no credential refresh, no write. New
+  checks cover the media index, the opener, GitHub, and Protocol-C receipt
+  storage.
+- **`aether doctor --live`** proves it: an authenticated catalog fetch, a dev
+  session, sequence-numbered frames, pause/resume/steer acknowledgement, a
+  sandboxed tool write/read/compare/delete round trip, a clean session close, a
+  real browser open confirmed by a loopback callback, GitHub identity, branch
+  freshness compared without fetching, the MCP broker, and a Protocol-C receipt
+  round trip. Billing is accounted across the run and reported as `spend.none`.
+- **No billed health probe.** The agent loop runs only when the server confirms
+  a non-billable doctor session; otherwise the session is closed immediately and
+  those checks report unproven with the reason. A skipped check is never a pass.
+- **`--no-ui`** skips the browser proof on a headless box and reports it as
+  skipped, not passed.
+- **`aether doctor --fix`** is a closed allowlist: create missing state
+  directories, tighten Aether-owned permissions, remove provably abandoned locks
+  and transaction temps, rebuild the media index while preserving the corrupt
+  original, and prune worktree metadata git already reports as gone. It prints
+  the exact scope, action, risk, reversibility and backup of every repair, and
+  changes nothing without `--yes`. It will not rotate credentials, spend UVT,
+  invoke a model, edit source, mutate a git ref, dispatch Actions, run Predator,
+  or call an MCP write tool.
+- A surface this build genuinely does not have — Actions dispatch, Predator —
+  reports `n/a` with the reason instead of a green tick.
+- `--deep` still means the read-only report it always meant, and points at
+  `--live` for the end-to-end proof.
+
+## Upgrading
+
+Nothing to do. `output open <number>` keeps working; existing history migrates
+on first read and stays visible. The doctor JSON report is now
+`schemaVersion: 2` — if you script against it, read the three axes rather than a
+single status field.

docs/releases/README.md

@@ -8,4 +8,5 @@ For the live command reference, see [COMMANDS.md](../COMMANDS.md).
 
 ## Index
 
+- [2026-08-14](2026-08-14.md) — Durable media output history, one safe opener, and `aether doctor` v2 (fast / `--live` / `--fix`).
 - [2026-06-09](2026-06-09.md) — Aether Agent rebrand + slash-command console (PRs #4–#16).