@rig-c/review 0.10.1 → 0.10.2

package/src/rebuild.ts

@@ -34,6 +34,7 @@ import { availableParallelism } from 'node:os';
 import { candidateRow, DENSITY_STRIP_SCHEMA, DensityStripError, stripLabels, stripPatches, stripShape, type DensityField, type StripRow } from './density-strip.ts';
 import { samplesClock } from './frame-clock.ts';
 import { cleanArgs, mapText, motionSummary, parseRetargetRequest, retargetArgs, retargetLines, retargetRecord, retargetRecordText, RetargetError, type MotionSummary, type RetargetLine, type RetargetRecord } from './retarget.ts';
+import { assertStateOutside as assertStateDirOutside } from './state-dir.ts';
 
 export const REBUILD_SCHEMA = 'rig-review-rebuild/1';
 const MAX_REGIONS = CHEST_REGIONS_MAX, MAX_POINTS = 256, MAX_LINES = 4000, GRID = 256;
@@ -488,16 +489,50 @@ async function opCarried(op: CarryingOp, spec: string, world: ApplyWorld | null,
   return { summary: carriedCheckSummary(carried, op) };
 }
 
+/** #185: the most files, and the deepest nesting, a config-named run directory may hold to be hashed into the build inputs. */
+export const MAX_NAMED_DIR_FILES = 4096, MAX_NAMED_DIR_DEPTH = 8;
+/**
+ * #185: a config-named run directory (an alternate's `full` / `head`) as one digest: every regular file under it, at most
+ * `MAX_NAMED_DIR_DEPTH` levels down and `MAX_NAMED_DIR_FILES` in all, each resolved and held inside the package root and
+ * hashed, in path order. Over the bound refuses (`BUILD_INPUT_TOO_LARGE`) rather than hash part of it.
+ */
+async function namedDirDigest(root: string, dir: string, field: string): Promise<string> {
+  const rows: [string, string][] = [];
+  const walk = async (at: string, depth: number): Promise<void> => {
+    const entries = (await readdir(at, { withFileTypes: true })).map(e => e.name).sort();
+    for (const name of entries) {
+      const lexical = join(at, name);
+      const real = await realpath(lexical);
+      const rel = relative(root, real);
+      if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) throw new RebuildError('BUILD_INPUT_OUTSIDE_ROOT', `config ${field} holds ${relative(dir, lexical).split(sep).join('/')}, which resolves outside the package root`);
+      const st = await lstat(real);
+      if (st.isDirectory()) {
+        if (depth >= MAX_NAMED_DIR_DEPTH) throw new RebuildError('BUILD_INPUT_TOO_LARGE', `config ${field} nests deeper than ${MAX_NAMED_DIR_DEPTH} levels`);
+        await walk(lexical, depth + 1);
+      } else if (st.isFile()) {
+        if (rows.length >= MAX_NAMED_DIR_FILES) throw new RebuildError('BUILD_INPUT_TOO_LARGE', `config ${field} holds more than ${MAX_NAMED_DIR_FILES} files`);
+        rows.push([relative(dir, lexical).split(sep).join('/'), sha256(await readFile(real))]);
+      }
+    }
+  };
+  await walk(dir, 1);
+  return sha256(JSON.stringify(rows));
+}
+
 /** #115: what a build-routed patch runs with — the handoff's painting and runs, absolute; never from the client. */
 export interface BuildPlan { source: string; full: string; head: string | null; inputsHash: string; inputs: AssembledView['inputs'] }
 /**
  * The build's inputs for a patch (`null` refusal line when the handoff declares no painting and full run): the painting
  * and the runs, and every config-relative file the patched config names for assemble, each resolved against the handoff
- * config's directory and held inside the handoff root (`BUILD_INPUT_OUTSIDE_ROOT`, `BUILD_INPUT_MISSING`) and hashed.
+ * config's directory and held inside the handoff root (`BUILD_INPUT_OUTSIDE_ROOT`, `BUILD_INPUT_MISSING`) and hashed — a named
+ * directory outside the declared runs by its contents (`namedDirDigest`, #185); a declared run is in the record already.
  */
 export async function buildPlan(handoff: Handoff, patched: JsonValue, show: (abs: string) => string): Promise<BuildPlan> {
   if (!handoff.source || !handoff.full) throw new RebuildError('MODELING_INPUT_UNAVAILABLE', BUILD_SOURCE_UNAVAILABLE.slice('MODELING_INPUT_UNAVAILABLE: '.length));
   const root = await realpath(handoff.root), configDir = dirname(handoff.config), named: AssembledView['inputs']['named'] = [];
+  // The declared runs' files are already in the handoff record (and so in the hash below); any other named directory is hashed here.
+  const declaredRuns = new Set<string>();
+  for (const run of [handoff.full, handoff.head]) if (run) declaredRuns.add(await realpath(run).catch(() => resolve(run)));
   for (const f of buildNamedFiles(patched)) {
     if (isAbsolute(f.value)) throw new RebuildError('BUILD_INPUT_OUTSIDE_ROOT', `config ${f.field} is an absolute path; the handoff config names its files relative to its own directory`);
     const lexical = resolve(configDir, f.value);
@@ -505,7 +540,7 @@ export async function buildPlan(handoff: Handoff, patched: JsonValue, show: (abs
     try { real = await realpath(lexical); } catch { throw new RebuildError('BUILD_INPUT_MISSING', `config ${f.field} names ${show(lexical)}, which does not exist`); }
     const rel = relative(root, real);
     if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) throw new RebuildError('BUILD_INPUT_OUTSIDE_ROOT', `config ${f.field} resolves outside the package root`);
-    named.push({ field: f.field, path: show(real), sha256: f.kind === 'file' ? sha256(await readFile(real)) : null });
+    named.push({ field: f.field, path: show(real), sha256: f.kind === 'file' ? sha256(await readFile(real)) : declaredRuns.has(real) ? null : await namedDirDigest(root, real, f.field) });
   }
   const inputs = { source: handoff.record.source?.path ?? show(handoff.source), full: handoff.record.full ?? show(handoff.full), head: handoff.head ? handoff.record.head ?? show(handoff.head) : null, named };
   // The painting, the runs' hashed files (the handoff record's) and the named files: an identical build reuses its scratch build.
@@ -543,7 +578,18 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
   interface StripCandidate { value: number; id: string; entry: JsonValue; dir: string; job: PatchJob; applied: boolean }
   let strip: { id: string; status: 'running' | 'done'; part: string; field: DensityField; concurrency: number; configHash: string; producer: { package: string; version: string }; compiler: { package: string; version: string }; started: number; wallMs: number | null; candidates: StripCandidate[] } | null = null;
   /** One producer workload at a time per review: an Apply (or undo's re-run) or a strip; the line refusing the other. */
-  const busy = (): string | null => (running ? `REBUILD_BUSY: rebuild ${running} is still running` : strip?.status === 'running' ? `REBUILD_BUSY: density strip ${strip.id} is still running` : null);
+  /**
+   * #183: a workload that passed `busy()` and has not yet set `running` or `strip` (its awaits — adopt, unkeep, reuse, the
+   * strip's scratch removal — come between). Taken synchronously right after `busy()`, so no second workload passes in that
+   * window; released when the workload is set or refused. Holds the line `busy()` refuses others with.
+   */
+  let reserved: string | null = null;
+  const busy = (): string | null => (running ? `REBUILD_BUSY: rebuild ${running} is still running` : reserved ?? (strip?.status === 'running' ? `REBUILD_BUSY: density strip ${strip.id} is still running` : null));
+  /** #183: run `body` holding the reservation; `body` sets `running` / `strip` synchronously before it returns. */
+  async function reserve<T>(line: string, body: () => Promise<T>): Promise<T> {
+    reserved = line;
+    try { return await body(); } finally { if (reserved === line) reserved = null; }
+  }
   /** #166: the session's applied records, in order; the last is on the stage. The request bodies by job id. */
   const stack: AppliedEntry[] = [];
   const bodies = new Map<string, unknown>();
@@ -553,10 +599,7 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
 
   /** The state directory may not sit inside the package or the handoff's root (the parent of an opened out/). */
   function assertStateOutside(): void {
-    for (const root of [p.root, ...(p.handoff ? [p.handoff.root] : [])]) {
-      const inside = relative(root, options.stateDir);
-      if (inside === '' || !inside.startsWith('..') && !isAbsolute(inside)) throw new RebuildError('REBUILD_STATE_INSIDE_PACKAGE', 'the review state directory is inside the inspected package; set RIG_REVIEW_STATE_DIR outside it');
-    }
+    assertStateDirOutside(options.stateDir, p, message => new RebuildError('REBUILD_STATE_INSIDE_PACKAGE', message));
   }
   /** Once per session: the first time the handoff and the producer both resolve, the baseline starts (or is reused). */
   let baseline: BaselineResult | null = null, baselineRun: Promise<BaselineResult> | null = null;
@@ -1065,19 +1108,21 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
     const current = jobs.get(id);
     if (current?.status === 'running') return { status: 202, body: snapshot(current) };
     if (busy()) return { status: 200, body: { status: 'refused', error: busy(), producerLine: null } };
-    guardRestore(id);
-    const dir = rebuildDir(options.stateDir, p.sourceHash, id);
-    await adopt(id);
-    await unkeep(id);
-    const reused = await reuse<PatchJob>(dir, id);
-    if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, body); await landed(reused); return { status: 200, body: snapshot(reused) }; }
-    const job: PatchJob = { schema: REBUILD_SCHEMA, kind: 'patch', id, status: 'running', reused: false, op, request: { patch, patchSha256: patchSha256(patch), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null, check: null }, check: null, diff: null, files: null, remesh: null, build: null,
-      ...(plan ? { assembled: { inputs: plan.inputs, refusals: [], checkFails: [], lines: [], seam: [], seamPairs: [], recomposite: { line: null, before: null, after: null, errorMap: null }, parts: null } } : {}),
-      ...(world ? { environment: world.record } : {}),
-      ...(clothPlan ? { cloth: { route: building ? 'build' as const : 'rig' as const, inputs: { source: p.handoff!.record.source?.path ?? '', keypoints: { ...p.handoff!.record.keypoints! } }, refusals: [], line: null, written: null, links: [], wallMs: { propose: null, build: null } } } : {}) };
-    jobs.set(id, job); running = id; bodies.set(id, body);
-    void executePatch(job, dir, inputs, resolved, patched, part, plan, world, clothPlan).finally(() => { if (running === id) running = null; });
-    return { status: 202, body: snapshot(job) };
+    return reserve(`REBUILD_BUSY: rebuild ${id} is still running`, async () => {
+      guardRestore(id);
+      const dir = rebuildDir(options.stateDir, p.sourceHash, id);
+      await adopt(id);
+      await unkeep(id);
+      const reused = await reuse<PatchJob>(dir, id);
+      if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, body); await landed(reused); return { status: 200, body: snapshot(reused) }; }
+      const job: PatchJob = { schema: REBUILD_SCHEMA, kind: 'patch', id, status: 'running', reused: false, op, request: { patch, patchSha256: patchSha256(patch), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null, check: null }, check: null, diff: null, files: null, remesh: null, build: null,
+        ...(plan ? { assembled: { inputs: plan.inputs, refusals: [], checkFails: [], lines: [], seam: [], seamPairs: [], recomposite: { line: null, before: null, after: null, errorMap: null }, parts: null } } : {}),
+        ...(world ? { environment: world.record } : {}),
+        ...(clothPlan ? { cloth: { route: building ? 'build' as const : 'rig' as const, inputs: { source: p.handoff!.record.source?.path ?? '', keypoints: { ...p.handoff!.record.keypoints! } }, refusals: [], line: null, written: null, links: [], wallMs: { propose: null, build: null } } } : {}) };
+      jobs.set(id, job); running = id; bodies.set(id, body);
+      void executePatch(job, dir, inputs, resolved, patched, part, plan, world, clothPlan).finally(() => { if (running === id) running = null; });
+      return { status: 202, body: snapshot(job) };
+    });
   }
 
   /**
@@ -1115,29 +1160,32 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
     if (strip?.id === id) return { status: strip.status === 'running' ? 202 : 200, body: stripView() };
     const refusal = busy();
     if (refusal) return { status: 200, body: { status: 'refused', error: refusal, producerLine: null } };
-    // Bounded disk: the strip on screen is the only one this package keeps; its predecessor's folder goes first.
-    const root = stripRoot(options.stateDir, p.sourceHash);
-    await rm(root, { recursive: true, force: true });
-    const concurrency = Math.max(1, Math.floor(options.stripConcurrency ?? defaultStripConcurrency()));
-    const candidates: StripCandidate[] = planned.map(({ patch }, i) => {
-      const cid = patchId({ sourceHash: p.sourceHash, configHash: inputs.configHash, patch, producer, compiler, op: 'remesh' });
-      const job: PatchJob = { schema: REBUILD_SCHEMA, kind: 'patch', id: cid, status: 'running', reused: false, op: 'remesh', request: { patch, patchSha256: patchSha256(patch), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null, check: null }, check: null, diff: null, files: null, remesh: null, build: null };
-      return { value: shape.values[i]!, id: cid, entry: shape.entries[i]!, dir: join(root, id, cid), job, applied: false };
-    });
-    const current = { id, status: 'running' as const, part: shape.part, field: shape.field, concurrency, configHash: inputs.configHash, producer: tool(resolved.producer), compiler: tool(resolved.compiler), started: performance.now(), wallMs: null, candidates };
-    strip = current;
-    // A bounded pool: each worker takes the next candidate in order; the strip is done when every candidate settled.
-    let next = 0;
-    const worker = async () => {
-      for (let i = next++; i < candidates.length; i = next++) {
-        const c = candidates[i]!;
-        await executePatch(c.job, c.dir, inputs, resolved, planned[i]!.patched, shape.part, null, null, null, true).catch(() => {});
-      }
-    };
-    void Promise.all(Array.from({ length: Math.min(concurrency, candidates.length) }, worker)).finally(() => {
-      if (strip === current) { (current as { status: 'running' | 'done' }).status = 'done'; (current as { wallMs: number | null }).wallMs = Math.round(performance.now() - current.started); }
+    // #183: own the workload before the first await below; `strip = current` takes over before the reservation ends.
+    return reserve(`REBUILD_BUSY: density strip ${id} is still running`, async () => {
+      // Bounded disk: the strip on screen is the only one this package keeps; its predecessor's folder goes first.
+      const root = stripRoot(options.stateDir, p.sourceHash);
+      await rm(root, { recursive: true, force: true });
+      const concurrency = Math.max(1, Math.floor(options.stripConcurrency ?? defaultStripConcurrency()));
+      const candidates: StripCandidate[] = planned.map(({ patch }, i) => {
+        const cid = patchId({ sourceHash: p.sourceHash, configHash: inputs.configHash, patch, producer, compiler, op: 'remesh' });
+        const job: PatchJob = { schema: REBUILD_SCHEMA, kind: 'patch', id: cid, status: 'running', reused: false, op: 'remesh', request: { patch, patchSha256: patchSha256(patch), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null, check: null }, check: null, diff: null, files: null, remesh: null, build: null };
+        return { value: shape.values[i]!, id: cid, entry: shape.entries[i]!, dir: join(root, id, cid), job, applied: false };
+      });
+      const current = { id, status: 'running' as const, part: shape.part, field: shape.field, concurrency, configHash: inputs.configHash, producer: tool(resolved.producer), compiler: tool(resolved.compiler), started: performance.now(), wallMs: null, candidates };
+      strip = current;
+      // A bounded pool: each worker takes the next candidate in order; the strip is done when every candidate settled.
+      let next = 0;
+      const worker = async () => {
+        for (let i = next++; i < candidates.length; i = next++) {
+          const c = candidates[i]!;
+          await executePatch(c.job, c.dir, inputs, resolved, planned[i]!.patched, shape.part, null, null, null, true).catch(() => {});
+        }
+      };
+      void Promise.all(Array.from({ length: Math.min(concurrency, candidates.length) }, worker)).finally(() => {
+        if (strip === current) { (current as { status: 'running' | 'done' }).status = 'done'; (current as { wallMs: number | null }).wallMs = Math.round(performance.now() - current.started); }
+      });
+      return { status: 202, body: stripView() };
     });
-    return { status: 202, body: stripView() };
   }
   function stripView(): DensityStripView | null {
     if (!strip) return null;
@@ -1236,16 +1284,18 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
     const current = jobs.get(id);
     if (current?.status === 'running') return { status: 202, body: snapshot(current) };
     if (busy()) return { status: 200, body: { status: 'refused', error: busy(), producerLine: null } };
-    guardRestore(id);
-    const dir = rebuildDir(options.stateDir, p.sourceHash, id);
-    await adopt(id);
-    await unkeep(id);
-    const reused = await reuse<DeltaJob>(dir, id);
-    if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, input); await landed(reused); return { status: 200, body: snapshot(reused) }; }
-    const job: DeltaJob = { schema: REBUILD_SCHEMA, kind: 'delta', id, status: 'running', reused: false, op: 'remesh', request: { part: request.part, delta: request.delta, deltaSha256: sha256(text), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null }, files: null, remesh: null, build: null };
-    jobs.set(id, job); running = id; bodies.set(id, input);
-    void executeDelta(job, dir, inputs, resolved, text).finally(() => { if (running === id) running = null; });
-    return { status: 202, body: snapshot(job) };
+    return reserve(`REBUILD_BUSY: rebuild ${id} is still running`, async () => {
+      guardRestore(id);
+      const dir = rebuildDir(options.stateDir, p.sourceHash, id);
+      await adopt(id);
+      await unkeep(id);
+      const reused = await reuse<DeltaJob>(dir, id);
+      if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, input); await landed(reused); return { status: 200, body: snapshot(reused) }; }
+      const job: DeltaJob = { schema: REBUILD_SCHEMA, kind: 'delta', id, status: 'running', reused: false, op: 'remesh', request: { part: request.part, delta: request.delta, deltaSha256: sha256(text), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { op: null, compile: null }, files: null, remesh: null, build: null };
+      jobs.set(id, job); running = id; bodies.set(id, input);
+      void executeDelta(job, dir, inputs, resolved, text).finally(() => { if (running === id) running = null; });
+      return { status: 202, body: snapshot(job) };
+    });
   }
 
   /** The package's declared `rig-pose-sequence/1` references (validated at load), with whether clean's record is on them. */
