@rig-c/review 2.0.0 → 2.2.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,8 +57,8 @@ 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) |
61
- | <a id="existing-output-handoff"></a>Inspect an existing folder | `check`, `review` | [Existing output handoff — WORKFLOWS](docs/WORKFLOWS.md#existing-output-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
+ | <a id="existing-output-handoff"></a>Inspect existing folders | `check`, `review DIR...` | [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) |
64
64
  | <a id="frame-strip-export"></a>Export feedback intervals as strips | `strip` | [Frame strip export — WORKFLOWS](docs/WORKFLOWS.md#frame-strip-export) |
@@ -483,8 +483,10 @@ A private bounded `/api/open-status` handshake requires its instance capability,
483
483
  returns matching identity, and verifies current input hashes. The state registry
484
484
  never makes a PID/port alone authoritative. Changed input, reference, mode,
485
485
  canonical input location or actual tool source/static fingerprint gets a distinct
486
- instance identity. Existing foreground servers do not gain an open registration
487
- or browser filesystem API.
486
+ instance identity. Existing single foreground servers retain their direct lifecycle.
487
+ Plain multi-target foreground review uses the shared owner workspace registration
488
+ and capabilities described in [WORKFLOWS](WORKFLOWS.md#subsequent-cli-and-semantic-paths).
489
+ Neither path supplies a browser filesystem API.
488
490
 
489
491
  Registry/request/log/claim files are private tool-state files; a per-binding claim
490
492
  serializes startup, stale records are not reused, and no unrelated process is
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,130 @@ 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 multi-target review starts a workspace in the foreground CLI process:
256
+
257
+ ```sh
258
+ rig-review dirA dirB --animation idle --animation-for 2 walk --view-only
259
+ ```
260
+
261
+ A new owner prints `Review ready: <owner URL>` and stays in that terminal. Its
262
+ SIGINT/SIGTERM handlers await shutdown of the one listener and its contexts.
263
+ The same aggregate last-window and unopened timers described above apply.
264
+ A compatible active workspace receives the batch instead; that launcher prints
265
+ only the identical owner URL and exits 0 without acquiring stop ownership.
266
+ `open` and foreground multi can join each other's owner. Registration retains
267
+ its atomic validation, source identities and bounded target list.
268
+
269
+ Multi uses managed port 4318, or `RIG_REVIEW_FRONT_PORT`, with explicit `--port`
270
+ precedence. Its port range is 1..65535; `--port 0` refuses with
271
+ `OPEN_OPTION_INVALID`. Existing single foreground remains on 4317 and accepts
272
+ `--port 0`; existing `compare` behavior is unchanged.
273
+
274
+ `--animation` is common to all operands and 1-based `--animation-for INDEX NAME`
275
+ overrides one operand. Each target uses its explicit selection, report animation,
276
+ or unique actual clip; ambiguity refuses by name. Static/source-only inspections
277
+ retain their existing support. Multi accepts common reference/handoff flags,
278
+ `--view-only` and `--control`. Its exact inputs work with the existing feedback
279
+ and control commands. Multi checkpoint, batch compare, direct and project/joined
280
+ options refuse with `OPEN_OPTION_INVALID`; existing single options retain their
281
+ behavior. Flags and their literal values are consumed before counting operands.
282
+ Core's `rigc review` continues forwarding to `open`; Review owns this grammar.
283
+
284
+ The embedded semantic-job hub also remains pending. Its same-process host will
285
+ own trusted `readPublished`, `partsEnumerator` and `installWriterBinding`
286
+ callbacks. General cross-process callback transport is deferred. Each job retains
287
+ independent source, reviewer, capabilities, generation CAS, cursor, displayed
288
+ acknowledgment and writer grant under job-api@2/act@2. Registration-handle detach,
289
+ host stop and semantic close remain separate lifecycle concerns. Follow the
290
+ current [standing live-job workflow](#standing-live-job-workflow) and
291
+ [public host contract](STABILITY.md#managed-owner-host) for semantic jobs.
187
292
 
188
293
  ### Launcher contract
189
294
 
@@ -192,7 +297,10 @@ stderr and exit code alone:
192
297
 
193
298
  1. On success stdout is exactly one line, the URL. `open` never writes anything
194
299
  else to stdout.
195
- 2. On success stderr carries the human lines in this fixed order: for the `check/`
300
+ 2. Managed workspace success writes per-target package/handoff and animation
301
+ diagnostics in target order, then `Review workspace started|reused; N target(s).
302
+ Retrieve feedback using the original input designation.` The direct-server
303
+ path retains the following stderr order. For the `check/`
196
304
  package of a `rig-parts build` output, `Package: rig-parts build check package <path>`
197
305
  and the handoff line (`Handoff <how>: <config path> sha256 <hash> · parts <dir>`, or
198
306
  `Handoff: <refusal>`); the animation diagnostic (when a clip is selected), the control notice (with `--control`),
@@ -205,20 +313,58 @@ stderr and exit code alone:
205
313
  - `OPEN_ANIMATION_UNKNOWN <name>`: the explicit or report-named clip (JSON-quoted) is not in the compiled model.
206
314
  - `OPEN_ANIMATION_AMBIGUOUS`: no flag or report selects one clip, or the A/B reports conflict.
207
315
  - `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`.
316
+ - `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
317
  - `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
318
  - `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
319
  4. Exit codes: 0 applied, 1 refused. (`control` keeps its own exit 2 for an
212
320
  unapplied command.)
213
321
 
214
- Package validation and worker startup refusals keep their existing messages; the
215
- named refusals above are decided before any state is written.
322
+ Input validation precedes workspace registration. Workspace startup and
323
+ registration refusals retain their named codes and exit 1. A refused batch
324
+ registration leaves existing registrations intact. Direct-worker refusals keep
325
+ their existing messages.
326
+
327
+ ### Direct server and legacy lifecycle
328
+
329
+ Use `rig-review open dirA --direct --animation idle --view-only` for a separate
330
+ single-target server. It prints the worker's own URL and retains the per-instance
331
+ lifecycle and hash-bound handoff described here. Foreground `review` and
332
+ `review compare` retain their existing separate-server behavior.
333
+
334
+ Only tool-owned instances with matching content, canonical input locations, tool
335
+ fingerprint and a private capability handshake are reused. The URL hash is
336
+ checked before serving the app; a stale link never selects another instance's
337
+ package. Input hashes are freshly computed, not trusted from mtime caches. In both
338
+ `open --direct` and foreground `review` / `review compare`, each open window holds a live
339
+ WebSocket connection (`/api/live`); once the last window closes and stays at zero connections
340
+ for the 3-second grace period, or if no window ever connects within 30 minutes
341
+ (reusing a windowless worker via `open --direct` gives it a fresh 30-minute unopened window),
342
+ the server finishes any in-flight request or Apply, flushes state, prints one line
343
+ stating why it exited, and exits `0`. A browser that unloads a background tab to
344
+ save memory looks the same as a closed tab, so the server stops; saved feedback
345
+ survives and `open --direct` brings it back. Their
346
+ private registry, requests and logs live beside feedback under
347
+ `~/.local/state/rig-c-review/open/`; nothing is written into supplied folders. `RIG_REVIEW_STATE_DIR` selects another state root
348
+ outside all input packages, judged by its canonical location (symlinks in the path
349
+ and its existing ancestors resolved). Existing foreground review commands still work.
350
+
351
+ No browser is opened, no LAN listener is added, and no misleading phone/QR URL is
352
+ printed: every current instance binds only `127.0.0.1`.
353
+
354
+ The printed feedback retrieval command uses POSIX shell quoting for literal path
355
+ arguments. It is not a PowerShell or cmd.exe command string.
216
356
 
217
357
  ### Managed front and write capability
218
358
 
219
- `open` is **managed by default**. It ensures one detached loopback front at
359
+ This heading preserves the legacy per-instance managed-front reference. Current
360
+ default `open` uses the [owner workspace](#one-command-owner-handoff).
361
+ `open --direct` serves its worker directly.
362
+
363
+ #### Legacy per-instance proxy
364
+
365
+ The earlier managed launcher ensured one detached loopback front at
220
366
  `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
367
+ printed `http://127.0.0.1:4318/instances/<key>/?input=…&handoff=…#cap=…`. Every
222
368
  inspection therefore shares one stable browser origin, so Settings, panel sizes and
223
369
  source-bound drafts survive a reopen. The front only routes: it takes the worker
224
370
  address from that key's private open record, allows a closed per-method route
@@ -235,10 +381,12 @@ If another listener holds the front port, `open` fails with
235
381
  does not fall back silently. `open --direct` keeps the per-instance port and
236
382
  prints that worker's own URL.
237
383
 
384
+ #### Direct and legacy write capability
385
+
238
386
  One origin cannot isolate scripts that run on it, so writes are bound to a
239
387
  per-instance capability rather than to the page's origin or the key in its path.
240
388
  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
389
+ The legacy managed launcher, `open --direct` and the foreground `review`/`review compare` commands
242
390
  print it in the `#cap=` fragment, which browsers never send to a server. That
243
391
  printed link goes only to the terminal of the command that started the instance.
244
392
  Output meant for a log does not carry it: the install smoke (`bun run smoke`, whose output CI publishes) prints the same
@@ -249,7 +397,8 @@ checks it before forwarding and the worker compares it again in constant time
249
397
  before its existing same-origin check. No endpoint returns it, so a page opened
250
398
  for one instance cannot submit to another. A copied view link (without the
251
399
  fragment) opens read-only and says *Read-only view: reopen with rig-review open to
252
- edit*; run `open` again for a writable link.
400
+ edit*; run `open --direct` again for a writable per-instance link. Current workspace
401
+ owner links use the separate incarnation-bound capability described above.
253
402
 
254
403
  ## Control the current inspection page
255
404
 
@@ -273,7 +422,7 @@ rig-review control /absolute/output --reference /absolute/original.mp4 --page '<
273
422
 
274
423
  Use the same reference/compare/animation inputs as the controlled `open`. Multiple
275
424
  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
425
+ existing ordinary servers do not become controllable. Registering the opted-in target
277
426
  is a one-time handoff, not a new link for each parameter change.
278
427
 
279
428
  Commands cover appearance, automatic layout, synchronized or independent pane
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "2.0.0",
3
+ "version": "2.2.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -10,6 +10,67 @@ compatibility: Requires Bun 1.3.0 or later on PATH. The canonical npm package is
10
10
  Use this to hand separated parts, a rig or a post to a person for inspection,
11
11
  or to read back their submitted review.
12
12
 
13
+ ## Open one owner workspace
14
+
15
+ For folder inspections, use **N rigs → one invocation, one owner link**.
16
+ `open` hosts designated targets in one loopback listener-owning process.
17
+ `--animation` supplies the default clip; `--animation-for <index> <name>` overrides
18
+ one 1-based target position. This opens nine rigs with `walk` for `dirB` and
19
+ `idle` for the others.
20
+
21
+ ```sh
22
+ rig-review open dirA dirB dirC dirD dirE dirF dirG dirH dirI \
23
+ --animation idle --animation-for 2 walk --view-only
24
+ ```
25
+
26
+ Invalid/out-of-range indices and duplicate overrides refuse with
27
+ `OPEN_OPTION_INVALID`. Common typed options retain their per-target validation.
28
+ Single-primary-target `--compare` requires `--reference`; batch compare is refused.
29
+ Compatible repeated calls also register into the same owner list.
30
+
31
+ ```sh
32
+ rig-review open dirA --animation idle --view-only
33
+ rig-review open dirB --animation walk --view-only
34
+ rig-review feedback dirA --animation idle --format json
35
+ ```
36
+
37
+ Both launchers exit 0 with the same root owner URL and capability within one
38
+ host incarnation, adding no listener or per-rig worker. A consumer opened N rigs
39
+ with N sequential `open` calls. Prefer one batch when the targets are known.
40
+ Give the person the private owner link and one what-to-look-at line.
41
+ For terminal-owned multi review, use `rig-review dirA dirB --animation idle
42
+ --animation-for 2 walk --view-only`. A new owner stays foreground on managed
43
+ port 4318; compatible reuse prints the same URL and exits 0. `--port` overrides
44
+ the port and accepts 1..65535. Single foreground keeps 4317 and port 0 support.
45
+ Multi checkpoint, compare, direct and project/joined flags refuse by name.
46
+ View-only entries are labelled **Inspection only**, without semantic acts or
47
+ pending approvals. Existing feedback semantics apply per target. Retain each
48
+ target's original feedback lookup arguments, inspection state, source-bound
49
+ draft and verbatim reviewer words.
50
+
51
+ The workspace admits 32 targets and lazily retains selected frames under that
52
+ same application bound. Target 33 refuses atomically with
53
+ `WORKSPACE_TARGET_LIMIT`. The limit supplies no hardware performance guarantee.
54
+ Reuse requires matching UID, installation, runtime and fingerprint. Restart
55
+ rotates host and target secrets, so run `open` again for a new owner link. Its
56
+ nonsecret `?workspace=<incarnation>` query forces a new document in an existing
57
+ tab; same-host repeated opens retain the identical URL.
58
+ Changed sources become unavailable without rebinding their feedback.
59
+
60
+ The workspace defaults to port 4318, overridden by `RIG_REVIEW_FRONT_PORT`.
61
+ An occupied port refuses `FRONT_PORT_BUSY`; choose an explicit port or use the
62
+ single-target separate-server path
63
+ `rig-review open dirA --direct --animation idle --view-only`.
64
+ Leave existing workers under their owner's control. Follow
65
+ [workspace lifecycle and restart](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#workspace-lifecycle-and-restart)
66
+ for host reuse, live unresponsive PID refusal and aggregate shutdown behavior.
67
+
68
+ Plain foreground multi-target invocation and the embedded semantic-job hub remain
69
+ pending. Core's `rigc review` passes arguments through unchanged. Follow the
70
+ current active-cycle contract below for semantic jobs and trusted callbacks.
71
+ Keep imagery, questions and approvals in the Review UI, using supported commands
72
+ and APIs. Agents never construct internal Review state or human acts.
73
+
13
74
  ## Active cycle standing live-job contract
14
75
 
15
76
  For the active Create and Parts cycle, the authoritative contract is `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)), 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` 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](https://github.com/rig-c/review/blob/main/docs/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`). Do not invent public export names, producer scene fields or unimplemented flags, and never expose capabilities in reports or logs. See [Live job contract](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#standing-live-job-workflow).
@@ -63,7 +124,8 @@ The one-shot CLI file-handoff instructions in this section and in Correction rea
63
124
  Use the installed CLI. For compiled packages, run `rig-review check <package>`
64
125
  before handoff to validate the package and read its source SHA-256. Use managed
65
126
  `rig-review open` for joined inspection and embedded saves. Give the reviewer
66
- its URL from stdout privately and keep the exact feedback command from stderr.
127
+ its URL from stdout privately and keep the original per-target feedback lookup
128
+ arguments. The direct-server path also prints a copyable feedback command on stderr.
67
129
  The stage buttons navigate within that source binding.
68
130
 
69
131
  1. **Parts + mesh.** Open the recorded Create draft's compiled check directory.
package/src/build.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { fileURLToPath } from 'node:url';
2
2
  export const appRoot=fileURLToPath(new URL('..',import.meta.url));
3
- export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'='single'):Promise<Blob> {
4
- const result=await Bun.build({entrypoints:[appRoot+(mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
3
+ export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'|'workspace'='single'):Promise<Blob> {
4
+ const result=await Bun.build({entrypoints:[appRoot+(mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
5
5
  if(!result.success)throw new Error(result.logs.map(v=>v.message).join('\n'));
6
6
  const output=result.outputs.find(v=>v.path.endsWith('.js'));if(!output)throw new Error('frontend bundle: JavaScript output missing');return output;
7
7
  }
package/src/cli.ts CHANGED
@@ -25,7 +25,7 @@ import { readCompareSession } from './compare-session.ts';
25
25
  import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
26
26
  import type { StripInterval, StripRequest } from './strip.ts';
27
27
  const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]]';
28
- const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
28
+ const usage='Usage: rig-review open <dir> [<dir> ...] [--animation-for <index> <name>] [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one owner workspace at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) hosts targets in one process; --animation applies to all targets, --animation-for overrides one 1-based target, and --direct keeps a separate single-target worker.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n rig-review <dir> <dir> ... [--animation <name>] [--animation-for <index> <name>] [--port 4318] [--reference <video>] [--view-only] [--control] '+handoffUsage+'\n Foreground multi owns a new workspace in this CLI process; a compatible existing owner is joined and the launcher exits. Multi --port accepts 1..65535; single foreground keeps 4317 and --port 0.\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
29
29
  async function stripCommand(args:string[],options:{stateDir?:string}){
30
30
  const compare=args[0]==='compare';if(compare)args.shift();const a=args.shift(),b=compare?args.shift():undefined;if(!a||compare&&!b)throw new Error('strip: expected package input(s)');
31
31
  let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -70,6 +70,84 @@ export function parseOpenInputs(args:string[]):OpenInputs {
70
70
  if(result.compare!==undefined&&handoffFlags(result))throw new Error('OPEN_OPTION_INVALID --config: compare takes no producer handoff; open one package with --config');
71
71
  return result;
72
72
  }
73
+
74
+ /** Common open options apply to every operand; indexed animation values override the common default. */
75
+ export function parseOpenTargets(args: readonly string[]): OpenInputs[] {
76
+ const inputs: string[] = [];
77
+ const common: string[] = [];
78
+ const animations = new Map<number, string>();
79
+ const booleanFlags = ['--control', '--direct', '--view-only'];
80
+ const valueFlags = ['--reference', '--compare', '--animation', ...projectFlags, ...HANDOFF_FLAGS.map(flag => '--' + flag)];
81
+ for (let index = 0; index < args.length; index++) {
82
+ const flag = args[index]!;
83
+ if (flag === '--animation-for') {
84
+ const target = args[++index], animation = args[++index];
85
+ if (target === undefined || !/^[1-9]\d*$/.test(target) || !Number.isSafeInteger(Number(target)) || animation === undefined || animation === '') {
86
+ throw new Error('OPEN_OPTION_INVALID --animation-for: expected a positive target index and animation name');
87
+ }
88
+ const targetIndex = Number(target);
89
+ if (animations.has(targetIndex)) throw new Error(`OPEN_OPTION_INVALID --animation-for: duplicate target index ${target}`);
90
+ animations.set(targetIndex, animation);
91
+ } else if (booleanFlags.includes(flag)) {
92
+ common.push(flag);
93
+ } else if (valueFlags.includes(flag)) {
94
+ const value = args[++index];
95
+ if (value === undefined || value === '') throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);
96
+ common.push(flag, value);
97
+ } else if (flag.startsWith('--')) {
98
+ throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);
99
+ } else {
100
+ inputs.push(flag);
101
+ }
102
+ }
103
+ if (inputs.length === 0) throw new Error(usage);
104
+ for (const target of animations.keys()) {
105
+ if (target > inputs.length) throw new Error(`OPEN_OPTION_INVALID --animation-for: target index ${target} exceeds ${inputs.length} input(s)`);
106
+ }
107
+ const targets = inputs.map(input => parseOpenInputs([input, ...common]));
108
+ if (targets.length > 1 && targets.some(target => target.compare !== undefined)) {
109
+ throw new Error('OPEN_OPTION_INVALID --compare: multi-target open requires exactly one primary input for comparison');
110
+ }
111
+ if (targets.length > 1 && targets.some(target => target.direct)) {
112
+ throw new Error('OPEN_OPTION_INVALID --direct: multi-target open requires the managed owner workspace');
113
+ }
114
+ for (const [index, animation] of animations) targets[index - 1]!.animation = animation;
115
+ return targets;
116
+ }
117
+ /** Multi detection consumes known option values before counting folder operands. */
118
+ export function parseForegroundTargets(args: readonly string[]): {targets: OpenInputs[]; port?: number; help: boolean} | null {
119
+ const values = ['--port', '--checkpoint', '--reference', '--compare', '--animation', ...projectFlags,
120
+ ...HANDOFF_FLAGS.map(flag => '--' + flag)];
121
+ const booleans = ['--view-only', '--control', '--direct'];
122
+ const operands: string[] = [], forwarded: string[] = [];
123
+ const unsupported = new Set(['--checkpoint', '--compare', '--direct', ...projectFlags]);
124
+ const refused: string[] = [];
125
+ let port: number | undefined, help = false, duplicatePort = false;
126
+ for (let index = 0; index < args.length; index++) {
127
+ const flag = args[index]!;
128
+ if (flag === '--help' || flag === '-h') {help = true; continue;}
129
+ if (unsupported.has(flag)) refused.push(flag);
130
+ if (flag === '--animation-for') {
131
+ forwarded.push(flag, ...args.slice(index + 1, index + 3)); index += 2;
132
+ } else if (flag === '--port') {
133
+ duplicatePort = port !== undefined;
134
+ port = Number(args[++index]);
135
+ } else if (values.includes(flag)) {
136
+ forwarded.push(flag); if (args[index + 1] !== undefined) forwarded.push(args[++index]!);
137
+ } else if (booleans.includes(flag)) forwarded.push(flag);
138
+ else if (!flag.startsWith('-')) {operands.push(flag); forwarded.push(flag);}
139
+ // Preserve the legacy validator's unknown-option and help precedence.
140
+ else return null;
141
+ }
142
+ if (operands.length < 2) return null;
143
+ if (help) return {targets: [], port, help};
144
+ if (refused.length) throw new Error('OPEN_OPTION_INVALID ' + refused[0] + ': unsupported for foreground multi-target review');
145
+ if (duplicatePort || port !== undefined && (!Number.isSafeInteger(port) || port < 1 || port > 65535)) {
146
+ throw new Error('OPEN_OPTION_INVALID --port: foreground multi-target review expects integer 1..65535');
147
+ }
148
+ return {targets: parseOpenTargets(forwarded), port, help};
149
+ }
150
+
73
151
  async function controlCommand(args:string[],stateDir?:string){
74
152
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(usage);return;}
75
153
  const inputs:OpenInputs={input},options:Parameters<typeof controlReview>[1]={stateDir},seen=new Set<string>(),projectOptions:string[]=[];
@@ -117,6 +195,8 @@ function commandHelpRequested(args:readonly string[],command:'open'|'review'|'ch
117
195
  const handoff=HANDOFF_FLAGS.map(f=>'--'+f),flags=command==='open'?['--reference','--compare','--animation',...projectFlags,...handoff]:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation',...handoff,...(command==='feedback'?projectFlags:[])];
118
196
  for(let i=compare?3:1;i<args.length;){
119
197
  const flag=args[i];if(flag==='--help'||flag==='-h')return true;
198
+ if(command==='open'&&flag==='--animation-for'){i+=3;continue;}
199
+ if(command==='open'&&!flag?.startsWith('--')){i++;continue;}
120
200
  if((command==='open'&&(flag==='--control'||flag==='--direct'||flag==='--view-only'))||(command==='review'&&flag==='--view-only')){i++;continue;}if(!flags.includes(flag!))return false;i+=2;
121
201
  }
122
202
  return false;
@@ -152,12 +232,37 @@ export async function main(args:string[],options:{stateDir?:string}={}){
152
232
  options={stateDir:options.stateDir??defaultStateDir()};if(args[0]==='--')args.shift();
153
233
  if(args[0]==='--version'||args[0]==='-v'){console.log((JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')) as {version:string}).version);return;}
154
234
  if(args[0]==='control')return controlCommand(args.slice(1),options.stateDir);
155
- if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
235
+ if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const targets=parseOpenTargets(openArgs);
236
+ if(!targets[0]?.direct){
237
+ const {openWorkspace}=await import('./open-workspace-launch.ts');
238
+ const result=await openWorkspace(targets,options);
239
+ console.log(result.url);
240
+ for(const target of result.prepared){if(target.build)console.error(buildOpenDiagnostic(target.build));if(target.package.selection)console.error(animationDiagnostic(target.package.selection));}
241
+ console.error(`Review workspace ${result.reused?'reused':'started'}; ${targets.length} target(s). Retrieve feedback using the original input designation.`);
242
+ return;
243
+ }
244
+ const inputs=targets[0]!;const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
156
245
  console.log(result.url);if(result.build)console.error(buildOpenDiagnostic(result.build));if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[]),...handoffWords(result.inputs),...projectWords(result.inputs)].map(shellWord).join(' ')}`);return;}
157
246
  if(args[0]==='parts')return partsCommand(args.slice(1));
158
247
  if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
159
248
  if(args[0]==='strip'){args.shift();if(args.includes('--help')){console.log(usage+'\nStrip: strip <package> --reference <declared-video-id> --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out path]\n strip compare <a> <b> --reference <video> --animation <name> --basis a|b (--frames FIRST:LAST | --all-feedback) [--json] [--out path]');return;}return stripCommand(args,options);}let command:'review'|'check'|'feedback'='review';if(args[0]==='check'||args[0]==='feedback'){command=args.shift() as 'check'|'feedback';}
160
249
  if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
250
+ const foreground = command === 'review' && args[0] !== 'compare' ? parseForegroundTargets(args) : null;
251
+ if (foreground) {
252
+ if (foreground.help) {console.log(usage); return;}
253
+ const {openWorkspace} = await import('./open-workspace-launch.ts');
254
+ const result = await openWorkspace(foreground.targets, {...options, frontPort: foreground.port, foreground: true});
255
+ if (!result.interrupted) {
256
+ for (const target of result.prepared) {
257
+ if (target.build) console.error(buildOpenDiagnostic(target.build));
258
+ if (target.package.selection) console.error(animationDiagnostic(target.package.selection));
259
+ }
260
+ if (result.waitForExit) console.log(`Review ready: ${result.url}\nTargets: ${foreground.targets.length}\nPress Ctrl+C to stop.`);
261
+ else console.log(result.url);
262
+ }
263
+ await result.waitForExit?.();
264
+ return;
265
+ }
161
266
  let format:'json'|'issue'='json',correctionId:string|undefined;if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;correctionId=parsed.correctionId;}
162
267
  // Feedback formatting assigns --format/value ownership before the help pass.
163
268
  if(commandHelpRequested(args,command)){console.log(usage);return;}