feat(orchestra): typed ArtifactManifest + flat per-flow run-root bundle

[proksh]

Stacked on #3282. Makes Maestro core own a typed, self-documenting artifact manifest, and restructures the CLI's debug output into one per-flow folder per run — so local and cloud emit the same shape and every consumer reads one model instead of re-deriving artifact types from a folder of files.

What this adds

1. Shared model (maestro-orchestra-models) — ArtifactManifest, ArtifactEntry, ArtifactKind, ArtifactFormat, and ArtifactFiles (canonical relative paths). Plain data classes, no serialization annotations — tolerance is the consumer's choice.

2. Self-documenting manifest.json — it carries a $schema pointing at a stable, versioned URL: the hand-written schema served straight from this repo's main branch via GitHub raw (…/mobile-dev-inc/Maestro/main/maestro-orchestra-models/.../manifest.v1.schema.json). The filename carries the schema's major version (schemaVersion), so a future structural change ships as manifest.v2.schema.json beside it and the v1 URL keeps resolving for every manifest already in the wild. The URL is the schema's permanent identity, so the manifest stays self-describing even after it's copied or uploaded away from its run folder — with no per-run schema file to bundle and no hosting to stand up (it's just the in-repo file). Within a version, pointing at main keeps the URL constant while its content tracks additive changes; that's safe because the model ignores unknown fields and a build test fails if any ArtifactKind/ArtifactFormat is missing from the schema, so docs can't drift from code. Trade-off: resolving it needs network — the offline-bundled copy was intentionally dropped. Note: the URL 404s until this work lands on main.

3. Core produces the bundle (maestro-orchestra) — ArtifactsGenerator (an internal OrchestraListener) writes the per-flow bundle into artifactsDir and builds the manifest, exposed on Orchestra.FlowResult.artifactManifest. The run root itself is the zippable bundle — everything core makes sits directly under it, with no intermediate artifacts/ folder:

• commands.json (per-command metadata) and logs/maestro.log at the run root. Serialized errors are slim — message + debugMessage only; hierarchies and stack traces live in their own artifacts.
• Typed per-command metadata.artifacts — each command entry in commands.json lists {type, path} objects (run-root-relative; type is an ArtifactKind name), so consumers find per-command artifacts without depending on the folder layout. The manifest stays folder-level — no per-file entries. Empty lists are omitted. Plumbing: a new OrchestraListener.onCommandArtifact(kind, relativePath) hook, dispatched only when a bundle is being produced.
• Self-describing kinds — TAKE_SCREENSHOT (takeScreenshot output → takeScreenshot/), START_SCREEN_RECORDING (startRecording output → startRecording/), SCREENSHOT (step screenshots → screenshots/step-<N>.png), SCREEN_RECORDING (full-run recording), SCREEN_HIERARCHY (per-step hierarchy JSON). No metadata.source tags on these — the kind says it; source remains only where it carries real information (e.g. DEVICE_LOG).
• Per-step view hierarchy, always on — every executed command writes screen-hierarchy/step-<N>.json and references it from its artifacts; the giant inline hierarchy blob is gone from commands.json (demo run: 246 KB → 4 KB).
• Unified screenshots — one folder, one naming scheme: with captureStepScreenshots on (worker), every executed command gets screenshots/step-<N>.png; with it off (local CLI), only the failed command does. No special screenshot-❌-*.png convention — the failure shot is the FAILED command's SCREENSHOT artifact in commands.json.
• Flag-gated capture (off by default; the worker turns them on): captureStepScreenshots (above) and captureScreenRecording → screen-recording.mp4.
• When there's no artifact dir (e.g. --continuous), takeScreenshot/startRecording write relative to CWD, as before.

4. CLI writes one folder per flow (maestro-cli) — each flow's output folder is resolved upfront and passed as the single artifactsDir; Orchestra writes the whole bundle straight into it. Single and suite runs both produce <output>/<ts>/<flow>/ (with -shard-N / -N suffixes for shards / name collisions). Replaces the old flat session layout and its temp-staging + copy step.

Layout

<output>/<ts>/<flow>/          # the run root IS the "artifacts" zip = everything core makes
  manifest.json
  commands.json
  logs/
    maestro.log
    …device logs, crash/ANR    # worker/cloud only (see #3346)
  takeScreenshot/…             # takeScreenshot command output
  startRecording/…             # startRecording command output
  screenshots/step-N.png       # step screenshots (all steps when flag on; failed step only when off)
  screen-hierarchy/step-N.json # per-step view hierarchy (always on)
  screen-recording.mp4         # full-run recording (flag-gated: worker on, CLI off)

The manifest uses paths relative to its own folder, so local and cloud manifests look the same.

Behavior change to flag

--test-output-dir, when set, is this artifact folder — it now holds the full bundle (incl. manifest.json), not just screenshots. Its help text is updated. The default location (~/.maestro/tests/<ts>/) is unchanged.

How this was tested

• Model tests — manifest round-trips, ignores unknown fields, and a build check fails if any artifact kind is missing from the schema.
• Orchestra tests — manifest entries carry the right dedicated kinds with run-root-relative paths and no redundant source tags; folders register as collections with a file count; step screenshots/recording appear per their flags; hierarchy files are written per executed command (not for skipped), attributed, and commands.json has no inline hierarchy; typed artifacts attribute to the right command (incl. nested/composite dedup) and the key is omitted when empty; serialized errors carry only message + debugMessage; manifest.json carries the stable, versioned $schema URL and no schema file is bundled.
• Local e2e — ran the built CLI against an iOS simulator (default and worker-flag modes): the takeScreenshot entry carries {"type": "TAKE_SCREENSHOT", "path": "takeScreenshot/checkout.png"}, every executed command references its screen-hierarchy/step-N.json, the failed command references screenshots/step-4.png, all paths resolve, and commands.json shrank 246 KB → 4 KB.
• CLI tests — per-flow folder naming: slashes sanitized, shard suffix, and same-name collisions.

[linear-code]

MA-4055

[steviec]

@proksh I worked with Claude to generate this. I'll attach the conversation so you can see how I got there. Please note that this is a first pass conversation, but it immediately picked up on the architectural problems I noticed in this PR on my first scan. If core is going to own the artifacts, it needs to really own them, and not just find them.

The "artifact policy" idea is interesting, but it might not be necessary. If we are only in two modes: record everything vs record a lighter subset, that might be better as a single boolean flag.

---

Artifact manifest: record, don't scan

The RFC call is right — one typed manifest owned by Orchestra, identical local and cloud. The implementation undermines it: it derives the manifest by scanning the run-root folders at flow end instead of recording artifacts as they're produced. Most of the issues below follow from that.

Problems

• Three registration paths, no single source of truth: a listener event (only the two command outputs), direct in-generator appends, and an end-of-run disk scan. The folder-level manifest and per-command list can disagree.
• The scan can't see what core didn't hardcode — pushed/user files and anything a non-core producer adds are invisible.
• No single "register an artifact" operation, so the manifest is core-sealed; absorbing device logs required re-implementing their capture in core (feat(orchestra): device logs + crash/ANR under logs/ #3346). Doesn't generalize.
• Capture gating is three inconsistent rules (booleans for screenshots/recording, always-on for device logs), none client-selectable.
• ArtifactFiles paths are a constant shared between writers and the scanner — that shared agreement is the drift surface.

Fix: a single collector that owns path allocation and the record. Producers go through it; the manifest is its records, the per-command list the same records grouped by command. Two verbs: allocate(kind, producer) → path for what we write (recorded atomically — can't write into the bundle unrecorded), adopt(kind, file, producer) for what's collected from outside (crash dumps, log streams). producer is a field, so worker- vs core-produced is data, not a second code path. Capture becomes one requested-artifact policy. ArtifactFiles becomes the collector's private layout, not a shared contract.

Layering (open decision): core manifest sealed/immutable at flow end; backend wraps it in a run envelope (run id, signed URLs, post-hoc cloud artifacts) that's a superset of the same entry type. Avoids a mutable manifest and the "when is it final" ambiguity.

PR impact: keep the model types, schema, driver seam, and flat layout. Replace the disk scan with collector accumulation; route every writer through allocate/adopt and delete the self-append/scan paths; swap the capture booleans for a policy; add producer to ArtifactEntry without building a separate worker-append path. Net less code than today.

---

Chat:
2026-06-12-133345-local-command-caveatcaveat-the-messages-below.txt