@@ -1351,16 +1401,18 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
     const current = jobs.get(id);
     if (current?.status === 'running') return { status: 202, body: snapshot(current) };
     if (busy()) return { status: 200, body: { status: 'refused', error: busy(), producerLine: null } };
-    guardRestore(id);
-    const dir = rebuildDir(options.stateDir, p.sourceHash, id);
-    await adopt(id);
-    await unkeep(id);
-    const reused = await reuse<RetargetJob>(dir, id);
-    if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, body); await landed(reused); return { status: 200, body: snapshot(reused) }; }
-    const job: RetargetJob = { schema: REBUILD_SCHEMA, kind: 'retarget', id, status: 'running', reused: false, op: 'retarget', request: { record, recordSha256: sha256(retargetRecordText(record)), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, refusals: [], exitCode: null, wallMs: { clean: null, retarget: null, compile: null }, files: null, motion: null, readings: [], frameTimes: null, build: null };
-    jobs.set(id, job); running = id; bodies.set(id, body);
-    void executeRetarget(job, dir, inputs, resolved, sequence).finally(() => { if (running === id) running = null; });
-    return { status: 202, body: snapshot(job) };
+    return reserve(`REBUILD_BUSY: rebuild ${id} is still running`, async () => {
+      guardRestore(id);
+      const dir = rebuildDir(options.stateDir, p.sourceHash, id);
+      await adopt(id);
+      await unkeep(id);
+      const reused = await reuse<RetargetJob>(dir, id);
+      if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, body); await landed(reused); return { status: 200, body: snapshot(reused) }; }
+      const job: RetargetJob = { schema: REBUILD_SCHEMA, kind: 'retarget', id, status: 'running', reused: false, op: 'retarget', request: { record, recordSha256: sha256(retargetRecordText(record)), configHash: inputs.configHash }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, refusals: [], exitCode: null, wallMs: { clean: null, retarget: null, compile: null }, files: null, motion: null, readings: [], frameTimes: null, build: null };
+      jobs.set(id, job); running = id; bodies.set(id, body);
+      void executeRetarget(job, dir, inputs, resolved, sequence).finally(() => { if (running === id) running = null; });
+      return { status: 202, body: snapshot(job) };
+    });
   }
 
   /** `POST /api/rebuild`: refusals are returned before anything is written or run. */
