rig-review 1.18.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -46,10 +46,10 @@ the same CLI. `@rig-c/review` remains the canonical package.
46
46
 
47
47
  The CLI and `@rig-c/review/job-host` managed owner host are supported surfaces. See [Public API stability](docs/STABILITY.md) for the frozen exports and signatures.
48
48
 
49
- Example stdout from `open` (instance values vary):
49
+ Example stdout from `open` (private capability omitted):
50
50
 
51
51
  ```text
52
- http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…
52
+ http://127.0.0.1:4318/?workspace=<incarnation>#cap=…
53
53
  ```
54
54
 
55
55
  ## What you can do
@@ -57,7 +57,7 @@ http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…
57
57
  | Task | Command or panel | Destination |
58
58
  | --- | --- | --- |
59
59
  | **Hand off and compare** | | |
60
- | <a id="one-command-owner-handoff"></a>Open an inspection | `open` | [Owner handoff — WORKFLOWS](docs/WORKFLOWS.md#one-command-owner-handoff) |
60
+ | <a id="one-command-owner-handoff"></a>Open an inspection workspace | `open` | [Owner handoff — WORKFLOWS](docs/WORKFLOWS.md#one-command-owner-handoff) |
61
61
  | <a id="existing-output-handoff"></a>Inspect an existing folder | `check`, `review` | [Existing output handoff — WORKFLOWS](docs/WORKFLOWS.md#existing-output-handoff) |
62
62
  | <a id="compare-two-outputs"></a>Compare two builds against a video | `compare` | [Compare two outputs — WORKFLOWS](docs/WORKFLOWS.md#compare-two-outputs) |
63
63
  | <a id="feedback-ownership"></a>Retrieve submitted feedback | `feedback` | [Feedback ownership — WORKFLOWS](docs/WORKFLOWS.md#feedback-ownership) |
package/docs/DESIGN.md CHANGED
@@ -157,13 +157,13 @@ their missing consumer contracts; no tools are fabricated for them.
157
157
 
158
158
  ### Standing live job boundary
159
159
 
160
- `src/job-contract.ts` freezes the semantic live-job boundary (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session open|publish|ask|next|close` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
160
+ `src/job-contract.ts` freezes the semantic live-job boundary (`JOB_API_SCHEMA` set to `rig-review/job-api@2`, `JOB_ACT_SCHEMA` set to `rig-review/act@2`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session open|publish|ask|next|close` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
161
161
 
162
162
  - **One standing window and owner visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media remain internal. A missing required visual (`visual.status` set to `'unavailable'`) is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
163
163
  - **Human UI authority vs agent verbs.** People submit finalized acts through the browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`) under a bootstrap-declared `reviewer` (`id` and `role` as `'owner'` or `'delegate'`). That reviewer binding is declared by trusted host bootstrap, cannot be typed or overridden in the browser UI, represents provenance rather than keyboard-user authentication, and maps to Create's existing `by` authority. Agents use `publish`, `ask`, `next` and `close` with `expectedGeneration` CAS and `idempotencyKey`. `publish` requires an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record`) held until acknowledgment as a caller obligation, with no watched-root or automatic-close guarantee. Only explicit `close` ends an active job.
164
164
  - **Exact displayed source, cursor replay and draft retention.** Finalized acts and job events replay through durable cursors (`next` and `subscribeJob`). The daemon derives `JobSourceBinding` from validated retained bytes and the page-scoped `displayedNonce` receipt rather than browser-supplied hashes. When a new publication updates the displayed source, old local drafts remain retained for their original source binding and are flagged without rebinding onto the new publication.
165
- - **Enabled vs reserved act kinds.** Five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`) while `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`). Checkpoint acts carry `pass` or `fail` only (`pending` is UI draft only) and require `words` as a string preserved verbatim including empty or whitespace-only text, with `planStepId` copied by the daemon from the validated ask and stage derived by Create. Signoff acts carry `approved` only with required verbatim `words` (empty or whitespace-only allowed) and remain separate from verdicts and Create stage transitions. Plan-bound signoffs (`plan-approved`, `rigging-interview`, `post-interview`) and checkpoints use step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, parts bindings (`JobPartsIdentity`) are limited to the declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal `parts/*.png` images plus exact `painting_in_rig.png` beside `parts.json` (root or project prefix only) — so `figure_mask` is missing and C3 is not yet a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without a Review field parser. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding while unreferenced stale extras are excluded.
166
- - **Writer-owned sibling fetch, public host seam and legacy file handoffs.** [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads via a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration), never tracked in version control or unstaged project output, never constructed or carried by agents, dead at explicit `close`, and renewed on each job incarnation. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` and `bindingId`; equality governs listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside the active cycle. Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files, and existing `--picks-file`, saved verdict path, reshaped feedback JSON and `--verbatim-file` handoffs are legacy/history bypass findings for the active cycle.
165
+ - **Enabled vs reserved act kinds.** Five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`) while `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`). Checkpoint acts carry `pass` or `fail` only (`pending` is UI draft only) and require `words` as a string preserved verbatim including empty or whitespace-only text, with `planStepId` copied by the daemon from the validated ask and stage derived by Create. Signoff acts carry `approved` only with required verbatim `words` (empty or whitespace-only allowed) and remain separate from verdicts and Create stage transitions. Plan-bound signoffs (`plan-approved`, `rigging-interview`, `post-interview`) and checkpoints use step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
166
+ - **Writer-owned sibling fetch, public host seam and legacy file handoffs.** [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads via a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration), never tracked in version control or unstaged project output, never constructed or carried by agents, dead at explicit `close`, and renewed on each job incarnation. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId`, `bindingId` and `partsEnumeratorId`; equality plus API/act schemas and actual enumerator version govern authenticated active-listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside the active cycle. Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files, and existing `--picks-file`, saved verdict path, reshaped feedback JSON and `--verbatim-file` handoffs are legacy/history bypass findings for the active cycle.
167
167
  - **Direction scope.** Direction carriage in `#484` is metadata-only and distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) remains parked.
168
168
 
169
169
  Stage 1 in a single compiled inspection with a producer handoff shows the
@@ -1017,7 +1017,7 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
1017
1017
 
1018
1018
  ## Live job contract
1019
1019
 
1020
- `src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@1`) and `JOB_ACT_SCHEMA` (`rig-review/act@1`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). One-shot file-handoff workflows documented elsewhere in this reference remain preserved as legacy/history compatibility for existing callers.
1020
+ `src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@2`) and `JOB_ACT_SCHEMA` (`rig-review/act@2`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). One-shot file-handoff workflows documented elsewhere in this reference remain preserved as legacy/history compatibility for existing callers.
1021
1021
 
1022
1022
  ### Vocabulary, authority, CLI and host ports
1023
1023
 
@@ -1030,12 +1030,12 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
1030
1030
  - `rig-review session close <job-url> --generation <n> --key <id> --reason <words> [--request-id <id>]`
1031
1031
  Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `http://127.0.0.1:<port>/jobs/<jobId>` and refuse `fetch-act` (`JOB_AUTHORITY_REFUSED`). See [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow) for an ordinary-package launch, bootstrap and explicit close example.
1032
1032
  - **Bootstrap-declared reviewer.** `JobReviewerBinding` (`id` and `role` as `'owner'` or `'delegate'` inside `JobHumanAuthority`) is declared by trusted host bootstrap when opening the window. The browser UI cannot type, edit or override this binding. It records bootstrap-declared provenance rather than keyboard-user authentication. Create maps `role` to its existing `by` authority and preserves the declared reviewer identity.
1033
- - **Trusted host ports and public managed-host startup seam.** `JobHostPorts` separates `handleJobApi` (which accepts agent verbs and consumer `fetch-act` only) from closed same-origin UI routes (`readPublication`, `commitUIAct`, `ackDisplayed`, `jobLiveness`, `subscribeJob`, mounted by `createJobFront` under `/jobs/<jobId>/…` with sealed retained publication routes; the owner HTML root accepts the default or literal `?lang=en` or `?lang=ko` only) that remain unavailable to agent tokens. Raw `Request` objects preserve real `Origin`, capability, body size and abort context. A TypeScript value is never authentication evidence. In the public managed-host startup seam (`startJobHost(options: JobHostOptions): Promise<JobOwnerHost>` from `@rig-c/review/job-host`, where `JobHostOptions extends JobWorkerOptions` adds `readerId?: string` and `bindingId?: string`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), each present hook (`readPublished`, `installWriterBinding`) requires a nonempty declared ID and a missing hook requires its ID to be absent (`JOB_HOST_OPTION_ID_INVALID`). Equal declared IDs permit listener reuse across processes and newly allocated function objects via `/jobs/<jobId>/host` (`schema: 'rig-review-job-host/1'`); differing IDs, hook-presence differences and unrecorded older listener IDs fail by name (`JOB_HOST_REUSE_MISMATCH`) with the option name and both IDs while preserving the existing listener. No function hashes are used. `installWriterBinding` receives `{jobId, origin, fetchCapability}` after reuse validation and runs on a matching new or reused host.
1033
+ - **Trusted host ports and public managed-host startup seam.** `JobHostPorts` separates `handleJobApi` (which accepts agent verbs and consumer `fetch-act` only) from closed same-origin UI routes (`readPublication`, `commitUIAct`, `ackDisplayed`, `jobLiveness`, `subscribeJob`, mounted by `createJobFront` under `/jobs/<jobId>/…` with sealed retained publication routes; the owner HTML root accepts the default or literal `?lang=en` or `?lang=ko` only) that remain unavailable to agent tokens. Raw `Request` objects preserve real `Origin`, capability, body size and abort context. A TypeScript value is never authentication evidence. In the public managed-host startup seam (`startJobHost(options: JobHostOptions): Promise<JobOwnerHost>` from `@rig-c/review/job-host`, where `JobHostOptions extends JobWorkerOptions` adds `readerId?: string`, `bindingId?: string` and `partsEnumeratorId?: string`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), each present hook (`readPublished`, `installWriterBinding`, `partsEnumerator`) requires a nonempty declared ID and a missing hook requires its ID to be absent (`JOB_HOST_OPTION_ID_INVALID`). Equal declared IDs, API/act schemas and actual enumerator versions permit authenticated active-listener reuse across processes and newly allocated function objects via `/jobs/<jobId>/host` (`schema: 'rig-review-job-host/1'`); differing IDs, hook-presence differences and unrecorded older listener IDs fail by name (`JOB_HOST_REUSE_MISMATCH`) with the option name and both IDs while preserving the existing listener. No function hashes are used. `installWriterBinding` receives `{jobId, origin, fetchCapability}` after reuse validation and runs on a matching new or reused host.
1034
1034
  - **Standing window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line (a job survives zero open owner tabs and reuses the same active job/link on later `session open` until explicit `close`). Internal agent and HQ media stay internal. Each `JobPublication` reports `visual` with `status` set to `'available'` or `'unavailable'` with a named `code`. A missing required visual is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
1035
1035
 
1036
1036
  ### Publication, producer-held freeze and generation CAS
1037
1037
 
1038
- - **Mutating requests and CAS.** Agent mutations (`publish`, `ask`, `close` in `JobMutation`) require `expectedGeneration` (a nonnegative safe integer) and `idempotencyKey` alongside `schema` (`rig-review/job-api@1`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`.
1038
+ - **Mutating requests and CAS.** Agent mutations (`publish`, `ask`, `close` in `JobMutation`) require `expectedGeneration` (a nonnegative safe integer) and `idempotencyKey` alongside `schema` (`rig-review/job-api@2`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`.
1039
1039
  - **Explicit producer-held freeze.** `JobPublishRequest` designates a root-relative `result` (`path` and nullable `selector`, never a command) and requires `freeze` with `kind` set to `'producer-held'`, `holdId` and `record` (`JobFileIdentity` for the exact record used for selection, or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved or incomplete record (`JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local CAS. The freeze assertion is a caller obligation on the publishing producer or agent, not a lock Review can impose on independent writers.
1040
1040
  - **Explicit close lifecycle.** Review offers no watched-root or automatic-close guarantee. Only an explicit `close` request (`JobCloseRequest` with `reason`) ends an active job (`status` transitions from `'active'` to `'closed'`, and subsequent mutations or fetches refuse with `JOB_CLOSED`).
1041
1041
  - **Finalized acts and cursor replay.** `JobNextRequest` (`verb` set to `'next'`, `after` cursor or `null`, and daemon-bounded `waitMs`) and `subscribeJob` replay complete durable `JobEvent` items (`published`, `pending`, `act`, `closed`) in order, returning `JobNextValue` (`events`, `cursor`, and `status` as `'events'`, `'timeout'` or `'closed'`). Waiting is abortable and never consumes an act. Invalid cursors refuse with `JOB_CURSOR_INVALID`.
@@ -1055,7 +1055,13 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
1055
1055
  - **`review-verdict`.** `JobActValues['review-verdict']` carries `stage` (`'rig-review'` or `'direction-review'`), `verdict` and `words`, requiring a `rig` or `post` selector and non-null `source.model` with runtime stage, selector and direction consistency checks.
1056
1056
  - **`signoff`.** `JobActValues['signoff']` carries `stage` (validated by Create's writer), `decision` restricted to `'approved'` only (changes requested are a verdict, never a signoff) and required `words` preserved verbatim including empty or whitespace-only strings. A verdict, a signoff and a Create stage transition are three separate writes, and `JobAct` grants no transition authority. Every stage in `JOB_PLAN_BOUND_SIGNOFF_STAGES` (`'plan-approved'`, `'rigging-interview'`, `'post-interview'`) requires non-null `source.plan` with exact displayed step IDs and hashes before act creation, while other stages keep `source.plan` nullable where appropriate.
1057
1057
  - **Create-published step IDs and hashes.** `JobPlanIdentity` holds `steps` (`id` and `hash`) published by [Create #184](https://github.com/rig-c/create/issues/184) for the displayed plan. Review retains these values without importing or recomputing Create's internal `stepHash`. Create validates them through its existing `steps` and `step_hashes` writer logic, with no separate plan revision hash or additional revision gate in this contract.
1058
- - **Manifest-referenced parts PNG set and C3 limitation.** In the current C3 runtime (`JobPartsIdentity` and `src/job-source.ts`), parts binding is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — exact `manifest` (`parts.json` or `${string}/parts.json` and `sha256`) plus lexically ordered unique `images` (`JobPartImagePath` and `sha256`) restricted to normal `parts/*.png` (`parts/${string}.png` or `${string}/parts/${string}.png`) and exact `painting_in_rig.png` beside `parts.json` at the root or project prefix only (`'painting_in_rig.png'` or `${string}/painting_in_rig.png`). Because `figure_mask` is missing from C3, current C3 runtime does not cover the complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without its own `parts.json` field parser or duplicated field rules. Within the current C3 set, missing or changed referenced bytes — including a referenced `painting_in_rig.png` — invalidate the binding, while unreferenced stale extra files are excluded and do not cause refusal. Both the manifest and the bound referenced set enter `sourceHash`, with no new parts filename or migration.
1058
+ - **C4 manifest-referenced parts PNG identity.** C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
1059
+
1060
+ ### C4 schema and stored-state compatibility
1061
+
1062
+ API@1 and unsupported requests refuse `JOB_REQUEST_INVALID` with `JOB_API_SCHEMA_MISMATCH`, HTTP 400, the current API@2 response schema and unchanged generation. The CLI checks response schema before consuming its value. Consumer writers must also check act@2. JobData and host descriptors carry explicit `apiSchema` and `actSchema` markers. Missing or old stored markers refuse `JOB_STORED_SCHEMA_MISMATCH` before credentials, status or replay. Authenticated active-listener reuse compares declared hook IDs, API/act schemas and the actual enumerator version. A stopped listener can be explicitly restarted for the same job with new valid hook IDs. Old retained documents and approvals remain under their original schemas and are never migrated or relabelled. Legacy one-shot contracts retain their documented boundaries.
1063
+
1064
+ The manifest and complete retained image rows enter the composite source hash. Limits are 4096 rows, 128 UTF-16 role units, 4096 path units, 64 MiB per raw file or decoded RGBA allocation and 256 MiB unique retained bytes. Source-bound refusals retain the old head and generation. Reference-set, path, missing-file, PNG, hash and limit details are bounded. A missing row names its official zero-based index, role and manifest-relative path. Create #184 owns its production record projection and consumer checks, which remain pending. [Public boundary](STABILITY.md#parts-enumeration-boundary).
1059
1065
 
1060
1066
  ### Writer-owned sibling fetch capability and consumer writes
1061
1067
 
package/docs/STABILITY.md CHANGED
@@ -10,10 +10,9 @@ The named exports and signatures below are the supported import contract.
10
10
  Changes to them require an explicit public-contract review. The facade reexports
11
11
  the existing implementation and semantic types directly. The semantic schemas
12
12
  and behavior are defined in [Live job contract](REVIEW_PACKAGE.md#live-job-contract).
13
- The current C3 parts binding and the separately queued C4 work remain governed
14
- by that reference.
13
+ The C4 parts binding and schema compatibility are defined by that reference.
15
14
 
16
- At C4 ([Review #501](https://github.com/rig-c/review/issues/501)), `JobPartsManifestPath`, `JobPartImagePath` and `JobPartsIdentity` will change, together with their embedding public types `JobHostOptions`, `JobOwnerHost`, `JobSessionOptions`, `JobSession`, `JobWorkerOptions`, `JobPublicationReader`, `JobPublishedContext`, `JobSourceBinding`, `JobActSources`, `JobAct`, `JobPendingAsk`, `JobPublication`, `JobStatus`, `JobEvent`, `JobNextValue`, `JobResponseValues`, `JobApiResponse`, `JobDisplayPublication` and `JobHostPorts`. This is a declared contract revision that must bump `JOB_API_SCHEMA` and receive HQ sign-off. Current-schema consumers must named-refuse a schema mismatch and must never silently interpret an incompatible payload. The installed smoke control `SMOKE_PUBLIC_HOST_SCHEMA_MISMATCH_REFUSED` sends an unsupported schema through the public host, verifies HTTP 400 with `JOB_REQUEST_INVALID` and the current response schema, and checks that generation remains unchanged, exercising the existing `parseJobRequest` schema guard. [Installed control](https://github.com/rig-c/review/blob/main/scripts/install-smoke.ts#L152), [schema guard](https://github.com/rig-c/review/blob/main/src/job-api.ts#L131).
15
+ C4 changes `JobPartsManifestPath`, `JobPartImagePath`, `JobPartsIdentity` and their embedding public host, publication, source and act types under `JOB_API_SCHEMA` (`rig-review/job-api@2`) and `JOB_ACT_SCHEMA` (`rig-review/act@2`). API@1 and unsupported requests receive HTTP 400 with `JOB_REQUEST_INVALID`, detail `JOB_API_SCHEMA_MISMATCH`, the current response schema and unchanged generation. The CLI validates response schema before consuming values. Consumer writers must check API and act schemas. The C4 candidate requires HQ exact-head sign-off and a parent-owned final contract hash. Create #184 production integration remains pending. [C4](https://github.com/rig-c/review/issues/501), [installed control](https://github.com/rig-c/review/blob/main/scripts/install-smoke.ts).
17
16
 
18
17
  ```ts
19
18
  import {startJobHost} from '@rig-c/review/job-host';
@@ -31,6 +30,7 @@ interface JobSessionOptions {
31
30
  readonly fingerprint: string;
32
31
  readonly reviewer: JobReviewerBinding;
33
32
  readonly readPublished?: JobPublicationReader;
33
+ readonly partsEnumerator?: JobPartsEnumerator;
34
34
  readonly afterSnapshot?: () => void | Promise<void>;
35
35
  readonly afterDirectorySync?: (path: string) => void;
36
36
  }
@@ -47,6 +47,7 @@ interface JobWorkerOptions extends JobSessionOptions {
47
47
  interface JobHostOptions extends JobWorkerOptions {
48
48
  readonly readerId?: string;
49
49
  readonly bindingId?: string;
50
+ readonly partsEnumeratorId?: string;
50
51
  }
51
52
 
52
53
  type JobPublicationReader = (input: {
@@ -64,6 +65,26 @@ interface JobPublishedContext {
64
65
  readonly files: readonly JobFileIdentity[];
65
66
  }
66
67
 
68
+ type JobPartsManifestPath = string; // Work-root-relative, runtime validated.
69
+ type JobPartImagePath = string; // Manifest-directory-relative, runtime validated.
70
+ type JobPartsRole = string; // Bounded string. Membership belongs to Parts.
71
+
72
+ interface JobPartsFileReference {
73
+ readonly path: JobPartImagePath;
74
+ readonly role: JobPartsRole;
75
+ }
76
+
77
+ interface JobPartsEnumerator {
78
+ readonly version: string;
79
+ readonly enumerate: (dir: string) => readonly JobPartsFileReference[];
80
+ }
81
+
82
+ interface JobPartsIdentity {
83
+ readonly enumeratorVersion: string;
84
+ readonly manifest: {readonly path: JobPartsManifestPath; readonly sha256: JobSha256};
85
+ readonly images: readonly {readonly path: JobPartImagePath; readonly role: JobPartsRole; readonly sha256: JobSha256}[];
86
+ }
87
+
67
88
  interface JobOwnerHost {
68
89
  readonly session: JobSession;
69
90
  readonly ports: JobHostPorts;
@@ -97,12 +118,25 @@ available port. `ownerUrl` opens the shipped standing owner page with its privat
97
118
  UI capability fragment. `origin` and the returned `ports` belong to that host.
98
119
 
99
120
  A present `readPublished` callback requires a nonempty `readerId`. A present
100
- `installWriterBinding` callback requires a nonempty `bindingId`. Each ID must be
121
+ `installWriterBinding` callback requires a nonempty `bindingId`. A present
122
+ `partsEnumerator` requires a nonempty `partsEnumeratorId`. Each ID must be
101
123
  absent when its callback is absent. Violations reject startup with
102
124
  `JOB_HOST_OPTION_ID_INVALID`. Equal declared IDs permit active-listener reuse
103
- across processes and newly allocated function objects. Changed or unrecorded IDs
125
+ across processes and newly allocated function objects after an authenticated host probe.
126
+ API/act schemas and the actual enumerator version must match too. Changed or unrecorded IDs
104
127
  reject with `JOB_HOST_REUSE_MISMATCH`, including the option name, listener ID and
105
128
  requested ID. The caller owns the semantic meaning of those IDs.
129
+ After `stop()`, an explicit new startup may change valid hook IDs or enumerator
130
+ version while keeping the same active job. Before allocating for any fingerprint,
131
+ startup checks active rows for that canonical root inside the same store transaction.
132
+ An old or missing stored API/act marker refuses `JOB_STORED_SCHEMA_MISMATCH`, naming
133
+ the canonical root, stored/current schemas and the instruction to close the old job
134
+ with its matching older installation. Old documents remain byte-identical. Current
135
+ schemas retain the existing different-fingerprint partition, and closed old-schema
136
+ rows do not block a new job. Subsequent reads also guard stored schemas before replay. Active listener
137
+ descriptors and authenticated responses with old/missing markers refuse reuse.
138
+ Retained identities and acts keep their original bytes and schemas. They are
139
+ never migrated, relabelled or rebound to new approvals.
106
140
 
107
141
  `readPublished` supplies the producer's published semantic context for the exact
108
142
  frozen record. `installWriterBinding` receives the private finalized-act fetch
@@ -130,6 +164,7 @@ values from the frozen semantic contract.
130
164
  - `startJobHost`
131
165
  - `JOB_API_SCHEMA`
132
166
  - `JOB_ACT_SCHEMA`
167
+ - `JOB_PARTS_ENUMERATOR_RANGE`
133
168
  - `JOB_ENABLED_ACT_KINDS`
134
169
  - `JOB_RESERVED_ACT_KINDS`
135
170
  - `JOB_PLAN_BOUND_SIGNOFF_STAGES`
@@ -163,6 +198,9 @@ without aliases or copied wire shapes.
163
198
  - `JobPartsManifestPath`
164
199
  - `JobPartImagePath`
165
200
  - `JobPartsIdentity`
201
+ - `JobPartsRole`
202
+ - `JobPartsFileReference`
203
+ - `JobPartsEnumerator`
166
204
  - `JobSelector`
167
205
  - `JobSourceBinding`
168
206
  - `JobReviewerBinding`
@@ -198,13 +236,23 @@ without aliases or copied wire shapes.
198
236
  - `JobHostPorts`
199
237
  - `JobConsumerGrant`
200
238
 
239
+ ## Parts enumeration boundary
240
+
241
+ C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
242
+
243
+ The directory passed to the public callback holds the retained `parts.json` bytes. The original paths resolve from the directory holding the bound manifest. The host owns the official import and same-installation version check. A supplied version string alone does not authenticate a replaced callback. Review has no Parts runtime dependency and never installs the producer. Its dev-only 2.25.1 fixture is synthetic reference evidence. Missing or out-of-range versions name the required range and received value through `PARTS_ENUMERATOR_VERSION_MISMATCH`. A claimed version differing from the host installation also refuses.
244
+
245
+ Rows are capped at 4096, roles at 128 UTF-16 code units and literal paths at 4096. Individual raw files and decoded RGBA allocations are bounded at 64 MiB, and unique retained bytes at 256 MiB. Same-path multi-role references retain all rows and seal the physical bytes once. Parts' named manifest refusals are preserved through `PARTS_ENUMERATION_REFUSED`. Consumer refusals include `PARTS_REFERENCE_SET_MISMATCH`, `PARTS_REFERENCE_PATH_REFUSED`, `PARTS_REFERENCE_MISSING`, `PARTS_REFERENCE_PNG_INVALID`, `PARTS_REFERENCE_HASH_MISMATCH` and `PARTS_REFERENCE_LIMIT`. Details carry bounded row/role/path context where applicable. Failed publication preserves the committed head, source, generation and replay state.
246
+
201
247
  ## Installed acceptance
202
248
 
203
249
  `bun run smoke` packs the package and installs that tarball into an empty project.
204
250
  A consumer imports the runtime and every listed type through
205
251
  `@rig-c/review/job-host`. TypeScript checks the installed consumer and the runtime
206
252
  checks the full owner resources, retained publication, semantic ports, declared
207
- hooks, reuse and explicit-close grant lifetime using synthetic host data.
253
+ hooks, enumerator version/row carriage, reuse and explicit-close grant lifetime using synthetic host data.
254
+ This installed control uses an explicitly synthetic injected enumerator. Production
255
+ Create integration and official-import evidence have their separate acceptance gates.
208
256
 
209
257
  The declared export-removal control deletes only `./job-host` from the disposable
210
258
  installed manifest and requires the public import to fail for that missing
package/docs/WORKFLOWS.md CHANGED
@@ -94,10 +94,12 @@ The footer fits its measured text while retaining full hashes. Text is drawn in
94
94
 
95
95
  ## One-command owner handoff
96
96
 
97
- `open` validates and hashes an existing folder, starts a background loopback
98
- instance or reuses the exact matching one, prints its hash-bound URL, and exits.
99
- By default the URL goes through the managed front at `127.0.0.1:4318`; `--direct`
100
- prints the instance's own port instead (see [Managed front and write capability](#managed-front-and-write-capability)):
97
+ `open` validates and hashes designated folders, starts or reuses one background
98
+ loopback owner workspace, prints its owner URL, and exits. **N rigs → one
99
+ invocation, one owner link.** Targets share one listener-owning process and port.
100
+ The default port is `127.0.0.1:4318`; `RIG_REVIEW_FRONT_PORT` selects an explicit
101
+ port. The URL has the form `http://127.0.0.1:4318/?workspace=<incarnation>#cap=…`; keep its capability
102
+ private and give the person one link plus one what-to-look-at line.
101
103
 
102
104
  ```sh
103
105
  bun run open -- /absolute/output --reference /absolute/original.mp4
@@ -142,8 +144,9 @@ checkpoints do not apply another clip's time or axis. Static/source-only package
142
144
  remain inspectable without claiming clip selection; explicit unvalidatable clips
143
145
  refuse. Single review sessions remain package-wide; animation selection does not
144
146
  create an animation-specific approval identity. Opening never
145
- approves a review. The command prints the matching feedback retrieval command on
146
- stderr; stdout contains the URL alone. A selected external video takes precedence
147
+ approves a review. Retrieve submitted feedback with the original per-target input and handoff
148
+ arguments; stdout contains the owner URL alone. The workspace summary on stderr
149
+ does not print a per-target feedback command. A selected external video takes precedence
147
150
  at automatic startup; an explicit checkpoint link or manual checkpoint selection
148
151
  still chooses that checkpoint's reference.
149
152
 
@@ -162,28 +165,105 @@ binding. Headless equivalent (the original declared-reference form stays valid):
162
165
  rig-review strip /absolute/output --reference-video /absolute/original.mp4 --animation dance --frames 176:184 --out /absolute/external/strip.png
163
166
  ```
164
167
 
165
- Only tool-owned instances with matching content, canonical input locations, tool
166
- fingerprint and a private capability handshake are reused. The URL hash is
167
- checked before serving the app; a stale link never selects another instance's
168
- package. Input hashes are freshly computed, not trusted from mtime caches. In both
169
- `open` and foreground `review` / `review compare`, each open window holds a live
170
- WebSocket connection (`/api/live`); once the last window closes and stays at zero connections
171
- for the 3-second grace period, or if no window ever connects within 30 minutes
172
- (reusing a windowless worker via `open` gives it a fresh 30-minute unopened window),
173
- the server finishes any in-flight request or Apply, flushes state, prints one line
174
- stating why it exited, and exits `0`. A browser that unloads a background tab to
175
- save memory looks the same as a closed tab, so the server stops; saved feedback
176
- survives and `open` brings it back. Their
177
- private registry, requests and logs live beside feedback under
178
- `~/.local/state/rig-c-review/open/`; nothing is written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
179
- outside all input packages, judged by its canonical location (symlinks in the path
180
- and its existing ancestors resolved). Existing foreground review commands still work.
168
+ ### Multiple targets and repeated open
181
169
 
182
- No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
183
- printed: every current instance binds only `127.0.0.1`.
170
+ `--animation` supplies the default clip for every target. Repeat
171
+ `--animation-for <index> <name>` to override distinct 1-based target positions.
172
+ This opens nine rigs, selecting `walk` for `dirB` and `idle` for the others.
184
173
 
185
- The printed feedback retrieval command uses POSIX shell quoting for literal path
186
- arguments. It is not a PowerShell or cmd.exe command string.
174
+ ```sh
175
+ rig-review open dirA dirB dirC dirD dirE dirF dirG dirH dirI \
176
+ --animation idle --animation-for 2 walk --view-only
177
+ ```
178
+
179
+ Indices outside the target list, invalid indices and duplicate overrides refuse
180
+ with `OPEN_OPTION_INVALID`. Common typed options apply to each target and retain
181
+ their existing validation. Each animation is validated against its own model.
182
+ A single primary target can use `--compare <other-dir>` with an explicit
183
+ `--reference <video>`; a multi-target batch with `--compare` is refused.
184
+ `--direct` accepts one primary target only.
185
+
186
+ Compatible repeated opens add to the same owner list and print the same root
187
+ owner URL, including its owner capability within that host incarnation. They exit
188
+ 0 and add no listener or resident per-rig worker.
189
+
190
+ ```sh
191
+ rig-review open dirA --animation idle --view-only
192
+ rig-review open dirB --animation walk --view-only
193
+ rig-review feedback dirA --animation idle --format json
194
+ ```
195
+
196
+ A consumer opened N rigs with N sequential `open` calls. Use the batch form when
197
+ all targets are known together. Duplicate compatible registrations reuse the
198
+ entry; conflicting options refuse with `WORKSPACE_TARGET_OPTIONS_MISMATCH`.
199
+ The owner selects targets from the list. `--view-only` entries are labelled
200
+ **Inspection only** and have no semantic act or pending approval. Existing
201
+ feedback semantics still apply within each inspection. Retrieve submitted
202
+ feedback using each target's exact original inputs, references and handoff
203
+ arguments. A shared owner URL supplies no feedback identity or approval.
204
+
205
+ Inspection frames load on selection and remain retained for their target's
206
+ camera, time, selected part/panel and source-bound draft. Switching pauses hidden
207
+ playback. Reviewer-authored words remain verbatim. Admission and retained frames
208
+ share a 32-target application limit. Adding target 33 refuses atomically with
209
+ `WORKSPACE_TARGET_LIMIT`, preserving the existing registrations. This bound is
210
+ an application limit, not a hardware memory or performance guarantee.
211
+
212
+ ### Workspace lifecycle and restart
213
+
214
+ The workspace owns one aggregate live lifecycle, shared by the owner page and
215
+ its target contexts. Target contexts have no independent server shutdown timers.
216
+ After all live connections close, the workspace waits the 3-second grace period
217
+ and for registrations, active response streams and target work to finish before
218
+ stopping. A workspace with no connected page has a 30-minute unopened window;
219
+ a successful registration re-arms that window when no page is connected.
220
+ These timers apply to the whole workspace. The separate per-instance behavior is
221
+ preserved under [Direct server and legacy lifecycle](#direct-server-and-legacy-lifecycle).
222
+
223
+ Reuse requires the same UID, installation, runtime and fingerprint, the designated
224
+ port and an authenticated live-host response. Mismatches refuse with
225
+ `WORKSPACE_OWNER_MISMATCH` or `WORKSPACE_HOST_MISMATCH`. A live but unresponsive
226
+ PID refuses with `WORKSPACE_HOST_UNRESPONSIVE`; a timeout leaves its ownership
227
+ intact. Concurrent launchers coordinate registration through the private store.
228
+
229
+ Restart creates a new host incarnation and rotates owner, launcher and target
230
+ secrets. The nonsecret `workspace` query changes with the incarnation, so opening
231
+ the new link in an existing tab loads a new document. Repeated opens within one
232
+ incarnation retain the same URL. Run `open` again and give the person the new
233
+ owner link. A supplied `workspace` query must match the current host; root links
234
+ without it remain accepted. Persisted input
235
+ designations are revalidated. Changed sources appear unavailable with
236
+ `WORKSPACE_SOURCE_CHANGED`; saved feedback and drafts retain their original
237
+ source binding. Registering another valid target remains possible when an
238
+ unrelated target's source has changed.
239
+
240
+ If a legacy front or another listener occupies the chosen port, launch refuses
241
+ with `FRONT_PORT_BUSY` and the instruction `use --direct` or set
242
+ `RIG_REVIEW_FRONT_PORT` explicitly. For example, choose another workspace port
243
+ with `RIG_REVIEW_FRONT_PORT=4320 rig-review open dirA --view-only`.
244
+ Leave existing workers and listeners under their current owner's control.
245
+
246
+ Workspace descriptors, designations, startup requests and logs live under
247
+ `<state>/owner-workspace/`, with private owner/launcher credentials and distinct
248
+ target capabilities. State stays outside every input package. Loopback-only,
249
+ same-origin bounded JSON mutations and contained package paths remain required.
250
+ Registration carries designated package inputs. Agents use supported commands
251
+ and APIs and never construct internal Review state or human acts.
252
+
253
+ ### Subsequent CLI and semantic paths
254
+
255
+ Plain foreground multi-target invocation and its compatible workspace joining
256
+ remain pending. The current delivery is the `open` CLI workspace. Core's
257
+ `rigc review` passes arguments through unchanged; Review owns the CLI grammar.
258
+
259
+ The embedded semantic-job hub also remains pending. Its same-process host will
260
+ own trusted `readPublished`, `partsEnumerator` and `installWriterBinding`
261
+ callbacks. General cross-process callback transport is deferred. Each job retains
262
+ independent source, reviewer, capabilities, generation CAS, cursor, displayed
263
+ acknowledgment and writer grant under job-api@2/act@2. Registration-handle detach,
264
+ host stop and semantic close remain separate lifecycle concerns. Follow the
265
+ current [standing live-job workflow](#standing-live-job-workflow) and
266
+ [public host contract](STABILITY.md#managed-owner-host) for semantic jobs.
187
267
 
188
268
  ### Launcher contract
189
269
 
@@ -192,7 +272,10 @@ stderr and exit code alone:
192
272
 
193
273
  1. On success stdout is exactly one line, the URL. `open` never writes anything
194
274
  else to stdout.
195
- 2. On success stderr carries the human lines in this fixed order: for the `check/`
275
+ 2. Managed workspace success writes per-target package/handoff and animation
276
+ diagnostics in target order, then `Review workspace started|reused; N target(s).
277
+ Retrieve feedback using the original input designation.` The direct-server
278
+ path retains the following stderr order. For the `check/`
196
279
  package of a `rig-parts build` output, `Package: rig-parts build check package <path>`
197
280
  and the handoff line (`Handoff <how>: <config path> sha256 <hash> · parts <dir>`, or
198
281
  `Handoff: <refusal>`); the animation diagnostic (when a clip is selected), the control notice (with `--control`),
@@ -205,20 +288,58 @@ stderr and exit code alone:
205
288
  - `OPEN_ANIMATION_UNKNOWN <name>`: the explicit or report-named clip (JSON-quoted) is not in the compiled model.
206
289
  - `OPEN_ANIMATION_AMBIGUOUS`: no flag or report selects one clip, or the A/B reports conflict.
207
290
  - `OPEN_ANIMATION_UNVALIDATABLE`: a clip was requested but no compiled model can validate it.
208
- - `OPEN_OPTION_INVALID <flag>`: an unknown, duplicate, empty or value-less option, a handoff flag without `--config`, `--source` without `--full` (or the reverse), or a handoff flag with `--compare`.
291
+ - `OPEN_OPTION_INVALID <flag>`: an unknown, duplicate, empty or value-less option, an invalid/out-of-range/duplicate `--animation-for` index, multi-target `--compare` or `--direct`, a handoff flag without `--config`, `--source` without `--full` (or the reverse), or a handoff flag with `--compare`.
209
292
  - `OPEN_STATE_INSIDE_PACKAGE <package | build root | handoff root>`: the state directory (`RIG_REVIEW_STATE_DIR` or the default), resolved through symlinks, lies inside an input package, the `rig-parts build` root a check package belongs to, or the producer handoff's root.
210
293
  - `OPEN_HANDOFF_INVALID <flag or path>`: a declared or discovered producer handoff path is refused — `HANDOFF_PATH_OUTSIDE_ROOT`, `HANDOFF_SYMLINK_ESCAPE`, `HANDOFF_INPUT_MISSING`, `HANDOFF_INPUT_INVALID` or `HANDOFF_PATH_INVALID`, named after the colon.
211
294
  4. Exit codes: 0 applied, 1 refused. (`control` keeps its own exit 2 for an
212
295
  unapplied command.)
213
296
 
214
- Package validation and worker startup refusals keep their existing messages; the
215
- named refusals above are decided before any state is written.
297
+ Input validation precedes workspace registration. Workspace startup and
298
+ registration refusals retain their named codes and exit 1. A refused batch
299
+ registration leaves existing registrations intact. Direct-worker refusals keep
300
+ their existing messages.
301
+
302
+ ### Direct server and legacy lifecycle
303
+
304
+ Use `rig-review open dirA --direct --animation idle --view-only` for a separate
305
+ single-target server. It prints the worker's own URL and retains the per-instance
306
+ lifecycle and hash-bound handoff described here. Foreground `review` and
307
+ `review compare` retain their existing separate-server behavior.
308
+
309
+ Only tool-owned instances with matching content, canonical input locations, tool
310
+ fingerprint and a private capability handshake are reused. The URL hash is
311
+ checked before serving the app; a stale link never selects another instance's
312
+ package. Input hashes are freshly computed, not trusted from mtime caches. In both
313
+ `open --direct` and foreground `review` / `review compare`, each open window holds a live
314
+ WebSocket connection (`/api/live`); once the last window closes and stays at zero connections
315
+ for the 3-second grace period, or if no window ever connects within 30 minutes
316
+ (reusing a windowless worker via `open --direct` gives it a fresh 30-minute unopened window),
317
+ the server finishes any in-flight request or Apply, flushes state, prints one line
318
+ stating why it exited, and exits `0`. A browser that unloads a background tab to
319
+ save memory looks the same as a closed tab, so the server stops; saved feedback
320
+ survives and `open --direct` brings it back. Their
321
+ private registry, requests and logs live beside feedback under
322
+ `~/.local/state/rig-c-review/open/`; nothing is written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
323
+ outside all input packages, judged by its canonical location (symlinks in the path
324
+ and its existing ancestors resolved). Existing foreground review commands still work.
325
+
326
+ No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
327
+ printed: every current instance binds only `127.0.0.1`.
328
+
329
+ The printed feedback retrieval command uses POSIX shell quoting for literal path
330
+ arguments. It is not a PowerShell or cmd.exe command string.
216
331
 
217
332
  ### Managed front and write capability
218
333
 
219
- `open` is **managed by default**. It ensures one detached loopback front at
334
+ This heading preserves the legacy per-instance managed-front reference. Current
335
+ default `open` uses the [owner workspace](#one-command-owner-handoff).
336
+ `open --direct` serves its worker directly.
337
+
338
+ #### Legacy per-instance proxy
339
+
340
+ The earlier managed launcher ensured one detached loopback front at
220
341
  `127.0.0.1:4318` (`RIG_REVIEW_FRONT_PORT` overrides) for the state directory and
221
- prints `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
342
+ printed `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
222
343
  inspection therefore shares one stable browser origin, so Settings, panel sizes and
223
344
  source-bound drafts survive a reopen. The front only routes: it takes the worker
224
345
  address from that key's private open record, allows a closed per-method route
@@ -235,10 +356,12 @@ If another listener holds the front port, `open` fails with
235
356
  does not fall back silently. `open --direct` keeps the per-instance port and
236
357
  prints that worker's own URL.
237
358
 
359
+ #### Direct and legacy write capability
360
+
238
361
  One origin cannot isolate scripts that run on it, so writes are bound to a
239
362
  per-instance capability rather than to the page's origin or the key in its path.
240
363
  Each worker mints a 256-bit capability kept only in its private 0600 open record.
241
- `open` (managed or direct) and the foreground `review`/`review compare` commands
364
+ The legacy managed launcher, `open --direct` and the foreground `review`/`review compare` commands
242
365
  print it in the `#cap=` fragment, which browsers never send to a server. That
243
366
  printed link goes only to the terminal of the command that started the instance.
244
367
  Output meant for a log does not carry it: the install smoke (`bun run smoke`, whose output CI publishes) prints the same
@@ -249,7 +372,8 @@ checks it before forwarding and the worker compares it again in constant time
249
372
  before its existing same-origin check. No endpoint returns it, so a page opened
250
373
  for one instance cannot submit to another. A copied view link (without the
251
374
  fragment) opens read-only and says *Read-only view: reopen with rig-review open to
252
- edit*; run `open` again for a writable link.
375
+ edit*; run `open --direct` again for a writable per-instance link. Current workspace
376
+ owner links use the separate incarnation-bound capability described above.
253
377
 
254
378
  ## Control the current inspection page
255
379
 
@@ -273,7 +397,7 @@ rig-review control /absolute/output --reference /absolute/original.mp4 --page '<
273
397
 
274
398
  Use the same reference/compare/animation inputs as the controlled `open`. Multiple
275
399
  pages require an explicit `--page`. The URL and source binding stay unchanged;
276
- existing ordinary servers do not become controllable. Starting the opt-in worker
400
+ existing ordinary servers do not become controllable. Registering the opted-in target
277
401
  is a one-time handoff, not a new link for each parameter change.
278
402
 
279
403
  Commands cover appearance, automatic layout, synchronized or independent pane
@@ -360,7 +484,7 @@ The managed front forwards only the trusted stage-atlas frame query (`stageEmbed
360
484
 
361
485
  ## Standing live job workflow
362
486
 
363
- The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) for the full schema and host seam reference.
487
+ The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@2`, `JOB_ACT_SCHEMA` set to `rig-review/act@2`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) for the full schema and host seam reference.
364
488
 
365
489
  Exact CLI usage from `src/entry.ts` and `src/job-cli.ts` (`publish`, `ask`, `next` and `close` also accept optional `--request-id <id>`):
366
490
 
@@ -400,8 +524,8 @@ rig-review session close http://127.0.0.1:<port>/jobs/<job-id> \
400
524
  - **Explicit producer-held freeze and explicit close.** Every `publish` request designates a root-relative `result` (`path` and `selector`, never a command) and carries an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record` as `JobFileIdentity` or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved record (`JOB_RECORD_MOVED`, `JOB_RECORD_INCOMPLETE`, `JOB_FREEZE_REQUIRED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local generation CAS (`JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`). The freeze assertion is a caller obligation rather than a lock Review can impose on independent writers. Review offers no watched-root or automatic-close guarantee, and only explicit `close` ends an active job.
401
525
  - **Exact displayed source and retained drafts.** The daemon derives `JobSourceBinding` from validated retained bytes and the actual displayed publication (`ackDisplayed` returning a page-scoped `displayedNonce` receipt, pinned same-origin `routes` with no mutable current alias). All metadata, images, runtime assets, routes and pending form dependencies prepare before the visible swap; paint and the single `displayedNonce` acknowledgment precede retirement of the previous view, and failed preparation or acknowledgment restores the prior view and draft. Clients never supply trusted source hashes or transfer prior approval onto a new binding. When a new publication updates the displayed source, old local drafts remain retained in storage for their original source binding and are flagged without rebinding onto the new publication.
402
526
  - **Finalized acts, five enabled kinds and cursor replay.** `next` (`after` cursor and bounded abortable `waitMs` that never consumes an act) and `subscribeJob` replay complete durable `JobEvent` records (`published`, `pending`, `act`, `closed`). Only five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`). `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`).
403
- - **Checkpoints, signoffs, plan steps and parts PNGs.** In `checkpoint` acts, `outcome` is `'pass'` or `'fail'` only (`'pending'` stays in the UI draft and never produces a finalized act), and required `words` is preserved verbatim as a string including empty or whitespace-only text. The browser sends `checkpointId`, `outcome` and `words` only while the daemon copies resolved `planStepId` from the validated ask, and Create derives execution stage from its authoritative step phase and order without Review stamping a stage. Only `'pass'` is eligible for Create's checkpoint sign-off writer, while `'fail'` is feedback or a named consumer refusal. In `signoff` acts, `decision` is `'approved'` only (changes requested are a verdict) with required `words` preserved verbatim including empty or whitespace-only text. A verdict, a signoff and a Create stage transition are three separate writes, and plan-bound signoff stages (`plan-approved`, `rigging-interview`, `post-interview`) require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, `JobPartsIdentity` is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal images at `parts/*.png` (`parts/${string}.png` or `${string}/parts/${string}.png`) plus exact `painting_in_rig.png` beside `parts.json` at the root or project prefix only (`painting_in_rig.png` or `${string}/painting_in_rig.png`) — so `figure_mask` is missing and C3 does not yet cover a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without parsing `parts.json` fields itself. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding, while unreferenced stale extra files are excluded without refusal.
404
- - **No agent file carriage, writer-owned sibling fetch and public host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and act fetch through a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration). That binding is never tracked in version control or unstaged project output, dies at explicit `close` with a new grant per job incarnation, and grants read-only `fetch-act` over loopback with `Authorization`. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` for `readPublished` and `bindingId` for `installWriterBinding`; missing or invalid IDs refuse with `JOB_HOST_OPTION_ID_INVALID`, and listener reuse requires equal `readerId` and `bindingId` or refuses with `JOB_HOST_REUSE_MISMATCH` (with no function hashes). Future mesh-edit consumption is owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159), where Create fetches a finalized mesh act and passes its typed value in process to Parts' public exported API without Parts reading Review or Create storage.
527
+ - **Checkpoints, signoffs, plan steps and parts PNGs.** In `checkpoint` acts, `outcome` is `'pass'` or `'fail'` only (`'pending'` stays in the UI draft and never produces a finalized act), and required `words` is preserved verbatim as a string including empty or whitespace-only text. The browser sends `checkpointId`, `outcome` and `words` only while the daemon copies resolved `planStepId` from the validated ask, and Create derives execution stage from its authoritative step phase and order without Review stamping a stage. Only `'pass'` is eligible for Create's checkpoint sign-off writer, while `'fail'` is feedback or a named consumer refusal. In `signoff` acts, `decision` is `'approved'` only (changes requested are a verdict) with required `words` preserved verbatim including empty or whitespace-only text. A verdict, a signoff and a Create stage transition are three separate writes, and plan-bound signoff stages (`plan-approved`, `rigging-interview`, `post-interview`) require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
528
+ - **No agent file carriage, writer-owned sibling fetch and public host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and act fetch through a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration). That binding is never tracked in version control or unstaged project output, dies at explicit `close` with a new grant per job incarnation, and grants read-only `fetch-act` over loopback with `Authorization`. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` for `readPublished` and `bindingId` for `installWriterBinding` and `partsEnumeratorId` for `partsEnumerator`; missing or invalid IDs refuse with `JOB_HOST_OPTION_ID_INVALID`, and listener reuse requires equal `readerId`, `bindingId` and `partsEnumeratorId` or refuses with `JOB_HOST_REUSE_MISMATCH` (with no function hashes). Future mesh-edit consumption is owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159), where Create fetches a finalized mesh act and passes its typed value in process to Parts' public exported API without Parts reading Review or Create storage.
405
529
  - **Direction metadata vs playback.** Direction carriage in `#484` is metadata-only (`source.direction` and `direction-review`) and is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) stays parked.
406
530
 
407
531
  ## Create choice interview
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "1.18.0",
3
+ "version": "2.1.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -25,6 +25,7 @@
25
25
  "pngjs": "7.0.0"
26
26
  },
27
27
  "devDependencies": {
28
+ "@rig-c/parts": "2.25.1",
28
29
  "@types/bun": "^1.3.0",
29
30
  "typescript": "^5.9.3"
30
31
  },