@bongos/core 1.19.663 → 1.19.665

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/modules/provisioning/credential-preflight.js

@@ -0,0 +1,170 @@
+// modules/provisioning/credential-preflight.js — does the caller hold a credential
+// that can actually stand up the repo they are adopting? (task 1002909, 1002898 N3)
+//
+// THE GAP THIS CLOSES. `POST /provisioning/instances` validated that an `adopt`
+// carried a target_ref, but never that the owner could READ it — so an API caller
+// could queue a standup that was doomed at request time and only learned about it
+// ~2 minutes later, as raw git stderr on the runner (the task-1002697 acceptance
+// walk did exactly that). The web wizard was only incidentally protected: it 403s
+// earlier on its own repo picker. The API had nothing.
+//
+// WHY IT WAITED FOR ADR 0176 (task 1002735). A preflight is only as good as its
+// definition of "usable credential", and 1002898 carved this out rather than guess
+// at one: written against the wrong definition it would either refuse valid creates
+// or keep admitting doomed ones. 1002735 settled it, so this file encodes THAT
+// definition and nothing else — what `ensurePrivateRepoAccess` (scripts/gds/
+// provision-repo.js) will demand at standup time, asked one round-trip earlier:
+//
+//   public target_ref   → any readable credential is enough. The recurring deploy
+//                         pull rides the shared SSH alias, which reads public repos
+//                         without being registered on them.
+//   private target_ref  → the runner must register a READ-ONLY deploy key on the
+//                         repo, and GitHub requires repository ADMIN for that. A
+//                         credential that can merely read a private repo is NOT
+//                         enough, and discovering that mid-standup is the loud
+//                         version of this same refusal.
+//
+// GREENFIELD IS EXEMPT, and that exemption is load-bearing (the constraint carried
+// over from 1002898): the platform CREATES that repo itself, so there is no
+// pre-existing repo for a credential to cover and nothing here to check.
+//
+// A TRANSIENT GITHUB FAILURE ADMITS. This refuses only on POSITIVE evidence that a
+// standup cannot succeed. GitHub being unreachable is not that evidence — and the
+// runner takes the same posture (`skipped: 'github_unreachable'` continues rather
+// than throwing), so a GitHub hiccup must not become an outage of project creation.
+//
+// WHY IT READS THE TOKEN ITSELF rather than calling core's db.getGithubToken /
+// github-repos.getUserRepo. `src/module-api.js` is a KERNEL file (ADR 0091 §1) and
+// may depend only on kernel files; `src/bongos/db.js` and `src/bongos/github-repos.js`
+// are domain, so routing either through the doorway fails the boundary check in
+// scripts/gds/fitness.js. Modules own their data access through the exposed `pool`
+// (the module contract's own rule), so the two small reads below are that ownership,
+// not a shortcut around it. Both are DELIBERATE TWINS of core's versions and say so;
+// `grantedScopeCoversRepos` is reached through the doorway instead of re-implemented
+// because it is kernel (src/bongos/auth-config.js) AND because its subtlety —
+// `public_repo` CONTAINS "repo", so a substring match accepts exactly the stale
+// pre-ADR-0155 token this guards against — is the kind that must never be re-typed.
+//
+// Its own file, like ../paid-shape-gate.js, for the same two mechanical reasons:
+// `routes/provisioning.js` sits at its 1500-line fitness ratchet, and every
+// dependency here is INJECTED so the check is exercisable without standing up the
+// auth stack or touching the network.
+'use strict';
+
+// Mirrors scripts/gds/provision-repo.js parseTargetRef EXACTLY. The preflight and
+// the runner must agree on what a target_ref means, or this admits refs the runner
+// cannot parse (and refuses ones it can) — a divergence that would be silent.
+function parseTargetRef(ref) {
+  const m = String(ref || '').trim()
+    .replace(/^git@[^:]+:/, '')
+    .replace(/^https?:\/\/[^/]+\//, '')
+    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+// Twin of src/bongos/db.js getGithubToken, kept in step with it deliberately (see
+// the header). Returns { token, scope } or null when there is none, it expired, or
+// the blob will not decrypt under the current master key. Unlike core's version it
+// does NOT lazily delete an expired row — a read-only preflight must not mutate, and
+// core's own reaper still runs on the endpoints that own that table.
+async function readOwnerRepoToken({ builderId }, { pool, secretBox }) {
+  if (!secretBox.isConfigured()) return null;
+  const { rows } = await pool.query(
+    `SELECT token_enc, scope, expires_at FROM github_oauth_tokens WHERE builder_id = $1`,
+    [builderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (new Date(row.expires_at).getTime() <= Date.now()) return null;
+  try { return { token: secretBox.decrypt(row.token_enc), scope: row.scope }; }
+  catch { return null; }   // a blob that won't decrypt reads as "none", as in core
+}
+
+// Twin of src/bongos/github-repos.js getUserRepo, narrowed to the two fields this
+// decision needs. Throws { code } on the cases the caller branches on; every other
+// status is a transient the caller admits on.
+async function fetchRepoVisibility(token, { owner, name, fetchImpl, userAgent }) {
+  const res = await (fetchImpl || fetch)(
+    `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+    { headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent, Accept: 'application/vnd.github+json' } },
+  );
+  if (res.status === 401) throw Object.assign(new Error('github rejected the token'), { code: 'github_unauthorized' });
+  if (res.status === 404) throw Object.assign(new Error('repo not found'), { code: 'repo_not_found' });
+  if (!res.ok) throw Object.assign(new Error(`github ${res.status}`), { code: 'github_error' });
+  const r = await res.json();
+  return { private: !!r.private, admin: !!(r.permissions && r.permissions.admin) };
+}
+
+// adoptCredentialFault — null to ADMIT the create, or the refusal the route should
+// send: { code, status, message }. Returning a value rather than writing to `res`
+// keeps this directly testable and leaves the HTTP shape with the route that owns it.
+//
+// deps: { pool, secretBox, grantedScopeCoversRepos, userAgent, fetchImpl?,
+//         readToken?, fetchRepo? } — the last two are test seams.
+async function adoptCredentialFault({ builderId, onboardMode, targetRef }, deps) {
+  if (onboardMode !== 'adopt') return null;            // greenfield: nothing to check
+  const { grantedScopeCoversRepos, secretBox, fetchImpl, userAgent } = deps;
+  const readToken = deps.readToken || readOwnerRepoToken;
+  const fetchRepo = deps.fetchRepo || fetchRepoVisibility;
+
+  // An unparseable ref cannot be checked, and the runner's identical parse would
+  // fail on it too — so this is a doomed standup, refused for the reason it is
+  // doomed rather than admitted because the credential question never got asked.
+  const repo = parseTargetRef(targetRef);
+  if (!repo) {
+    return { code: 'bad_target_ref', status: 400,
+      message: 'Name the repository to adopt as owner/repo.' };
+  }
+
+  // No secret-box means no token can be STORED at all, so every adopt would fail at
+  // the push. 503, not 403: the fault is the server's configuration, not the caller's.
+  if (!secretBox.isConfigured()) {
+    return { code: 'github_credential_unavailable', status: 503,
+      message: 'Repo access is not configured on this server, so an existing repository cannot be adopted yet.' };
+  }
+
+  const row = await readToken({ builderId }, deps);
+  if (!row || !row.token) {
+    return { code: 'repo_scope_required', status: 403,
+      message: 'Connect your GitHub account before adopting an existing repository.' };
+  }
+
+  let info;
+  try {
+    info = await fetchRepo(row.token, { owner: repo.owner, name: repo.name, fetchImpl, userAgent });
+  } catch (e) {
+    const code = e && e.code;
+    if (code === 'github_unauthorized') {
+      return { code: 'repo_scope_required', status: 403,
+        message: 'GitHub rejected your stored credential — reconnect your GitHub account and try again.' };
+    }
+    if (code === 'repo_not_found') {
+      // A `public_repo`-scoped token cannot SEE a private repo: GitHub answers 404
+      // for "absent" and for "private and invisible to you" identically. So the
+      // message covers both honestly rather than asserting the repo does not exist —
+      // a pre-ADR-0155 token reaching its own private repo lands exactly here, which
+      // is the hermeslines-marketing failure told at request time instead of at the pull.
+      if (!grantedScopeCoversRepos(row.scope)) {
+        return { code: 'repo_scope_required', status: 403,
+          message: `We cannot see ${repo.owner}/${repo.name}. If it is private, reconnect GitHub to include your private repositories; if it is public, check the name.` };
+      }
+      return { code: 'target_repo_not_found', status: 404,
+        message: `GitHub has no repository ${repo.owner}/${repo.name} that your account can reach — check the name, or that you still have access.` };
+    }
+    return null;   // unreachable / 5xx: no positive evidence of doom, so admit
+  }
+
+  // Private repos need repository ADMIN, because the runner registers a read-only
+  // deploy key to keep the deploy pull working after the one-shot OAuth token dies
+  // (ADR 0176). Read-only collaborator access passes the read above and then fails at
+  // key registration — the exact "looked like it worked" shape this exists to end.
+  // The sentence matches the runner's own so the two can never disagree.
+  if (info.private && !info.admin) {
+    return { code: 'repo_admin_required', status: 403,
+      message: `Your GitHub account can read ${repo.owner}/${repo.name}, but adopting a private repository needs repository ADMIN so its deploy key can be registered. Ask a repository admin to raise your access, or make the repository public.` };
+  }
+
+  return null;
+}
+
+module.exports = { adoptCredentialFault, parseTargetRef, readOwnerRepoToken, fetchRepoVisibility };

package/modules/provisioning/routes/provisioning.js

@@ -14,7 +14,10 @@
 //     POST   /provisioning/instances               — request a new instance
 //                                                     (a `dedicated` shape ALSO needs
 //                                                      provisioning.fleet.manage — it is the
-//                                                      only shape that bills; ../paid-shape-gate.js)
+//                                                      only shape that bills; ../paid-shape-gate.js.
+//                                                      An `adopt` ALSO passes the credential
+//                                                      preflight — ../credential-preflight.js,
+//                                                      task 1002909; greenfield is exempt)
 //     GET    /provisioning/instances               — list the caller's instances
 //     GET    /provisioning/instances/:id           — read one of the caller's instances
 //                                                     (also SELF-HEALS its catalog projection,
@@ -49,6 +52,7 @@ const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModu
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 const { requireAuthorityForMeteredShape } = require('../paid-shape-gate');
+const { adoptCredentialFault } = require('../credential-preflight');
 const catalogBridge = require('../catalog-bridge');
 const { callbackPage } = require('./callback-page');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -409,17 +413,18 @@ module.exports = function provisioningRoutes() {
         reason: 'adopt layers onto an existing repo, so target_ref (owner/repo) is required',
       });
     }
-    // KNOWN GAP — the credential preflight belongs HERE, and is deliberately absent.
-    // This route validates that target_ref is PRESENT but never that the owner holds a
-    // usable repo credential for it, so an API caller can queue a standup that dies
-    // ~2 minutes later in raw git stderr (the task-1002697 walk did exactly that; the
-    // web wizard is only incidentally protected because it 403s earlier). Carved out of
-    // task 1002898 as N3 and tracked by task 1002909, which is BLOCKED on task 1002735
-    // deciding what credential a private-repo standup actually needs: written against
-    // the wrong definition, a preflight would refuse valid creates or keep admitting
-    // doomed ones. Greenfield must stay exempt when it lands — the platform creates
-    // that repo itself, so there is no pre-existing repo to hold a credential for.
     try {
+      // The credential preflight (task 1002909, 1002898 N3). An `adopt` names a repo
+      // the platform must read forever, so ask ONE round-trip early whether this
+      // caller's credential can actually carry that standup — rather than queueing a
+      // doomed intent the runner discovers two minutes later as raw git stderr (the
+      // task-1002697 walk). Greenfield is exempt by construction. Encodes ADR 0176's
+      // definition of a usable credential; ../credential-preflight.js says why.
+      const credFault = await adoptCredentialFault(
+        { builderId: req.builder.id, onboardMode, targetRef: body.target_ref },
+        { pool, secretBox: api.secretBox, grantedScopeCoversRepos: api.grantedScopeCoversRepos, userAgent: api.userAgent() },
+      );
+      if (credFault) return res.fail(credFault.code, { status: credFault.status, message: credFault.message });
       // A re-request must not re-litigate the address: createInstance never updates
       // an existing row's domain, so for one the guards below could only misfire —
       // a "Try again" on a pre-existing reserved-label row, or domain_taken fired