@@ -1389,16 +1441,18 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
     const current = jobs.get(id);
     if (current?.status === 'running') return { status: 202, body: snapshot(current) };
     if (busy()) return { status: 200, body: { status: 'refused', error: busy(), producerLine: null } };
-    guardRestore(id);
-    const dir = rebuildDir(options.stateDir, p.sourceHash, id);
-    await adopt(id);
-    await unkeep(id);
-    const reused = await reuse(dir, id);
-    if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, input); await landed(reused); return { status: 200, body: snapshot(reused) }; }
-    const job: RebuildJob = { schema: REBUILD_SCHEMA, id, status: 'running', reused: false, request: { ...request, entrySha256: sha256(entry) }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { remesh: null, compile: null }, build: null };
-    jobs.set(id, job); running = id; bodies.set(id, input);
-    void execute(job, dir, inputs, resolved, entry).finally(() => { if (running === id) running = null; });
-    return { status: 202, body: snapshot(job) };
+    return reserve(`REBUILD_BUSY: rebuild ${id} is still running`, async () => {
+      guardRestore(id);
+      const dir = rebuildDir(options.stateDir, p.sourceHash, id);
+      await adopt(id);
+      await unkeep(id);
+      const reused = await reuse(dir, id);
+      if (reused) { jobs.set(id, reused); latestId = id; bodies.set(id, input); await landed(reused); return { status: 200, body: snapshot(reused) }; }
+      const job: RebuildJob = { schema: REBUILD_SCHEMA, id, status: 'running', reused: false, request: { ...request, entrySha256: sha256(entry) }, producer: tool(resolved.producer), compiler: tool(resolved.compiler), lines: [], producerLine: null, exitCode: null, wallMs: { remesh: null, compile: null }, build: null };
+      jobs.set(id, job); running = id; bodies.set(id, input);
+      void execute(job, dir, inputs, resolved, entry).finally(() => { if (running === id) running = null; });
+      return { status: 202, body: snapshot(job) };
+    });
   }
 
   function read(id: string): RebuildJob | PatchJob | DeltaJob | RetargetJob {

package/src/requirements-run.ts

@@ -9,12 +9,13 @@
  * The client sends typed requirements only — never a path or a flag. Nothing is written into the package.
  */
 import { createHash } from 'node:crypto';
-import { isAbsolute, join, relative } from 'node:path';
+import { join } from 'node:path';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import type { ReviewPackage } from './manifest.ts';
 import { resolveProducer, runTool } from './producer.ts';
 import { producerInputs, RebuildError } from './rebuild.ts';
 import { parseRequirementsRequest, readRequirements, requirementsCheckArgs, requirementsDocument, requirementsFileText, RequirementsError, REQUIREMENTS_RUN_SCHEMA, type RequirementRow, type RequirementsBuild } from './requirements.ts';
+import { assertStateOutside as assertStateDirOutside } from './state-dir.ts';
 
 const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
 const MAX_LINES = 4000;
@@ -89,10 +90,7 @@ export function createRequirementsCheck(p: ReviewPackage, options: RequirementsO
   let running: string | null = null;
   const snapshot = (job: RequirementsJob): RequirementsJob => JSON.parse(JSON.stringify(job)) as RequirementsJob;
   function assertStateOutside(): void {
-    for (const root of [p.root, ...(p.handoff ? [p.handoff.root] : [])]) {
-      const inside = relative(root, options.stateDir);
-      if (inside === '' || !inside.startsWith('..') && !isAbsolute(inside)) throw new RequirementsError('REQUIREMENTS_STATE_INSIDE_PACKAGE', 'the review state directory is inside the inspected package; set RIG_REVIEW_STATE_DIR outside it');
-    }
+    assertStateDirOutside(options.stateDir, p, message => new RequirementsError('REQUIREMENTS_STATE_INSIDE_PACKAGE', message));
   }
   const asRequirements = (e: unknown): never => { if (e instanceof RebuildError) throw new RequirementsError(e.code, e.message.slice(e.code.length + 2)); throw e; };
 

package/src/requirements.ts

@@ -134,8 +134,12 @@ export function rowOf(name: string, line: Record<string, unknown>, printed: stri
     // The producer prints the bar as `range_degrees: [lo, hi]`.
     const bar = Array.isArray(line.range_degrees) ? line.range_degrees : [line.lo_degrees, line.hi_degrees];
     const lo = num(bar[0]), hi = num(bar[1]);
-    // The end that breaks its bar, else the end with less room to its bar.
-    const lowSide = least !== null && lo !== null && (least < lo || (greatest === null || hi === null || least - lo < hi - greatest));
+    // The end that breaks its bar by more (either may, or both), else the end with less room to its bar.
+    const lowBreak = least !== null && lo !== null && least < lo ? lo - least : 0;
+    const highBreak = greatest !== null && hi !== null && greatest > hi ? greatest - hi : 0;
+    const lowSide = least !== null && lo !== null && (lowBreak > 0 || highBreak > 0
+      ? lowBreak >= highBreak
+      : greatest === null || hi === null || least - lo < hi - greatest);
     worst = worstFrame(lowSide ? line.least_at : line.greatest_at) ?? worstFrame(line.least_at);
   } else if (kind === 'follow') { measured = num(line.fraction_measured); worst = worstFrame(line.largest_residual_at) ?? worstFrame(line.largest_drive_at); }
   const reason = typeof line.reason === 'string' ? line.reason : null;

package/src/state-dir.ts

@@ -0,0 +1,48 @@
+/**
+ * #187: where review state may live. The state directory (`RIG_REVIEW_STATE_DIR` or the default) is judged by its
+ * canonical location — the realpath of its longest existing prefix plus the not-yet-created remainder — so a symlink
+ * (the directory itself or any ancestor) that lands inside a supplied folder is refused, not followed. It may not sit
+ * inside the rig-parts build root the check package belongs to (opening `out` redirects the package to `out/check`;
+ * the build is still the supplied folder), the package root, or the producer handoff's root.
+ */
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+export type StateRootKind = 'build root' | 'package' | 'handoff root';
+export interface StateRoot { kind: StateRootKind; path: string }
+/** The fields of a loaded package that name supplied folders. */
+export interface StateRootsSource { root: string; buildRoot?: string; handoff?: { root: string } | null }
+
+const missing = (e: unknown) => ['ENOENT', 'ENOTDIR'].includes((e as NodeJS.ErrnoException).code ?? '');
+
+/** The canonical location of `path`: realpath of the longest existing prefix joined with the remainder. */
+export function canonicalStatePath(path: string): string {
+  const absolute = resolve(path), rest: string[] = [];
+  for (let current = absolute; ; current = dirname(current)) {
+    try { const real = realpathSync(current); return rest.length ? join(real, ...rest.reverse()) : real; }
+    catch (e) { if (!missing(e) || dirname(current) === current) throw e; rest.push(basename(current)); }
+  }
+}
+
+/** The supplied folders of one package, innermost first (a refusal names the first that holds the state). */
+export function stateRoots(p: StateRootsSource): StateRoot[] {
+  return [{ kind: 'package', path: p.root }, ...(p.buildRoot ? [{ kind: 'build root' as const, path: p.buildRoot }] : []), ...(p.handoff ? [{ kind: 'handoff root' as const, path: p.handoff.root }] : [])];
+}
+
+const within = (root: string, path: string) => { const rel = relative(root, path); return rel === '' || rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel); };
+
+/** The first supplied folder the state directory sits inside (both sides canonical), or null when it is outside all. */
+export function stateDirInside(stateDir: string, roots: readonly StateRoot[]): StateRoot | null {
+  const state = canonicalStatePath(stateDir);
+  for (const root of roots) if (within(canonicalStatePath(root.path), state)) return root;
+  return null;
+}
+
+/** The refusal text after the code: which supplied folder holds the state directory. */
+export const stateInsideMessage = (root: StateRoot) => `the review state directory is inside the inspected ${root.kind}; set RIG_REVIEW_STATE_DIR outside it`;
+
+/** Throws `make(code-less message)` when the state directory sits inside one of the package's supplied folders. */
+export function assertStateOutside(stateDir: string, p: StateRootsSource, make: (message: string, root: StateRoot) => Error): void {
+  const root = stateDirInside(stateDir, stateRoots(p));
+  if (root) throw make(stateInsideMessage(root), root);
+}

package/web/environment-world.ts

@@ -40,3 +40,18 @@ export function environmentCheckRows(job: EnvironmentCheckView, defaultLine: (na
   if (job.check?.line) rows.push({ kind: 'label', text: `this world · ${job.check.line}` });
   return rows;
 }
+
+/**
+ * #183: a move of the drawn clip, as the page makes it — another animation chosen, a seek (scrub, cue, reading, control),
+ * a replay from the end (Play after the clip ended, idle repeat's loop), or an Apply's reload, which keeps the animation
+ * and time and resumes the world it had.
+ */
+export type ClipMove = { kind: 'choose' } | { kind: 'seek'; to: number } | { kind: 'replay' } | { kind: 'reload' };
+/**
+ * Whether the move restarts the clip and so, while the schedule is watched (Use for readings), the wind clock restarts
+ * with it: the exported schedule starts at t = 0 on the clip's first frame, so the stage must too.
+ */
+export function restartsWindClock(move: ClipMove, watched: boolean): boolean {
+  if (!watched) return false;
+  return move.kind === 'choose' || move.kind === 'replay' || (move.kind === 'seek' && move.to <= 0);
+}

package/web/label-placement.ts

@@ -6,6 +6,8 @@
  * tries its home box (right of the point, rising from it), then the box left of the point, then both sides shifted up
  * and down by one row at a time; it takes the first box that intersects no box already placed nor an obstacle (the point
  * glyphs) and stays inside the bounds. A label with no free box within `rows` is hidden; a pinned label is never hidden and falls back to its home box.
+ * With bounds, a label whose point is outside them (a joint panned or zoomed off the canvas, its glyph clipped) is not
+ * placed at all, pinned or not (#186): a tag and leader for a joint that is not drawn would be a phantom annotation.
  */
 export interface LabelPoint {x:number;y:number}
 export interface LabelInput {at:LabelPoint;width:number;pinned?:boolean}
@@ -34,9 +36,11 @@ export function labelCandidates(input:LabelInput,options:LabelPlacementOptions={
 export function placeLabels(inputs:readonly LabelInput[],options:LabelPlacementOptions={}):PlacedLabel[]{
  const order=inputs.map((_,i)=>i).sort((a,b)=>Number(!!inputs[b]!.pinned)-Number(!!inputs[a]!.pinned)||a-b);
  const inside=(b:LabelBox)=>!options.bounds||(b.x>=0&&b.y>=0&&b.x+b.w<=options.bounds.width&&b.y+b.h<=options.bounds.height);
+ const onCanvas=(p:LabelPoint)=>!options.bounds||(p.x>=0&&p.y>=0&&p.x<=options.bounds.width&&p.y<=options.bounds.height);
  const placed:LabelBox[]=[...(options.obstacles??[])],out:PlacedLabel[]=new Array(inputs.length);
  for(const i of order){
   const input=inputs[i]!,candidates=labelCandidates(input,options),home=candidates[0]!;
+  if(!onCanvas(input.at)){out[i]={box:home,visible:false,moved:false};continue;}
   const index=candidates.findIndex(b=>inside(b)&&!placed.some(p=>boxesIntersect(b,p)));
   if(index>=0){const box=candidates[index]!;placed.push(box);out[i]={box,visible:true,moved:index>0};}
   else if(input.pinned){placed.push(home);out[i]={box:home,visible:true,moved:false};}