Session cues and production questions

The session is the primary interface. These commands require Python's standard library and a configured workspace; neither app, Node, provider credentials nor a render worker is needed. Studio's cue capture, transition and production-answer handlers delegate to the same operations.

Capture and inspect

Write an explicit cue request to a local JSON file. A shot request selects its registered prompt, checks its CLEAR receipt and matching hash, and freezes parameters through the existing model manifest. A supplied version must match the current registered version. Capture always creates a held cue. It does not submit work, start a worker, approve a review, establish a price or bypass the existing spend gates.

{"kind":"fire","shot":"S1","params":{"duration":10,"resolution":"480p"},"note":"The director's scoped instruction"}

python -S bin/studio_cues.py --workspace C:/StudioWorkspace capture example ./cue.json --operation-id s1-capture-01
python -S bin/studio_cues.py --workspace C:/StudioWorkspace list example

Choose parameters from the production's model manifest; the example values are not universal defaults. Optional connection must name a declared connection and satisfy the production's lane policy. A bare free cue can record a note; it does not become a renderable prompt by being recorded.

Transition deliberately

python -S bin/studio_cues.py --workspace C:/StudioWorkspace mark example CUE_ID queued --operation-id s1-release-01
python -S bin/studio_cues.py --workspace C:/StudioWorkspace mark example CUE_ID cancelled --operation-id s1-cancel-01

These are separate alternatives, used only when their transition is appropriate. Release makes a cue available to an existing reader. It rechecks the saved prompt hash and the receipt; editing and rechecking a prompt cannot retarget an old cue. A reader still owes its own phase, identity, lane, receipt-freshness and spend checks at execution. A fired cue cannot be cancelled by changing its record. landed accepts --take for a portable production-relative path; failed accepts --error.

Use the same operation ID and exact request to retry a failed response. A committed retry returns its original result, even if a later operation changed the bus. A new ID denotes a new instruction. Optional --expected accepts a JSON map of relative file names to SHA-256 revisions (or null for absence). A stale revision or changed request using the same ID refuses. The bus retains the original capture and every transition; history and bus changes recover together. Read commands do not recover pending writes or release cues.

The older bin/cues.py next/list/mark remains available for existing readers and historical split-root productions. Its mark now accepts --operation-id and uses the same durable transition engine. Prefer studio_cues.py for new scene productions; it enforces the explicit workspace and archive policy. The low-level engine retains compatibility with historical cue buses.

Bench prompts

A request with {"bench":"lighting-test","kind":"free","text":"...","model":"..."} saves a new immutable bench prompt and records its preflight outcome beside the held cue. Supply only actual independent reviewer output in review; ackNoLint is the existing explicit acknowledgement, never an automatic waiver.

python -S bin/studio_cues.py --workspace C:/StudioWorkspace capture _lab/lighting-test ./bench-cue.json --operation-id lighting-01
python -S bin/studio_cues.py --workspace C:/StudioWorkspace list _lab/lighting-test

An interrupted check leaves the reserved prompt version intact. Retrying the exact capture resumes it; it does not allocate another version. A BLOCKED result can still be recorded as held evidence, but cannot be released. A separately saved/reviewed bench prompt can also be captured with a prompt path and a CLEAR receipt. Inspection never checks or renders automatically.

Production questions

python -S bin/studio_asks.py --workspace C:/StudioWorkspace open example direction-01 "Which approved reference should this use?" --operation-id ask-open-01
python -S bin/studio_asks.py --workspace C:/StudioWorkspace list example
python -S bin/studio_asks.py --workspace C:/StudioWorkspace answer example direction-01 "Use reference B." --operation-id ask-answer-01

Questions have stable IDs. An answer preserves the original question and records the answer with history. Retrying the original operation is harmless; a competing answer refuses instead of silently replacing it. Answer text is data: this command never executes it, releases a cue, applies a verdict or authorizes a spend. Open a new question when a decision needs reconsideration.

Production questions live in .studio/asks.jsonl. Optional embedded-session questions in .studio/session/asks.jsonl belong to that session runtime and are separate. Spine stage asks in docs/_asks/ continue through bin/spine.py answer/status and their existing stage checks.

Malformed JSONL, duplicate keys and incomplete final records refuse rather than silently dropping evidence. Preserve the file and reconcile its contents before retrying; do not delete a bus or operation journal to force progress. Shared-operation guarantees cover cooperating writers on a local filesystem, not arbitrary manual edits or network-share durability. CLI exits are 0 for a recorded/read result, 2 for invalid input or refusal, 3 for conflicts/lock timeout, and 4 for I/O failure. A successful bench capture can contain a BLOCKED receipt; capture success is not permission to release.