@bongos/core 1.19.664 → 1.19.666

package/modules/hall-ui/public/studio.js

@@ -16,21 +16,35 @@
 //      shows people. Best-effort: an instance without the copy-desk module has
 //      no queue, and the room degrades to reviews alone rather than erroring.
 //
-// It writes NOTHING and gates NOTHING (ADR 0162 / the goal's no-live-CMS rule):
-// "open this" routes to where the craft is actually done (the task record, the
-// copy desk), and "let it be for now" only advances the reader to the next
-// piece. The full tables it replaces stay one link away in the footer.
+// It gates NOTHING (ADR 0162 / ADR 0241): nothing here holds a ship or a deploy.
+// And it writes NOTHING to any live string or asset — the goal's no-live-CMS
+// rule, unchanged. What it DOES write, since task 1003829, is the artist's own
+// VERDICT on their own queue: a review is a task in the ledger, and the three
+// weights below move that task the way triage always could. The craft itself
+// still happens on the surface that owns it (the task record, the copy desk),
+// and every change to the product still lands as a claimed, graded, shipped
+// task. The allowlist of what may be written is WRITE_ROUTES below, pinned in
+// tests/hall_studio_world.mjs.
+//
+// THE PICTURE (task 1003829). A review names the shipped task it is about, and
+// that task may carry a ship-time visual. The room reads it for the card in
+// focus and renders the image AS the card, because "look at it" is the whole of
+// what an artist is being asked to do here. One read per card, lazily, so a
+// 50-deep queue still costs one /tasks/:id.
 
 (() => {
   'use strict';
 
   const API = '/api/bongos';
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
-  const { escapeHtml, $ } = window.OTB;
+  const { escapeHtml, $, toast, errMessage } = window.OTB;
+  const kit = window.OTBKit;
 
   let viewer = null;
   let pieces = [];   // the combined garden: [{ type:'review'|'flag', … }]
   let idx = 0;       // which stone is in focus
+  let busy = false;  // a verdict is in flight — one at a time, so a double-click cannot file twice
+  let tended = false; // at least one verdict landed this sitting, so an emptied garden reads as finished
 
   // Bound the reviews read. cascade.js files a review per qualifying ship and they
   // sit at backlog until claimed or dismissed ("dismissable rather than nagging"),
@@ -42,6 +56,43 @@
   // keeps the most-prioritised waiting reviews.
   const REVIEW_LIMIT = 50;
 
+  // The ONLY writes this room may issue, as an explicit allowlist rather than a
+  // convention (tests/hall_studio_world.mjs asserts studio.js writes nothing
+  // outside it). Each moves the REVIEW TASK — the artist's own queue item — and
+  // none of them touches a live string, an asset, a claim, a grade or a deploy:
+  //
+  //   abandon  looks good   → the review is dismissed, which cascade.js's own
+  //                           body calls "a real, expected outcome".
+  //   patch    note it      → the artist's words are appended to the review's
+  //                           brief, which is what whoever claims it reads.
+  //   create   needs work   → the words become a new task in the reviewed
+  //                           work's goal…
+  //   merge                 → …and the review is closed against that task, so
+  //                           the follow-up carries the lineage instead of the
+  //                           review just vanishing.
+  //
+  // All four floor at METIC server-side (modules/government/catalog.js:
+  // task.abandon / task.edit / task.create / task.merge). The room therefore
+  // OFFERS them only to a viewer who holds that floor — the task 1003751 lesson,
+  // that a card must not print a verb its route will refuse. ADR 0016 still
+  // stands: this is cosmetic, and the routes are the wall.
+  const WRITE_ROUTES = Object.freeze({
+    abandon: (reviewId) => `${API}/tasks/${reviewId}/abandon`,
+    patch: (reviewId) => `${API}/tasks/${reviewId}`,
+    create: () => `${API}/tasks`,
+    merge: (reviewId) => `${API}/tasks/${reviewId}/merge`,
+  });
+
+  // The verdict floor, read off /me. Local like goals-render.js's copy — four
+  // ranks, one comparison, and no reason for the kit to own a ladder.
+  const RANK_ORDER = { archon: 4, metic: 3, thetes: 2, xenos: 1 };
+  const MAX_WORDS = 2000;  // the abandon/merge `reason` cap the routes apply anyway
+
+  function canVerdict() {
+    const rank = String((viewer && viewer.rank) || '').toLowerCase();
+    return (RANK_ORDER[rank] ?? 0) >= RANK_ORDER.metic;
+  }
+
   // ---------------------------------------------------------------------------
   // helpers
   // ---------------------------------------------------------------------------
@@ -80,18 +131,81 @@
   // the focus card, one shape per kind of work
   // ---------------------------------------------------------------------------
 
+  // THE PLATE — the reviewed work's ship-time visual, at the size the card can
+  // give it. Through the kit's one renderer (OTBKit.taskVisualFigureHtml, which
+  // carries the server-minted-URL guard and the escaping) with the Studio's own
+  // class, because the size is this surface's decision: here the picture is the
+  // subject, not an illustration beside a record.
+  //
+  // Draws nothing when there is no visual, when the reviewed task could not be
+  // read, or when the kit is absent — a review with no picture must read as a
+  // review, never as an empty frame (the degrade rule).
+  function plateHtml(p) {
+    if (!p.shipped || !kit || typeof kit.taskVisualFigureHtml !== 'function') return '';
+    return kit.taskVisualFigureHtml(p.shipped, { className: 'studio-plate' });
+  }
+
+  // The three weights, and the one field they share. Offered only to a viewer
+  // whose rank clears the routes' floor (see WRITE_ROUTES) — otherwise the card
+  // says plainly where the verdict is recorded instead of printing three
+  // buttons that would 403.
+  //
+  // "looks good" takes words or no words; the other two require them, because a
+  // note with no note and a follow-up task with no brief are both worse than
+  // nothing. The check is in the handler, and it answers inline.
+  function verdictHtml(p) {
+    if (!canVerdict()) {
+      return `<p class="studio-verdict__sealed">Your verdict on a review is recorded from the review itself — open it to dismiss it, note what you saw, or file the follow-up.</p>`;
+    }
+    const id = escapeHtml(String(p.taskId));
+    return `
+      <div class="studio-verdict">
+        <label class="studio-verdict__label" for="studio-words">What you saw <small>— your words, in your voice. Needed for a note or a follow-up.</small></label>
+        <textarea class="studio-verdict__words" id="studio-words" rows="3" maxlength="${MAX_WORDS}"
+          placeholder="The headline lands, but the sub-line reads like a brochure."></textarea>
+        <p class="studio-verdict__err" id="studio-verdict-err" hidden></p>
+        <!-- Three ghosts, no accent: the weights are three equal answers, and
+             the One Warm Thing Rule spends the accent on the door to the craft
+             below. Nothing here should push an artist toward filing work. -->
+        <div class="studio-verdict__weights">
+          <button type="button" class="btn-ghost" data-verdict="good" data-review="${id}">Looks good</button>
+          <button type="button" class="btn-ghost" data-verdict="note" data-review="${id}">Note it</button>
+          <button type="button" class="btn-ghost" data-verdict="work" data-review="${id}">Needs work</button>
+        </div>
+      </div>`;
+  }
+
+  // The two steps of the craft (R04) — what happens INSIDE a review once it is
+  // opened. Today's copy, and the whole of what a review card could say before
+  // there was a picture on it.
+  const STEPS = `
+      <ol class="studio-steps">
+        <li class="studio-step"><span class="studio-step__n">01</span><span>Coach the grader<small>Review how it judged this work, and teach it what good looked like.</small></span></li>
+        <li class="studio-step"><span class="studio-step__n">02</span><span>Remake or tweak<small>Only if it needs it — with the AI at your side, or on your own.</small></span></li>
+      </ol>`;
+
   function reviewCard(p, n) {
     const title = p.shippedId
       ? `The copy and visuals that shipped in task #${escapeHtml(p.shippedId)}`
       : escapeHtml(p.title || 'A review of what shipped');
+    const plate = plateHtml(p);
+    // WITH A PICTURE the card is the picture: one line of framing, then the
+    // verdict, so the thing being judged and the answer to it are on one screen.
+    // The two steps describe the work done AFTER opening the review, and they
+    // belong behind that door rather than between the artist and their answer.
+    //
+    // WITHOUT ONE the card degrades to exactly the copy it has always shown —
+    // the framing paragraph and both steps — so a review with no visual still
+    // reads as a review and never as an empty frame.
+    const body = plate
+      ? `<p class="studio-card__context">It shipped and it is live. Say what you see — your review coaches the grader and never blocks what shipped.</p>`
+      : `<p class="studio-card__context">It shipped and it is live. Your review coaches the grader on how it judged the work, then remakes or tweaks the words or art only if they need it — it never blocks what shipped.</p>${STEPS}`;
     return `
       <p class="studio-card__eyebrow">to tend now · ${escapeHtml(n)}</p>
       <h2 class="studio-card__title">${title}</h2>
-      <p class="studio-card__context">It shipped and it is live. Your review coaches the grader on how it judged the work, then remakes or tweaks the words or art only if they need it — it never blocks what shipped.</p>
-      <ol class="studio-steps">
-        <li class="studio-step"><span class="studio-step__n">01</span><span>Coach the grader<small>Review how it judged this work, and teach it what good looked like.</small></span></li>
-        <li class="studio-step"><span class="studio-step__n">02</span><span>Remake or tweak<small>Only if it needs it — with the AI at your side, or on your own.</small></span></li>
-      </ol>
+      ${plate}
+      ${body}
+      ${verdictHtml(p)}
       <div class="studio-card__actions">
         <a class="btn-accent" href="/builders/task/${escapeHtml(String(p.taskId))}">Open this review</a>
         <button type="button" class="btn-ghost" data-skip>Let it be for now</button>
@@ -139,11 +253,17 @@
     const focus = $('#studio-focus');
     const rest = $('#studio-rest');
 
-    if (!pieces.length) { focus.innerHTML = emptyCard(false); rest.hidden = true; return; }
+    // An emptied garden reads as FINISHED once the reader has actually tended
+    // something this sitting, and as quiet when there was nothing to begin with.
+    if (!pieces.length) { focus.innerHTML = emptyCard(tended); rest.hidden = true; return; }
     if (idx >= pieces.length) { focus.innerHTML = emptyCard(true); rest.hidden = true; return; }
 
     const p = pieces[idx];
     focus.innerHTML = p.type === 'review' ? reviewCard(p, `${idx + 1} of ${pieces.length}`) : flagCard(p, `${idx + 1} of ${pieces.length}`);
+    // The reviewed work is read for the card in FOCUS, and only once. hydrate()
+    // repaints when it lands, so the card appears immediately and the picture
+    // arrives a beat later rather than the room waiting on a second request.
+    hydrate(p);
 
     // The rest of the garden: one stone per remaining piece, quiet and
     // non-interactive — the room asks the reader to tend one thing, not to scan.
@@ -160,6 +280,190 @@
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // the reviewed work — read for the card in focus, once
+  // ---------------------------------------------------------------------------
+
+  // Hydrate ONE review with the task it is about, then repaint. Lazy on purpose:
+  // the queue is capped at 50 and the room shows one piece at a time, so eagerly
+  // reading every reviewed task would be 50 requests to render one card — the
+  // unbounded-read shape modules/hall-ui/CLAUDE.md flags. `hydrated` is set
+  // whether or not the read succeeded, so a 404 or a 403 is asked once and the
+  // card then simply carries no picture.
+  async function hydrate(p) {
+    if (!p || p.type !== 'review' || p.hydrated || !p.shippedId) return;
+    p.hydrated = true;
+    const res = await api.request('GET', `${API}/tasks/${encodeURIComponent(p.shippedId)}`);
+    if (!res.ok) return;
+    const t = (res.data && res.data.task) || null;
+    if (!t) return;
+    // The security_sensitive narrowing, taken from the server's own audience
+    // predicate (modules/lifecycle/task-visuals.js isPubliclyViewable, and the
+    // public feed's SQL): a security_sensitive task's image is the one visual
+    // the platform does not re-publish, so this room does not re-publish it
+    // either. The review still reads as a review — it degrades to the copy.
+    //
+    // BE CLEAR WHAT THIS IS: a UI choice, not a wall. isPubliclyViewable gates
+    // the UNAUTHENTICATED path, so GET /tasks/:id hands the full visual_url and
+    // visual_alt to any signed-in builder and the response in this very browser
+    // already carries them. Dropping them here keeps a sensitive image off a
+    // room that exists for looking at things, and keeps the URL out of the DOM
+    // and out of a screenshot of it. It secures nothing on its own, and nothing
+    // here should be read as a substitute for the server's gate.
+    p.shipped = t.security_sensitive === true ? { id: t.id } : t;
+    if (pieces[idx] === p) paint();
+  }
+
+  // ---------------------------------------------------------------------------
+  // the verdict — the artist's answer, recorded against the review
+  // ---------------------------------------------------------------------------
+
+  function words() {
+    const el = $('#studio-words');
+    return el ? String(el.value || '').trim().slice(0, MAX_WORDS) : '';
+  }
+
+  function verdictError(msg) {
+    const el = $('#studio-verdict-err');
+    if (!el) return;
+    el.textContent = msg || '';
+    el.hidden = !msg;
+  }
+
+  // The review is done with: drop it from the garden and move to the next stone
+  // without renumbering what the reader already passed.
+  function retire(p) {
+    const at = pieces.indexOf(p);
+    if (at === -1) return;
+    tended = true;
+    pieces.splice(at, 1);
+    if (idx > at) idx -= 1;
+    paintHead();
+    paint();
+    window.scrollTo({ top: 0 });
+  }
+
+  // "Looks good" — dismiss. cascade.js's own body says this is a real and
+  // expected outcome, so it is a first-class button and not a hidden one. The
+  // words are optional here and ride along as the retire reason, which
+  // db.abandonTask stores on the task as "Abandoned: <reason>".
+  async function verdictGood(p) {
+    const said = words();
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const reason = `Reviewed in the studio by ${who} — the copy and visuals are good as shipped.${said ? ` ${said}` : ''}`;
+    const res = await api.request('POST', WRITE_ROUTES.abandon(p.taskId), { reason });
+    if (!res.ok) return verdictError(errMessage(res.data) || 'That could not be recorded. Nothing changed.');
+    toast('Dismissed — the copy and visuals are good as shipped.');
+    retire(p);
+    return undefined;
+  }
+
+  // "Note it" — the artist's words, recorded against the review, which stays
+  // open. They are APPENDED to the review's own description because that is the
+  // text whoever claims this review actually reads; the route audit-logs every
+  // description edit, so the note has a trail as well as a home.
+  //
+  // THE BASE IS RE-READ, not taken from the queue row, and both halves of that
+  // matter. PATCH description REPLACES the field, so appending to a stale or
+  // absent base does not add a note — it DELETES the cascade's brief. The list
+  // read happens to carry `description` today (db-tasks.js listTasks is
+  // SELECT t.*), but that projection is already under pressure from the board's
+  // read sizes, and a narrowing there must not silently blank a review body
+  // here. The re-read also means a second artist noting on the same review
+  // appends after the first instead of overwriting them. No base, no write.
+  async function verdictNote(p) {
+    const said = words();
+    if (!said) return verdictError('Write what you saw first — a note with no note is worse than none.');
+    const cur = await api.request('GET', `${API}/tasks/${p.taskId}`);
+    const base = cur.ok && cur.data && cur.data.task ? String(cur.data.task.description || '') : null;
+    if (base === null) {
+      return verdictError('The review could not be re-read just now, so nothing was written — try again in a moment.');
+    }
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const stamp = new Date().toISOString().slice(0, 10);
+    const block = `\n\n---\n\nARTIST NOTE (${stamp}, ${who}, from the studio):\n\n${said}`;
+    const res = await api.request('PATCH', WRITE_ROUTES.patch(p.taskId), { description: `${base}${block}` });
+    if (!res.ok) return verdictError(errMessage(res.data) || 'That could not be recorded. Nothing changed.');
+    p.description = `${base}${block}`;
+    toast('Noted on the review — it stays open.');
+    const el = $('#studio-words');
+    if (el) el.value = '';
+    verdictError('');
+    return undefined;
+  }
+
+  // "Needs work" — the words become a NEW task in the reviewed work's goal, and
+  // the review is closed AGAINST it.
+  //
+  // No live edit happens here and none can: what this files is an ordinary
+  // backlog task that somebody has to claim, build, have graded and ship, which
+  // is goal 1000074's hard rule stated as a mechanism rather than a promise.
+  //
+  // The review's own goal_id/version_id are the reviewed work's — cascade.js
+  // property 3: a generated review inherits the source task's goal and version.
+  // So the follow-up lands beside the work it is about with no second read.
+  //
+  // source_ref makes the pair idempotent: POST /tasks keys on (source,
+  // source_ref), so a double-click or a retry resolves to the SAME follow-up
+  // rather than minting a second one, and the merge below is idempotent when it
+  // re-merges into the target already recorded.
+  async function verdictWork(p) {
+    const said = words();
+    if (!said) return verdictError('Write what needs work first — a follow-up with no brief cannot be claimed.');
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const about = p.shippedId ? `task ${p.shippedId}` : `review ${p.taskId}`;
+    const created = await api.request('POST', WRITE_ROUTES.create(), {
+      version_id: p.versionId,
+      goal_id: p.goalId ? Number(p.goalId) : undefined,
+      title: `Artist verdict: the copy or visuals shipped in ${about} need work`,
+      description: [
+        `Filed from the studio by ${who}, as the verdict on artist review ${p.taskId} of ${about}.`,
+        '',
+        'WHAT THE ARTIST SAW:',
+        '',
+        said,
+        '',
+        'This is ordinary work: claim it, make the change, have it graded and ship it. The studio files the judgement and never edits a live string or asset (goal 1000074\'s rule).',
+      ].join('\n'),
+      discipline: 'artist',
+      source: 'studio-verdict',
+      source_ref: `studio-needs-work-on-review-${p.taskId}`,
+    });
+    if (!created.ok) return verdictError(errMessage(created.data) || 'The follow-up could not be filed. Nothing changed.');
+    const newId = created.data && created.data.task && created.data.task.id;
+    if (!newId) return verdictError('The follow-up came back without an id, so the review was left open.');
+    // Close the review against the follow-up. If this half fails the follow-up
+    // still exists and is reported as such — a stranded-but-visible task beats
+    // a silent success, and re-running the same verdict is safe.
+    const closed = await api.request('POST', WRITE_ROUTES.merge(p.taskId), {
+      into_task_id: Number(newId),
+      reason: `Artist verdict from the studio: the review's answer is task ${newId}, which carries the work.`,
+    });
+    if (!closed.ok) {
+      return verdictError(`Task ${newId} was filed, but this review could not be closed against it — close it from the review itself.`);
+    }
+    toast(`Filed as task ${newId} — this review is closed against it.`);
+    retire(p);
+    return undefined;
+  }
+
+  const VERDICTS = { good: verdictGood, note: verdictNote, work: verdictWork };
+
+  async function runVerdict(kind) {
+    const p = pieces[idx];
+    if (busy || !p || p.type !== 'review' || !VERDICTS[kind]) return;
+    if (!canVerdict()) return;
+    busy = true;
+    verdictError('');
+    try {
+      await VERDICTS[kind](p);
+    } catch (_err) {
+      verdictError('That could not be recorded. Nothing changed.');
+    } finally {
+      busy = false;
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // load
   // ---------------------------------------------------------------------------
@@ -174,7 +478,19 @@
     return tasks
       .filter((t) => t.source === 'cascade' || /^artist review\b/i.test(t.title || ''))
       .sort((a, b) => new Date(b.created_at || 0) - new Date(a.created_at || 0))
-      .map((t) => ({ type: 'review', taskId: t.id, title: t.title, shippedId: reviewShippedId(t) }));
+      // goalId/versionId are the REVIEWED work's — cascade.js property 3: a
+      // generated review inherits its source task's goal and version. They ride
+      // here so the "needs work" follow-up needs no second read, and
+      // `description` rides here so "note it" appends rather than overwrites.
+      .map((t) => ({
+        type: 'review',
+        taskId: t.id,
+        title: t.title,
+        description: t.description,
+        goalId: t.goal_id,
+        versionId: t.version_id,
+        shippedId: reviewShippedId(t),
+      }));
   }
 
   // The open flags. Best-effort: no copy-desk module → 404 → no flags, and the
@@ -198,7 +514,15 @@
 
   document.addEventListener('click', (ev) => {
     if (ev.target.closest('[data-skip]')) { idx += 1; paint(); window.scrollTo({ top: 0 }); return; }
-    if (ev.target.closest('[data-restart]')) { idx = 0; paint(); window.scrollTo({ top: 0 }); }
+    if (ev.target.closest('[data-restart]')) { idx = 0; paint(); window.scrollTo({ top: 0 }); return; }
+    const weight = ev.target.closest('[data-verdict]');
+    if (weight) runVerdict(weight.dataset.verdict);
+  });
+
+  // Clear the inline error as soon as the artist edits the field — the design
+  // system's rule: an error stands until the input that caused it changes.
+  document.addEventListener('input', (ev) => {
+    if (ev.target && ev.target.id === 'studio-words') verdictError('');
   });
 
   (async () => {

package/modules/hall-ui/public/studio.states.json

@@ -1,5 +1,5 @@
 {
-  "_": "The Studio (artist mode), R06 of goal 1000074 (task 1003117). A calm room that surfaces the artist's real work — backlog review requests (cascade, R04) and open copy flags (R02) — one piece at a time, never a table. Against the kit's own stub the page renders its EMPTY state (no /tasks or /copy-desk feed), which is a state the floors must hold in; against the hall-preview harness with the studio__reviews / copy-desk__queue fixtures it renders the focus card and the garden's stones.",
+  "_": "The Studio (artist mode), R06 of goal 1000074 (task 1003117). A calm room that surfaces the artist's real work — backlog review requests (cascade, R04) and open copy flags (R02) — one piece at a time, never a table. Against the kit's own stub the page renders its EMPTY state (no /tasks or /copy-desk feed), which is a state the floors must hold in. TO SEE IT POPULATED, point the kit at the hall-preview harness instead: `node scripts/hall-preview/server.js --port 4629 --fixture-me` then `render.js --base-in http://builders.localhost:4629 --base-out http://builders.localhost:4629`. That harness answers /tasks from fixtures/tasks.json (whose first row IS a cascade artist review), the reviewed task from fixtures/tasks__detail.json (which carries a visual_url), and the visual itself as a generated stand-in — task 1003829, where the review card's picture became the subject of the card and a broken frame stopped being reviewable. An earlier version of this note named a studio__reviews.json fixture; there is no such file and there never was.",
   "page": "/builders/studio",
   "surface": "hall-ui",
   "stub": {

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.664",
+  "version": "1.19.666",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.664",
+      "version": "1.19.666",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.664",
+  "version": "1.19.666",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/conductor-dispatch.js

@@ -44,6 +44,9 @@
 // 0 when a task was selected (a directive was emitted), 1 on a NO-GO / no work.
 
 const { execFileSync } = require('node:child_process');
+// basename(cwd) is the worktree name a claim is bound to (task 1003834) — the
+// same value claim.js records via --worktree.
+const path = require('node:path');
 const { cliClient } = require('./cli-lib');
 const grader = require('../../modules/grading/grader');
 // Phase 4.5: reuse the $0 deterministic autonomy precheck (the same gate the
@@ -195,11 +198,58 @@ function diffStatsSince(base, untracked) {
   };
 }
 
+// THE WORKTREE IS THE ANSWER, when there is one (task 1003834).
+//
+// A claim BINDS to a dedicated worktree — one claim per session, one worktree
+// per claim (task 1642, ADR 0097) — and `claim.js --worktree` records that
+// worktree's leaf-folder name on the claim row, which is exactly
+// `path.basename(process.cwd())`. So when this dispatch runs inside a claimed
+// worktree there is no inference to do: that worktree's claim IS the task being
+// worked on. Everything below it is a heuristic; this is a fact.
+//
+// Claims from before the column existed carry a null worktree_name and are
+// simply not matched here — the heuristic still covers them.
+function claimForWorktree(claims, worktreeName) {
+  if (!Array.isArray(claims) || !worktreeName) return null;
+  return claims.find((c) => c && c.worktree_name && c.worktree_name === worktreeName) || null;
+}
+
 // Pick the active claim whose touches[] best overlap the changed files — the
 // claim the current diff most plausibly belongs to. With multiple (possibly
 // stale) claims, blindly taking claims[0] grades the diff against the wrong
 // task: the Phase 4 dogfood's Narc FAILed because it graded Conductor code
 // against an unrelated stale offsite-backup claim. Best-overlap fixes that.
+//
+// SPECIFICITY, NOT VOLUME (task 1003834). A raw count of matched files rewards
+// BREADTH, so the more honestly a claim declares its touches[] the more likely
+// it loses. Observed 2026-09-10: reviewing task 1003829's diff, its own claim
+// declared three exact files (`modules/hall-ui/public/studio.{js,html,css}`) and
+// could therefore score at most 3, while a concurrent rename claim declaring
+// `scripts/gds/`, `src/bongos/`, `modules/`, `clients/` matched most of the
+// same diff and won — so the reviewer was briefed on an unrelated task. A
+// pattern like `modules/` covers almost any diff in this repo and must not
+// out-vote an exact path.
+//
+// So each matched file is worth the SPECIFICITY of the pattern that matched it:
+// its path-segment depth, plus a bonus when the pattern is the file itself.
+// Volume still counts — a genuinely broad claim matching fifty files beats a
+// narrow one sharing a single file — but depth breaks the tie the right way.
+function patternWeight(pattern, file) {
+  const p = String(pattern || '');
+  const depth = p.replace(/\/+$/, '').split('/').filter(Boolean).length;
+  return depth + (p === file ? EXACT_MATCH_BONUS : 0);
+}
+const EXACT_MATCH_BONUS = 1;
+
+function claimOverlapScore(claim, files) {
+  let score = 0;
+  for (const f of files) {
+    const hit = matchOne(f, (claim && claim.touches) || []);
+    if (hit !== null) score += patternWeight(hit, f);
+  }
+  return score;
+}
+
 function bestMatchingClaim(claims, changedFiles) {
   if (!Array.isArray(claims) || claims.length === 0) return null;
   const files = Array.isArray(changedFiles) ? changedFiles : [];
@@ -207,12 +257,29 @@ function bestMatchingClaim(claims, changedFiles) {
   let bestScore = -1;
   for (const c of claims) {
     // Use the canonical matcher; ties keep the earlier claim (strict >).
-    const score = files.filter((f) => matchOne(f, c.touches || []) !== null).length;
+    const score = claimOverlapScore(c, files);
     if (score > bestScore) { bestScore = score; best = c; }
   }
   return best;
 }
 
+// The claim this diff belongs to, and HOW that was decided — because the two
+// answers deserve very different trust. 'worktree' is a fact; 'overlap' is a
+// guess, and a guess that must be visible so a reader can discount a review
+// that argues from the brief rather than from the diff.
+//
+// A claim with an EMPTY touches[] scores zero against any diff, which is most
+// tasks in this repo — another reason the worktree signal leads rather than
+// merely breaking ties.
+function attributeClaim(claims, changedFiles, worktreeName) {
+  const byWorktree = claimForWorktree(claims, worktreeName);
+  if (byWorktree) return { claim: byWorktree, signal: 'worktree', worktree: worktreeName };
+  const byOverlap = bestMatchingClaim(claims, changedFiles);
+  if (!byOverlap) return { claim: null, signal: 'none', worktree: worktreeName || null };
+  const score = claimOverlapScore(byOverlap, Array.isArray(changedFiles) ? changedFiles : []);
+  return { claim: byOverlap, signal: score > 0 ? 'overlap' : 'fallback', worktree: worktreeName || null };
+}
+
 // --- task context (best-effort) ---
 // Workers grade a diff against a task. For a mid-flight review we use the
 // best-matching active claim's task; otherwise we synthesize a minimal
@@ -224,7 +291,12 @@ async function resolveTaskContext(changedFiles) {
     if (me.ok) {
       const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
       if (claims.length > 0) {
-        const c = bestMatchingClaim(claims, changedFiles);
+        // The worktree this dispatch was invoked in decides it when it can
+        // (task 1003834); the touches[] heuristic is the fallback, and which
+        // one answered is reported to the reader rather than hidden.
+        const attribution = attributeClaim(claims, changedFiles, path.basename(process.cwd()));
+        const c = attribution.claim;
+        if (!c) throw new Error('no claim attributed');
         // Pull the full description for richer context (best-effort). Coerce
         // task_id to an integer before interpolating it into the URL path —
         // it's a trusted internal value, but a guard costs nothing and closes
@@ -243,6 +315,11 @@ async function resolveTaskContext(changedFiles) {
           description: description || '(no description fetched — mid-flight review; judge the diff on its own merits)',
           kind: 'unclassified',
           version_id: c.version_id,
+          // How this task was attributed to this diff, carried so the header can
+          // say it (task 1003834). 'worktree' is a fact; anything else is a
+          // guess the reader should weigh.
+          attribution: attribution.signal,
+          claim_count: claims.length,
         };
       }
     }
@@ -257,6 +334,22 @@ async function resolveTaskContext(changedFiles) {
 
 // --- rendering ---
 
+// Say how the task context was chosen, but only when saying it changes what a
+// reader should do (task 1003834). Attribution by WORKTREE is certain, and a
+// single claim leaves nothing to confuse, so both stay silent. A guess made
+// while several claims were open is the case that misled a reader before, and
+// it says so out loud.
+function attributionNote(task) {
+  if (!task || !task.id) return '';
+  const n = Number(task.claim_count) || 0;
+  if (task.attribution === 'worktree' || n < 2) return '';
+  const how = task.attribution === 'overlap'
+    ? 'guessed from touches[] overlap'
+    : 'no signal at all — first claim taken';
+  return `\n   ⚠ attribution: ${how}, across ${n} open claims. This worktree is bound to no claim, so the brief`
+    + '\n     may belong to different work: weigh findings about the FILES, discount findings about intent.';
+}
+
 function renderWorker(w) {
   const lines = [];
   const status = w.error ? `ERROR (${w.error})` : w.verdict.toUpperCase();
@@ -382,7 +475,7 @@ async function main() {
   const routeRank = grader.routeRankPrePass(files);
 
   console.log(`🎼 Conductor dispatch → ${kinds.join(', ')}  (model=${model}, ${files.length} changed file(s), base=${base.slice(0, 8)})`);
-  console.log(`   task context: ${task.id ? '#' + task.id + ' ' + task.title : task.title}`);
+  console.log(`   task context: ${task.id ? '#' + task.id + ' ' + task.title : task.title}${attributionNote(task)}`);
   if (routeRank) console.log('   + deterministic route-rank check (route file in diff)');
   console.log('');
 
@@ -423,4 +516,9 @@ if (require.main === module) {
   });
 }
 
-module.exports = { pickSpecialists, bestMatchingClaim, selectAutonomousDispatch, autoDispatch };
+module.exports = {
+  pickSpecialists, bestMatchingClaim, selectAutonomousDispatch, autoDispatch,
+  // task 1003834 — the attribution layer, exported so its decisions are pinned
+  // rather than only observed through a dispatch run.
+  claimForWorktree, claimOverlapScore, attributeClaim, attributionNote,
+};

package/scripts/hall-preview/server.js

@@ -183,6 +183,17 @@ app.use((req, res, next) => {
     return;
   }
 
+  // The ship-time VISUAL is an image, not a fixture (task 1003829). Without
+  // this, every surface that renders one — the task record, a ship feed, the
+  // Studio's review card, where the picture IS the card — previews as a broken
+  // frame, so the one thing being reviewed is the one thing you cannot see.
+  // A generated stand-in; see scripts/hall-preview/task-visual.js.
+  if (/^task-visuals\/[A-Za-z0-9._-]+$/.test(apiPath) && req.method === 'GET') {
+    const png = require('./task-visual').placeholderPng();
+    res.set({ 'content-type': 'image/png', 'cache-control': 'no-store' });
+    return res.end(png);
+  }
+
   if (req.method !== 'GET') {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }