chore(stella-media): fix the live-smoke gate, preview labels, branding

[macanderson]

Closes #565

Three of the ten area:media audit items. The other seven are deferred with a reason each — see below. Partial batches are explicitly allowed by the issue.

What changed

Item 1 — the live-smoke opt-in only arms on the literal 1

All three live smokes gated on std::env::var("OXAGEN_MEDIA_LIVE").is_err(), so any value armed them — 0, false, true, the empty string. OXAGEN_MEDIA_LIVE=0 cargo test -p stella-media submitted a real, billable CogVideoX job, while the module doc (adapters/mod.rs:14) and the two adapter comments all promised =1.

The three sites now share one gate in stella-media/src/adapters/mod.rs:

#[cfg(test)]
pub(crate) fn live_smoke_enabled() -> bool {
    live_smoke_armed_by(std::env::var("OXAGEN_MEDIA_LIVE").ok().as_deref())
}

#[cfg(test)]
pub(crate) fn live_smoke_armed_by(value: Option<&str>) -> bool {
    value == Some("1")
}

matching live_smoke_enabled in stella-model/tests/live_smoke.rs:67-69. The comments are unchanged, per the issue's Fix text — the code was the thing that lied.

A named helper (rather than three inline is_ok_ands) is a hair beyond the literal Fix text, and it is deliberate: it is what makes the gate witnessable and stops the three families drifting apart again.

Witness: adapters::tests::only_the_literal_one_arms_the_paid_live_smokes — asserts "1" arms and "0" / "false" / "true" / "yes" / "" / " 1" / "1 " / "01" / unset do not. It asserts over live_smoke_armed_by, the pure half of the gate, instead of mutating the process env: set_var("OXAGEN_MEDIA_LIVE", …) would race the very test threads reading that variable to decide whether to spend money. The test fails to compile on main (the helper does not exist) and passes here.

Item 9 — the plain preview rung labels the kind it was given

plain_line hard-coded [image], so the fallback rung announced a generated video as [image] saved to …/med_x.mp4. That rung is what every non-kitty, non-iTerm2 terminal and every CI run sees.

plain_line and render now take a MediaKind and render [image] / [svg] / [video].

API note: this changes an exported signature — render is re-exported as stella_media::render_preview. There are zero other in-repo callers (stella-tui's render_preview is an unrelated local fn), and cargo check --workspace --all-targets is clean.

Witness: preview::tests::plain_line_labels_the_kind_it_was_given; plain_line_cites_the_path and render_dispatches_by_rung are updated as the issue asks.

Item 7 — branding / description cleanup

• stella-media/src/lib.rs — "for the Oxagen CLI" → "for the Stella CLI" (the binary is stella; it was the only Oxagen CLI hit in the tree).
• stella-context/Cargo.toml — "THE CONTEXT PLANE: …" → "The context plane: …", the only crate description in shouting caps.

Untouched on purpose: the SPDX Copyright (c) 2026 Oxagen, Inc. headers, stella-serve/src/{lib,frame,remote}.rs (a genuine external host), and stella-tui/src/theme.rs:12 (a brand-asset name) — all called out as correct by the issue itself.

No witness (docs/metadata only); verified via cargo metadata.

Checklist from the issue

• adapters/mod.rs:14 — live-smoke gate accepts any value (item 1)
• zai_video.rs:244 — unknown task_status maps to Running forever (item 2)
• artifact.rs:118 — save_with_id silently overwrites + duplicates a manifest row (item 3)
• artifact.rs:200 — append_manifest has no cross-writer lock, fixed temp name (item 4)
• error.rs:65 — MediaError::Cancelled is never constructed (item 5)
• http.rs:98 — download_bytes has no size cap (item 6)
• lib.rs:3 — branding leakage into crate docs and descriptions (item 7)
• operation_journal.rs:517 — journal_error funnels into MediaError::Artifact (item 8)
• preview.rs:106 — plain_line hard-codes [image] (item 9)
• svg.rs:337 — references_external scheme test + style attribute (item 10)

Deferred

Every deferred item is one the issue's own Fix text declines, and each needs a decision this PR is not entitled to make.

Item	Why not here
2 — poll_video unknown task_status	Fix says behavior is unchanged and the trade-off is already recorded in a comment at the _ => arm. The remediation offers two different designs (age-aware terminal check on MediaJobStatus vs. a caller-side deadline) and an unspecified "N minutes". Picking the layer and the timeout is owner judgment, and the failure mode — a provider inventing a new terminal status — is not reproducible locally.
3 — save_with_id overwrite	Fix: "Not fixed: changing write semantics is a behavior change on a path other crates drive." It also leaves a fork open (return the existing ref on a sha256 match vs. fail with MediaError::Artifact), and stella-tools/stella-cli drive this path.
4 — append_manifest locking	Fix: "Not fixed: adding locking to a write path is a behavior change (it can now block or fail on lock acquisition)." Requires lifting JobStore::mutation_lock into a shared helper — a cross-module refactor whose contended behavior I cannot verify with a local run.
5 — MediaError::Cancelled	Fix: "Not fixed: adding cancellation plumbing is an async/signature change across the MediaProvider trait (hard rule 3)", then offers the opposite option (delete the variant). Pure owner judgment on whether cancellation is in scope.
6 — download_bytes size cap	Fix: "Not fixed: adding a cap changes behavior on the shared adapter path." The 64 MiB / 512 MiB numbers are policy the owner sets, and the OOM failure mode is not reproducible in a local test.
8 — journal_error → MediaError::Artifact	Fix: "Not fixed: adding a MediaError::Journal(String) variant is a public-enum change that other crates match on." (For the record: the cross-crate uses in stella-tools/stella-cli are variant constructions, not exhaustive matches, so it would likely still compile — but the enum is public API, the issue disclaims it, and "update the SidecarRace neighbours' docs" is unbounded.)
10 — SVG sanitizer	Fix: "Not fixed: tightening a sanitizer changes behavior, and stella-tools' media tests exercise this path (hard rule 4)" — the issue invokes a hard rule on itself. The prescribed scheme test (<ascii-alpha>[a-z0-9+.-]*:) over all attribute values has real false-positive risk on legitimate SVG (any value containing word:), which would silently strip valid attributes; the existing hostile corpus only tests the attack side, so a green local run would not catch the over-blocking. svg.rs:51-58 already records this under "Known limits". Security-sensitive — half-doing it is worse than not doing it.

Verification

Run from the worktree:

cargo fmt --check                                        # clean
cargo clippy -p stella-media -p stella-context --all-targets -- -D warnings   # clean
cargo test -p stella-media                               # 102 + 1 + 16 passed, 0 failed
cargo test -p stella-context                             # 62 passed, 0 failed
cargo check --workspace --all-targets                    # clean (render signature change)
make no-scratch                                          # OK

stella-context is clippy'd and tested too because this PR touches its Cargo.toml. No pre-existing failures were encountered.

Merge-order note

adapters/{mod,openai_image,zai_image,zai_video}.rs and stella-context/Cargo.toml are also being touched by the PRs for #557 and #560. The edits here are deliberately kept to one added block plus three one-line call-site swaps, and a single description line, so the PRs should merge in any order.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Ready	Preview, Comment	Jul 25, 2026 7:48pm

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery