@bongos/core 1.19.389 → 1.19.391

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.389",
-  "core_contract": "1.19.389",
-  "source_commit": "6025dfdf6c2020fdf22152cb9edf610790cc83b0",
+  "core_version": "1.19.391",
+  "core_contract": "1.19.391",
+  "source_commit": "340dd8cf2dc62375b464f1deb56fa203cb37e47a",
   "source_ref": "HEAD",
-  "built_at": "2026-08-27T23:26:50.061Z",
+  "built_at": "2026-08-28T01:59:37.546Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 339,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1620,
+    "functional_verbatim": 1624,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1981,
-  "tree_sha256": "1cb4d393dd04fb49bb9f7aaaea5ae98dc3b4d9ce595c3a00b3aa0d86c7db7c95",
+  "file_count": 1985,
+  "tree_sha256": "5e47c4db4acc79aeebd5d9582aa0d5bc78dfac50ac7fceab7fb64269a6c0f76b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -42,7 +42,7 @@
     {
       "path": ".claude/skills/builder-claim/SKILL.md",
       "mode": "0000644",
-      "sha256": "4e6aeafd02b609df2a7651e11238a1b4c2f45b61f8a8f4122200c530aae81b25"
+      "sha256": "248ba892c506cb2ba5787dd9bc11978623d7116e9eb911e79d9c6b33b2d7374e"
     },
     {
       "path": ".claude/skills/builder-connect/SKILL.md",
@@ -1792,7 +1792,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "c717435fcd8d12a1073419666cdeeec1ae40d988789f2980413d2c22e1c45784"
+      "sha256": "4da98da4c1d5bc5e2a1c1949775f362d8867faa5a2a0321ccd954dc0a5b71202"
     },
     {
       "path": "docs/handoff-template.md",
@@ -5122,12 +5122,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "eea9d3bbfd5303579b774edd548952fb8faa1b88acc2d21a1091409a247ec3f0"
+      "sha256": "fa2614ac06762df93cebbd6d3b31ee9aa8610187156003199b894dedb875587c"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f012bfc1226d3d1d3dbe511bdb4c734f2e6731c37f220126f773b88ef3303a8c"
+      "sha256": "7ba34a8faeb6cf944e2603900caf3f203dc032a1a1eae04b87b93cf5a28cc293"
     },
     {
       "path": "public-docs/index.html",
@@ -5707,7 +5707,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "528e0fd4a91933cab751524f4a0c930dd0f23945801538182343faacf02d9ef7"
+      "sha256": "d2710556d771f5dcc7298806c91f3a33c7ad16b9f7738eef7edd14b7868d143b"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -6729,6 +6729,11 @@
       "mode": "0000644",
       "sha256": "be4fec619d5a0c76ba05bcc75042c1497f70da21b54a3d646884e2228f90b2ba"
     },
+    {
+      "path": "scripts/gds/worktree-claim-guard.js",
+      "mode": "0000644",
+      "sha256": "1ad4dfc90a2c5cd8afe40cd43c6b3d119e9bb7710785e024b4dd8d45e7ab823f"
+    },
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
@@ -6737,17 +6742,22 @@
     {
       "path": "scripts/hall-preview/README.md",
       "mode": "0000644",
-      "sha256": "12318c5928131ceb5dd7aa1322de0d4fd8116f80f1d41a84c0e1fd6b1f12a2c1"
+      "sha256": "880fb5ec7749e6e3092d5869b1f6baa64adbb956933f139eabfaf25347e3b9d8"
+    },
+    {
+      "path": "scripts/hall-preview/live-identity.js",
+      "mode": "0000644",
+      "sha256": "69edca9e3fd584f5e8f29aaf7451611e80c663be32114dc03cce1c5da22a9c5d"
     },
     {
       "path": "scripts/hall-preview/refresh-fixtures.js",
       "mode": "0000644",
-      "sha256": "ad8a601e499bc3c3b1fbd8d7180e8a2489461941e659169a7591899a778f7261"
+      "sha256": "b5819ccfabd209ced41613c6f9109faa2723a49c017c115a27383d907f777f3b"
     },
     {
       "path": "scripts/hall-preview/server.js",
       "mode": "0000644",
-      "sha256": "eb2c9bde186fcd050c41d68697945f46b9d891e545cc65f81db71b647a7cb3d9"
+      "sha256": "a55d67cab28ca941ad47a016bb5ed66d2fe1f410d0557544ee79ab57adc70006"
     },
     {
       "path": "scripts/migrate.sh",
@@ -7107,7 +7117,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6daab593739c8b3f37576399b8ba4cdcb6fdf82f8ce914ce1cdb4322ac8d1f24"
+      "sha256": "b5e645e16766a357b39033daec49842b257e6ce4450718d2f4e76667e4c6f304"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8449,6 +8459,11 @@
       "mode": "0000644",
       "sha256": "a53080637382b2313c6ed16d013fec6102a604fe7b8c72260945b5c85cb9303b"
     },
+    {
+      "path": "tests/hall_preview_identity.mjs",
+      "mode": "0000644",
+      "sha256": "4c2dadec059bd6ae7c1f16ec67f9ce6dd1d39eaa10aa7d1ad6219619947ffab4"
+    },
     {
       "path": "tests/hall_signout.mjs",
       "mode": "0000644",
@@ -9899,6 +9914,11 @@
       "mode": "0000644",
       "sha256": "43c7c42ffe92143443c45d5ba382d522efa0a16ef14f58675e6a86233e3f8e74"
     },
+    {
+      "path": "tests/worktree_claim_guard.mjs",
+      "mode": "0000644",
+      "sha256": "28662ce24931e2623c8d54e6931d80f400715a6661a6e78d638f7e8cdaa6db87"
+    },
     {
       "path": "tests/worktree_disambiguation.mjs",
       "mode": "0000644",

package/.claude/skills/builder-claim/SKILL.md

@@ -9,7 +9,7 @@ You are claiming a task on behalf of the current builder. The claim is atomic
 
 ## What this skill does
 
-Runs `node scripts/gds/claim.js <task-id> [--worktree NAME]`. The CLI hits `POST /api/gds/claims`, which transactionally:
+Runs `node scripts/gds/claim.js <task-id> [--worktree NAME]`. Before it hits the API at all, the CLI enforces **worktree-per-claim locally** (task 1002579 — see below). Then it hits `POST /api/gds/claims`, which transactionally:
 
 1. Verifies the task exists and is `ready`.
 2. Verifies all declared `dependencies[]` are in `shipped` status (V3.R02 / migration 020).
@@ -37,7 +37,13 @@ The server now **enforces** the one-claim half (task 1642): `POST /api/gds/claim
 
 1. **Confirm the task id with the user** if they didn't give a number directly.
 
-2. **Determine the worktree name** (cross-platform). If we're inside a worktree, the worktree name is the leaf folder of the current path. Resolve it portably with node (works on Windows/macOS/Linux — no `basename`/`$PWD` shell-isms):
+2. **Be in a per-claim worktree, not the main checkout.** `claim.js` **refuses** (exit 2) when it is run in the primary worktree — worktree-per-claim is the project default (task 1642) and task 1002579 is the check behind it. Branching in the main checkout parks it off `main`, and `ship.js`'s local auto-merge then has nowhere to merge INTO: the ship strands at `confirmed` until the server reconciler or `/merge-mode` catches it. The refusal names the exact fix; run it and claim from the new tree:
+   ```
+   node scripts/gds/worktree.js add <task-id>
+   ```
+   A linked worktree claims normally, and a tree git can't classify is allowed through (the guard never blocks on a guess). The escape hatch — for a builder who genuinely means to work in the main checkout — is `--here`, which downgrades the refusal to a loud warning and accepts the `confirmed`/`/merge-mode` finish.
+
+   **Determine the worktree name** (cross-platform). The worktree name is the leaf folder of the current path. Resolve it portably with node (works on Windows/macOS/Linux — no `basename`/`$PWD` shell-isms):
    ```
    node -e "console.log(require('path').basename(process.cwd()))"
    ```

package/docs/file-map.md

@@ -152,7 +152,7 @@
 │       ├── discord-channels.js  ← Archon CLI: plan/apply the Discord channel layout via the API (ADR 0036, #727)
 │       ├── setup.js             ← one-time GitHub Device Flow → ~/.config/otb/gds-session.json
 │       ├── start.js             ← list claimable tasks + active claims (`/builder-start`)
-│       ├── claim.js             ← atomic POST /api/gds/claims (`/builder-claim`); prints the claim-time context pack incl. next-free ADR/migration numbers (V4.R26); printDisciplineMode() reads discipline-modes.json to route a claimed task to its playbook skill
+│       ├── claim.js             ← atomic POST /api/gds/claims (`/builder-claim`); runs the worktree-per-claim guard (worktree-claim-guard.js) BEFORE the session check and the POST; prints the claim-time context pack incl. next-free ADR/migration numbers (V4.R26); printDisciplineMode() reads discipline-modes.json to route a claimed task to its playbook skill
 │       ├── discipline-modes.json ← discipline→operating-playbook map read by claim.js: ideator→/ideate, artist→/paint, engineer→/dev; absence of an entry = the default build-and-ship loop, fail-open ([#1267](https://example.com/builders#/task/1267))
 │       ├── next-number.js       ← deterministic next-free ADR + migration number from origin/main ∪ local working tree; supersedes the drift-prone claim-time DB counter (V4.R26, [#964](https://example.com/builders#/task/964)). `node scripts/gds/next-number.js [--json]`
 │       ├── gen-repo-map.js      ← Path B (ADR 0063, [#1224](https://example.com/builders#/task/1224)): zero-dep, deterministic symbol-skeleton generator → docs/repo-map.md + the generated factual block in each nested CLAUDE.md; ranks exported symbols by reference frequency. `--check` = CI gate; regenerated on deploy by ship.js regenerateRepoMap()
@@ -181,6 +181,7 @@
 │       ├── recall.js            ← `/recall` CLI: two-call progressive-disclosure search (summary → `--expand <id>`) over Bongos retrieval layer (ADR 0060); `node scripts/gds/recall.js <query>`
 │       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills. Task 1002927 / R151 taught it the GRADES: `--full --fields-file f.json` files a Full Idea, `--spark` is capture-then-mark (two requests — the route refuses a pre-marked capture), and after a plain quick capture it OFFERS to develop further. That offer is TTY-gated (`--no-prompt` too): capture.js is run by agents with no terminal and reads its body from stdin, so an unguarded prompt would hang every non-interactive caller
 │       ├── spark.js            ← (tasks 1002920 / R144 + 1002921 / R145 + 1002922 / R146) the whole spark handoff from the terminal: mark one of your OWN quick ideas as a Big Idea Spark (`--undo` withdraws it), `--list` is the SPARK QUEUE, `--template` prints the five Full Idea fields, `--develop <id> --fields-file <json>` is the PICKUP (any builder; author + developer both recorded). Author-only server-side for the mark (it is the consent); its own command because sparking acts on an EXISTING idea, which is why capture.js refuses grade='spark'
+│       ├── worktree-claim-guard.js ← (task 1002579) the PURE decision behind worktree-per-claim, enforced at claim time: claiming in the MAIN CHECKOUT is refused (escape hatch `--here` → loud warning), a linked worktree passes, an unclassifiable tree fails open. Stops the ship-time "the main checkout is on <branch>, not main" strand at its cause
 │       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.389",
+  "version": "1.19.391",
   "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/claim.js

@@ -2,7 +2,7 @@
 // Builder claim — atomically claim a task.
 //
 // Usage:
-//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]
+//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]
 //
 // On success: prints the claim id, the task title, and the touches[] so the
 // builder knows the parallel-safety boundary they're working within.
@@ -13,8 +13,9 @@ const path = require('node:path');
 const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote } = require('./cli-lib');
 const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
-const { contextPack, formatContextPack } = require('./context-pack');
+const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
 const { printClaimRecall } = require('./claim-recall');
+const { decideWorktreeClaim, ESCAPE_FLAG } = require('./worktree-claim-guard');
 // task 1003153 — the DEAD dependency edge, one definition shared with the route
 // and the detector. A lifecycle CLI may require the lifecycle module directly
 // (the documented exception in modules/lifecycle/CLAUDE.md).
@@ -81,6 +82,34 @@ function printDisciplineMode(task) {
   }
 }
 
+// task 1002579 — the I/O half of the worktree-per-claim guard. Probes the tree
+// with resolveWorktreeRoot (the same signal the context pack and skill-preflight
+// read, so there is one answer to "is this the main checkout") plus the current
+// branch, hands both to the pure decision, prints it, and exits 2 on a refusal.
+// Every probe failure degrades to isMainCheckout=null, which the decision treats
+// as allow — a guard that cannot see the tree must never block a real claim.
+function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
+  let tree = { isMainCheckout: null };
+  let branch = null;
+  try {
+    const runGit = (a) => execSync(`git ${a.join(' ')}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    tree = resolveWorktreeRoot({ runGit, cwd: process.cwd() });
+    branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']).trim() || null;
+  } catch (_) {
+    /* fail-open: an unclassifiable tree is allowed through */
+  }
+  const d = decideWorktreeClaim({
+    isMainCheckout: tree.isMainCheckout,
+    branch,
+    allowMainCheckout,
+    taskId,
+  });
+  if (d.verdict === 'allow') return;
+  for (const line of d.lines) console.error(line);
+  if (d.verdict === 'refuse') process.exit(2);
+  console.error('');
+}
+
 function captureHeadSha() {
   try {
     return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
@@ -423,13 +452,17 @@ async function runGoalJoinFlow({ api, d, taskId, assumeYes }) {
 }
 
 async function main() {
-  await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]');
+    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]');
     process.exit(2);
   }
+  // task 1002579: worktree-per-claim, enforced BEFORE anything happens — before
+  // the session check, before the POST. The whole point is that the builder
+  // learns at claim time, not from a stranded ship hours later.
+  enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
+  await requireSession();
   const wIdx = args.indexOf('--worktree');
   // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
   // parallel worktrees off one login each hold their own claim (the server guard

package/scripts/gds/worktree-claim-guard.js

@@ -0,0 +1,104 @@
+// scripts/gds/worktree-claim-guard.js — worktree-per-claim, enforced at CLAIM
+// time instead of discovered at ship time (task 1002579).
+//
+// THE FAILURE THIS KILLS. A builder with direct repo access runs
+// `git checkout -b task-N` in the PRIMARY worktree (the main checkout) rather
+// than in a dedicated `.claude/worktrees/<name>`. Everything looks fine for the
+// whole session — and then ship.js's local auto-merge finds the receiving tree
+// is the very tree holding the feature branch, so there is nowhere to merge
+// INTO. The ship bails with "the main checkout is on <branch>, not main"
+// (ship-merge.js) and the task strands at `confirmed` until the server
+// reconciler or /merge-mode catches it. The cause is at claim time; the symptom
+// was hours away at ship time.
+//
+// Worktree-per-claim has been the documented default since task 1642 and the
+// claim-time context pack has warned about it since task 1002573 — but both
+// speak AFTER the claim lands, and neither stops anything. Owner directive
+// (2026-08-05): make it the enforced project default for ALL builders.
+//
+// The whole decision is the pure function below so it can be unit-tested without
+// a git repo; claim.js supplies the two facts (which kind of tree, which branch)
+// from resolveWorktreeRoot() — the SAME probe the context pack and
+// skill-preflight already use, so there is one answer to "is this the main
+// checkout", not three that can disagree.
+
+'use strict';
+
+// The documented escape hatch. Named here so the refusal text and claim.js's
+// argv parse can never drift apart.
+const ESCAPE_FLAG = '--here';
+
+// Decide whether a claim may proceed in the tree it is being run from.
+//
+//   isMainCheckout  true | false | null   — null means "could not tell" (git
+//                                           unavailable / odd checkout)
+//   branch          the current branch name, or null when unknown
+//   defaultBranch   the branch the main checkout must stay parked on
+//   allowMainCheckout  the builder passed the escape hatch
+//   taskId          only used to spell the remedy commands concretely
+//
+// Returns { verdict: 'allow' | 'warn' | 'refuse', reason, lines }.
+// - 'allow'  — a linked worktree (the correct setup), or a tree we cannot
+//              classify. NEVER refuse on a guess: an unknown tree fails open,
+//              because a false refusal blocks real work and the ship-time bail
+//              still catches the real thing.
+// - 'refuse' — the main checkout, no escape hatch. Exit before the claim lands.
+// - 'warn'   — the main checkout WITH the escape hatch: the builder has said
+//              they mean it, so say loudly what it costs and continue.
+function decideWorktreeClaim({
+  isMainCheckout,
+  branch = null,
+  defaultBranch = 'main',
+  allowMainCheckout = false,
+  taskId = null,
+} = {}) {
+  if (isMainCheckout !== true) {
+    return { verdict: 'allow', reason: isMainCheckout === false ? 'linked worktree' : 'tree kind unknown', lines: [] };
+  }
+
+  // Two shapes of the same mistake, and the second is already broken: a main
+  // checkout parked OFF its default branch has ALREADY lost the merge target,
+  // so say that rather than warning about a future that has happened.
+  const parked = branch && branch !== defaultBranch && branch !== 'HEAD';
+  const headline = parked
+    ? `the main checkout is already parked on \`${branch}\`, not \`${defaultBranch}\``
+    : `you are in the main checkout (on \`${branch || defaultBranch}\`), not a per-claim worktree`;
+  const cost = parked
+    ? `The local auto-merge at ship time merges INTO this tree — while it holds \`${branch}\` there is nowhere to merge to, so the ship strands at \`confirmed\`.`
+    : `Branching here parks the main checkout off \`${defaultBranch}\`, and the local auto-merge at ship time then has nowhere to merge INTO: the ship strands at \`confirmed\` until the server reconciler (or /merge-mode) catches it.`;
+
+  const id = taskId == null ? '<task-id>' : String(taskId);
+  const remedy = [
+    '  Work this claim in its own worktree instead:',
+    `    node scripts/gds/worktree.js add ${id}`,
+    `    cd .claude/worktrees/task-${id}`,
+    `    node scripts/gds/claim.js ${id}`,
+  ];
+
+  if (allowMainCheckout) {
+    return {
+      verdict: 'warn',
+      reason: headline,
+      lines: [
+        `⚠ Claiming in the MAIN CHECKOUT (${ESCAPE_FLAG} given) — ${headline}.`,
+        `  ${cost}`,
+        '  Automation that resets this tree mid-session can also take your uncommitted work with it.',
+        ...remedy,
+      ],
+    };
+  }
+
+  return {
+    verdict: 'refuse',
+    reason: headline,
+    lines: [
+      `✗ Refusing to claim here — ${headline}.`,
+      `  ${cost}`,
+      '  Worktree-per-claim is the project default (task 1642); this is the check behind it.',
+      ...remedy,
+      `  If you genuinely mean to work in the main checkout, re-run with ${ESCAPE_FLAG} (you will land at \`confirmed\` and finish through /merge-mode).`,
+    ],
+  };
+}
+
+module.exports = { decideWorktreeClaim, ESCAPE_FLAG };

package/scripts/hall-preview/README.md

@@ -21,11 +21,43 @@ node scripts/hall-preview/server.js                 # neutral pack, port 4600
 | `--brand config/branding.json` | serve the instance pack (default: `config/branding.neutral.json`, the vanilla skin) |
 | `--modules-off dev-box,provisioning` | report those modules disabled in `window.__MODULES__` — verifies `moduleOn()` gating (Harbor nav item, Instances/Start-a-project widgets must vanish) |
 | `--empty` | drain every array in every fixture — the empty-state screenshot pass |
+| `--fixture-me` | don't read your own account live — serve the checked-in `me.json` snapshot (see below) |
 
 Writes are not wired: any `POST/PATCH/DELETE` answers `501 preview_readonly`.
 A GET with no fixture answers 404 and logs
 `no fixture: <path>` — that log line names the exact file to add.
 
+## The account is yours (task 1003315)
+
+The fixtures are one particular builder's snapshot, so the harness used to greet
+everyone as that builder — their name, credits, achievements, goals and **rank**.
+A metic snapshot also sealed the Archon-gated pages, so a UI change to Watch /
+Harbor / Gate / Permissions could not be reviewed at all.
+
+So at boot the harness reads **your** account: if this machine holds a GDS CLI
+session, the me-scoped endpoints (`/me`, `/me/*`, `/builders/<you>/…`,
+`/analytics/builder/<you>`, `/inbox/by-builder/<you>`, `/inbox/awaiting-nod`) are
+fetched live — read-only GETs — and layered over the fixtures in memory. The boot
+banner names whose hall you are looking at:
+
+```
+  account: @scootermack (archon) — your own, live
+```
+
+Nothing is written to `fixtures/` (that's `refresh-fixtures.js`'s job), so the
+checked-in snapshot stays the fallback. It serves whenever the live read can't
+happen — signed out, expired session, offline, or an endpoint your rank can't
+call (that one keeps its own fixture and the rest of your identity still lands).
+Every fallback says why, and says the hall is about to show you someone else:
+
+```
+  account: @jaxri (metic) — NOT YOURS, the checked-in fixture: this machine has no Bongos CLI session — run /builder-setup
+```
+
+**`--fixture-me` pins the snapshot.** Use it for the screenshot matrix below —
+a live account makes the images vary run to run — and to review the signed-out
+fallback deliberately. `--rank <rank>` still overrides whichever `/me` is served.
+
 ## Fixtures
 
 `fixtures/<path>.json`, slashes as `__` (`/me/recent-ships` → `me__recent-ships.json`).
@@ -46,7 +78,8 @@ Box/terminal endpoints are deliberately never snapshotted (connection details).
 
 Screenshot every changed page at **{light, dark} × {1280w, 390w}**, plus one
 instance-pack run (`--brand config/branding.json`) proving the theming contract
-survives. With the Playwright MCP (`npx playwright install chrome` once):
+survives. Run the harness with **`--fixture-me`** for these — the pinned snapshot
+is what makes two runs comparable. With the Playwright MCP (`npx playwright install chrome` once):
 
 1. `browser_navigate` → the page. `browser_console_messages` must show **0 errors**.
 2. 1280w: `browser_resize 1280×900` → `browser_take_screenshot` (fullPage for tall pages).

package/scripts/hall-preview/live-identity.js

@@ -0,0 +1,121 @@
+'use strict';
+// scripts/hall-preview/live-identity.js — serve the SIGNED-IN builder's own
+// account in the hall preview harness (task 1003315).
+//
+// The harness answers every read from checked-in fixtures, and fixtures/me.json
+// is one particular builder's snapshot. So every preview greeted whoever ran it
+// as somebody else ("Welcome back, Jackson Rini"), with that builder's credits,
+// achievements, goals and RANK — and because that snapshot is a metic, the
+// Archon-gated pages rendered their sealed notice, so a UI change to them could
+// not be reviewed at all. Reviewing your own UI change against someone else's
+// account is the bug.
+//
+// The fix: at boot, when the machine has a GDS CLI session, the me-scoped reads
+// are fetched LIVE (read-only GETs) and held in memory as overrides layered on
+// top of the fixtures. Nothing is ever written to fixtures/ — the checked-in
+// snapshot stays the signed-out fallback and the deterministic pass for the
+// screenshot matrix (`--fixture-me` pins it).
+//
+// Every dependency is injected, so this file is testable with no disk, no
+// network and no session (tests/hall_preview_identity.mjs).
+
+// The me-scoped reads — everything the hall renders as "you". ':id' expands to
+// the signed-in builder's id. Box/terminal endpoints are deliberately absent,
+// the same rule refresh-fixtures.js follows: they carry connection details.
+const ME_SCOPED_PATHS = [
+  'me',
+  'me/recent-ships?limit=30',
+  'me/cross-project',
+  'me/profile-nudge',
+  'me/render',
+  'me/wandering',
+  'me/skill-prefs',
+  'me/sound-prefs',
+  'me/event-sound-prefs',
+  'me/art-key/own',
+  'builders/:id/profile',
+  'builders/:id/active-claims',
+  'builders/:id/activity?section=tasks',
+  'builders/:id/activity?section=goals',
+  'analytics/builder/:id?days=90',
+  'inbox/by-builder/:id',
+  // Permission-gated (idea.triage, Metic+), so whether this queue exists at all
+  // is a fact about YOUR rank — the needs-attention inbox renders it or not.
+  'inbox/awaiting-nod?limit=20',
+];
+
+// The key an override is stored under, and the key a request looks itself up
+// by. The api path alone — EXCEPT where ?section= picks the row shape rather
+// than the path (the profile's activity log), which is the same discrimination
+// the harness's FIXTURE_FALLBACKS already makes for that one endpoint.
+function overrideKey(apiPath, query = {}) {
+  const p = String(apiPath || '').replace(/\/$/, '');
+  return query && query.section ? `${p}?section=${query.section}` : p;
+}
+
+// A ':id' template → the concrete request path plus the key it lands under.
+function expandPath(template, id) {
+  const [rawPath, search = ''] = String(template).split('?');
+  const p = rawPath.replace(':id', encodeURIComponent(String(id)));
+  const query = Object.fromEntries(new URLSearchParams(search));
+  return { key: overrideKey(p, query), url: search ? `${p}?${search}` : p };
+}
+
+// Why we fell back, in the builder's words rather than an HTTP status — this
+// line is printed in the boot banner and is the only signal that the hall is
+// about to greet them as someone else.
+function fallbackReason(status) {
+  if (status === 401 || status === 403) return 'your CLI session is no longer valid — run /builder-reauth';
+  return `the instance answered GET /me with ${status}`;
+}
+
+// resolveLiveIdentity — fetch the caller's own me-scoped reads, or explain why
+// not. NEVER throws and never exits: a preview harness that dies because the
+// laptop is offline is worse than one showing fixture data, so every failure
+// path degrades to { ok: false, why } and the fixtures keep serving.
+async function resolveLiveIdentity({
+  session,
+  fetchImpl = globalThis.fetch,
+  apiPrefix = '/api/bongos/v1',
+  timeoutMs = 8000,
+} = {}) {
+  if (!session || !session.token) {
+    return { ok: false, why: 'this machine has no Bongos CLI session — run /builder-setup' };
+  }
+  const base = String(session.apiBase || '').replace(/\/+$/, '');
+  if (!base) return { ok: false, why: 'the CLI session names no instance to read from' };
+
+  const get = async (url) => {
+    try {
+      const res = await fetchImpl(`${base}${apiPrefix}/${url}`, {
+        headers: { authorization: `Bearer ${session.token}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!res.ok) return { ok: false, status: res.status };
+      return { ok: true, data: await res.json() };
+    } catch (e) {
+      return { ok: false, status: 0, error: e && e.message };
+    }
+  };
+
+  const me = await get('me');
+  if (!me.ok) return { ok: false, why: me.status ? fallbackReason(me.status) : `could not reach ${base} (${me.error || 'network error'})` };
+  const builder = me.data && me.data.builder;
+  if (!builder || !builder.id) return { ok: false, why: 'the instance returned no builder on GET /me' };
+
+  const overrides = new Map([['me', me.data]]);
+  const skipped = [];
+  const rest = ME_SCOPED_PATHS.filter((t) => t !== 'me').map((t) => expandPath(t, builder.id));
+  const results = await Promise.all(rest.map(({ url }) => get(url)));
+  rest.forEach(({ key }, i) => {
+    // A read this builder's rank can't make (or one this instance doesn't
+    // serve) simply keeps its fixture — a partial identity still shows YOUR
+    // name, rank and credits, which is the whole point.
+    if (results[i].ok) overrides.set(key, results[i].data);
+    else skipped.push(key);
+  });
+
+  return { ok: true, builder, base, overrides, skipped };
+}
+
+module.exports = { ME_SCOPED_PATHS, overrideKey, expandPath, fallbackReason, resolveLiveIdentity };

package/scripts/hall-preview/refresh-fixtures.js

@@ -24,6 +24,7 @@ const SNAPSHOTS = [
   ['versions', 'versions'],
   ['leaderboard', 'leaderboard'],
   ['inbox', 'inbox', trimList('ideas', 25)],
+  ['inbox/awaiting-nod?limit=20', 'inbox__awaiting-nod', trimList('awaiting', 25)],
   ['goals', 'goals'],
   ['goals/inbox', 'goals__inbox'],
   // goal details: a handful of REAL ids (exact-match fixtures) + goal 25

package/scripts/hall-preview/server.js

@@ -19,8 +19,16 @@
 //                  window.__MODULES__ (verifies moduleOn() gating)
 //   --empty        serve every fixture with its arrays emptied — the
 //                  empty-state screenshot pass
-//   --rank archon  override the /me fixture's builder.rank so the Archon-gated
-//                  pages (watch, harbor, gate) render their content in preview
+//   --rank archon  override the served /me builder.rank (live or fixture) so the
+//                  Archon-gated pages (watch, harbor, gate) render in preview
+//   --fixture-me   do NOT read your own account live; serve the checked-in
+//                  fixtures/me.json snapshot (deterministic screenshot passes,
+//                  and the offline/signed-out path) — task 1003315
+//
+// The account is YOURS: when this machine holds a GDS CLI session the me-scoped
+// reads are fetched live at boot and layered over the fixtures, so the hall
+// greets the builder previewing the change rather than whoever's snapshot is
+// checked in (task 1003315). Signed out, offline, or --fixture-me → fixtures.
 //
 // Browse http://builders.localhost:<port>/ — Chromium resolves *.localhost,
 // and the `builders.` host prefix exercises the real subdomain serving path.
@@ -41,9 +49,11 @@ function arg(name) {
 }
 const PORT = Number(arg('--port')) || 4600;
 const EMPTY = process.argv.includes('--empty');
-// --rank: view the hall as a different rank — the /me fixture's builder.rank is
+// --rank: view the hall as a different rank — the served /me builder.rank is
 // overridden in the response, so the Archon-gated pages (watch, harbor, gate)
-// render their real content instead of the sealed notice. Preview-only theatre:
+// render their real content instead of the sealed notice. Since task 1003315 the
+// served /me is normally your OWN account, so this is now only needed to view
+// the hall as a rank you are not. Preview-only theatre:
 // the real pages are server-gated (requireGovernmentPage / ADR 0016).
 const RANK_OVERRIDE = arg('--rank');
 const MODULES_OFF = String(arg('--modules-off') || '').split(',').map((s) => s.trim()).filter(Boolean);
@@ -51,6 +61,10 @@ const MODULES_OFF = String(arg('--modules-off') || '').split(',').map((s) => s.t
 // often lacks prod's instance modules (provisioning, dev-box), and their
 // widgets can't be reviewed without it (task 2169).
 const MODULES_ON = String(arg('--modules-on') || '').split(',').map((s) => s.trim()).filter(Boolean);
+// --fixture-me: pin the checked-in /me snapshot instead of reading the caller's
+// own account live. The screenshot matrix in the README wants a stable subject,
+// and it is the explicit way to preview the signed-out fallback (task 1003315).
+const FIXTURE_ME = process.argv.includes('--fixture-me');
 const BRAND_FILE = arg('--brand') || 'config/branding.neutral.json';
 process.env.GDS_BRANDING_FILE = path.resolve(ROOT, BRAND_FILE);
 
@@ -65,6 +79,21 @@ catch (_) { express = require('express'); }
 const { buildStampedHtml } = require(path.join(ROOT, 'src', 'asset-version.js'));
 const { injectBrandingGlobal, mountInternalSurfaces } = require(path.join(ROOT, 'src', 'bongos', 'serve-internal.js'));
 const { clientModules } = require(path.join(ROOT, 'src', 'modules.js'));
+const { overrideKey, resolveLiveIdentity } = require('./live-identity');
+
+// The session is the ONE thing this harness reads from outside its own tree, and
+// it reads it through the FAIL-OPEN helper on purpose: apiCall/cliClient exit the
+// process on a 401, which would kill a preview over a cosmetic feature.
+function readSession() {
+  try { return require(path.join(ROOT, 'scripts', 'gds', 'cli-lib')).readSessionToken(); }
+  catch (_) { return null; }
+}
+
+// Live me-scoped payloads, keyed by overrideKey(); empty until boot resolves
+// them, and empty forever when signed out / offline / --fixture-me.
+let liveOverrides = new Map();
+let liveBuilder = null;
+let liveWhy = null;
 
 // ---- fixtures ---------------------------------------------------------------
 // File naming: the API path with slashes as "__" — /me/recent-ships →
@@ -151,7 +180,11 @@ app.use((req, res, next) => {
   if (req.method !== 'GET') {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }
-  const fix = fixtureFor(apiPath, req.query || {});
+  // Your own account wins over the checked-in snapshot; a me-scoped read that
+  // wasn't resolved live falls through to its fixture exactly as before.
+  const q = req.query || {};
+  const live = liveOverrides.get(overrideKey(apiPath, q)) ?? liveOverrides.get(apiPath);
+  const fix = live !== undefined ? live : fixtureFor(apiPath, q);
   if (fix === undefined) {
     console.log(`  no fixture: ${apiPath}  (add scripts/hall-preview/fixtures/${apiPath.replace(/\//g, '__')}.json)`);
     return res.status(404).json({ error: { code: 'no_fixture', message: apiPath } });
@@ -197,10 +230,41 @@ app.get(/^\/([a-z-]+)$/, (req, res, next) => {
 // the page routes we already served.
 mountInternalSurfaces(app);
 
+// Whose hall this is, said plainly in the banner. When it is NOT yours, that is
+// the line that says so — the old harness printed nothing and the substitution
+// was only visible as a stranger's name on the page (task 1003315).
+function accountLine() {
+  if (liveBuilder) {
+    const who = liveBuilder.github_login ? `@${liveBuilder.github_login}` : liveBuilder.display_name;
+    return `  account: ${who} (${liveBuilder.rank}) — your own, live${RANK_OVERRIDE ? ` [rank forced to ${RANK_OVERRIDE}]` : ''}`;
+  }
+  const why = FIXTURE_ME ? '--fixture-me' : liveWhy;
+  // A published core carves fixtures/ out (publish-manifest.js) — there the
+  // fallback is not "someone else's account", it is NO account, and the hall
+  // will 404 its way through /me. Say which of the two this is.
+  const snap = (loadFixture('me') || {}).builder;
+  if (!snap) return `  account: NONE — no live read (${why}) and this checkout ships no me fixture`;
+  const who = snap.github_login ? `@${snap.github_login}` : (snap.display_name || 'a checked-in snapshot');
+  return `  account: ${who} (${RANK_OVERRIDE || snap.rank}) — NOT YOURS, the checked-in fixture: ${why}`;
+}
+
 // Loopback only — this is a pre-auth preview of hall pages with fixture data;
 // *.localhost resolves to 127.0.0.1 so nothing else is needed.
-app.listen(PORT, '127.0.0.1', () => {
-  console.log(`hall-preview: http://builders.localhost:${PORT}/`);
-  console.log(`  brand: ${BRAND_FILE}${EMPTY ? '  (EMPTY fixtures)' : ''}${MODULES_OFF.length ? `  modules off: ${MODULES_OFF.join(',')}` : ''}`);
-  console.log('  pages:', Object.keys(stamped).map((f) => f.replace(/\.html$/, '')).sort().join(' '));
-});
+(async () => {
+  if (!FIXTURE_ME) {
+    const res = await resolveLiveIdentity({ session: readSession() });
+    if (res.ok) {
+      liveOverrides = res.overrides;
+      liveBuilder = res.builder;
+      if (res.skipped.length) console.log(`  (kept fixtures for: ${res.skipped.join(', ')})`);
+    } else {
+      liveWhy = res.why;
+    }
+  }
+  app.listen(PORT, '127.0.0.1', () => {
+    console.log(`hall-preview: http://builders.localhost:${PORT}/`);
+    console.log(accountLine());
+    console.log(`  brand: ${BRAND_FILE}${EMPTY ? '  (EMPTY fixtures)' : ''}${MODULES_OFF.length ? `  modules off: ${MODULES_OFF.join(',')}` : ''}`);
+    console.log('  pages:', Object.keys(stamped).map((f) => f.replace(/\.html$/, '')).sort().join(' '));
+  });
+})();

package/src/module-api.js

@@ -1218,8 +1218,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.387 with no explicit bump. run 33125589814. (task 1002620)
 //   1.19.389 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.388 with no explicit bump. run 33126279278. (task 1002620)
+//   1.19.390 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.389 with no explicit bump. run 33133575931. (task 1002620)
+//   1.19.391 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.390 with no explicit bump. run 33134514193. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.389'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.391'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/hall_preview_identity.mjs

@@ -0,0 +1,163 @@
+// tests/hall_preview_identity.mjs — hermetic unit test for the hall preview
+// harness's live-identity layer (task 1003315: the preview greeted every
+// builder as whoever's snapshot was checked into fixtures/me.json).
+//
+// NO disk, NO network, NO session: the session object and fetch are injected.
+//
+// Run:  node tests/hall_preview_identity.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const lib = require('../scripts/hall-preview/live-identity.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+const SESSION = { token: 'tok', apiBase: 'https://example.test' };
+const ME = { builder: { id: '1000094', github_login: 'scootermack', rank: 'archon' } };
+
+// A fetch stub: routes are keyed by the api path after /api/bongos/v1/. A number
+// means "answer that status"; a missing key means 404.
+function stubFetch(routes, { record } = {}) {
+  return async (url) => {
+    const p = String(url).split('/api/bongos/v1/')[1];
+    if (record) record.push(p);
+    const hit = Object.prototype.hasOwnProperty.call(routes, p) ? routes[p] : undefined;
+    if (hit === undefined) return { ok: false, status: 404, json: async () => ({}) };
+    if (typeof hit === 'number') return { ok: false, status: hit, json: async () => ({}) };
+    return { ok: true, status: 200, json: async () => hit };
+  };
+}
+const allOk = (extra = {}) => stubFetch(Object.assign({ me: ME }, extra));
+
+// ---------- key derivation ----------
+t('overrideKey: the path alone, except where ?section= picks the row shape', () => {
+  assert.equal(lib.overrideKey('me'), 'me');
+  assert.equal(lib.overrideKey('me/'), 'me', 'a trailing slash is the same key');
+  assert.equal(lib.overrideKey('builders/7/activity', { section: 'goals' }), 'builders/7/activity?section=goals');
+  assert.equal(lib.overrideKey('builders/7/activity', { limit: '20' }), 'builders/7/activity',
+    'a query that is NOT ?section= does not fork the key');
+});
+
+t('expandPath: :id expands, and the key drops the non-discriminating query', () => {
+  assert.deepEqual(lib.expandPath('builders/:id/profile', '1000094'),
+    { key: 'builders/1000094/profile', url: 'builders/1000094/profile' });
+  assert.deepEqual(lib.expandPath('me/recent-ships?limit=30', '1'),
+    { key: 'me/recent-ships', url: 'me/recent-ships?limit=30' },
+    'limit is a fetch detail, not part of the key the harness looks up');
+  assert.deepEqual(lib.expandPath('builders/:id/activity?section=goals', '9'),
+    { key: 'builders/9/activity?section=goals', url: 'builders/9/activity?section=goals' });
+});
+
+t('ME_SCOPED_PATHS: /me leads, and no box/terminal read is snapshotted', () => {
+  assert.equal(lib.ME_SCOPED_PATHS[0], 'me');
+  const box = lib.ME_SCOPED_PATHS.filter((p) => /(^|\/)box(\/|$)|terminal/.test(p));
+  assert.deepEqual(box, [], 'box endpoints carry connection details and are never fetched here');
+});
+
+// ---------- the fail-open paths (a preview must never die over this) ----------
+await ta('no session: falls back, and never touches the network', async () => {
+  let called = 0;
+  const res = await lib.resolveLiveIdentity({ session: null, fetchImpl: async () => { called += 1; } });
+  assert.equal(res.ok, false);
+  assert.equal(called, 0);
+  assert.match(res.why, /builder-setup/);
+});
+
+await ta('a session with no apiBase: falls back rather than fetching a bare path', async () => {
+  const res = await lib.resolveLiveIdentity({
+    session: { token: 'tok' },
+    fetchImpl: async () => { throw new Error('should not fetch'); },
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.why, /names no instance/);
+});
+
+await ta('401: falls back with the reauth line, NOT an exit (cli-lib apiCall would exit)', async () => {
+  const res = await lib.resolveLiveIdentity({ session: SESSION, fetchImpl: stubFetch({ me: 401 }) });
+  assert.equal(res.ok, false);
+  assert.match(res.why, /builder-reauth/);
+});
+
+await ta('offline: falls back with the unreachable instance named', async () => {
+  const res = await lib.resolveLiveIdentity({
+    session: SESSION,
+    fetchImpl: async () => { throw new Error('ECONNREFUSED'); },
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.why, /example\.test/);
+  assert.match(res.why, /ECONNREFUSED/);
+});
+
+await ta('a /me with no builder: falls back (a half-identity is worse than the fixture)', async () => {
+  const res = await lib.resolveLiveIdentity({ session: SESSION, fetchImpl: stubFetch({ me: { builder: null } }) });
+  assert.equal(res.ok, false);
+  assert.match(res.why, /no builder/);
+});
+
+// ---------- the happy path ----------
+await ta('signed in: /me is YOUR account, keyed for the harness lookup', async () => {
+  const res = await lib.resolveLiveIdentity({ session: SESSION, fetchImpl: allOk() });
+  assert.equal(res.ok, true);
+  assert.equal(res.builder.github_login, 'scootermack');
+  assert.equal(res.builder.rank, 'archon', 'the RANK is what unseals the Archon-gated pages in preview');
+  assert.deepEqual(res.overrides.get('me'), ME);
+});
+
+await ta('id-bearing reads are fetched for YOUR id, never the fixture builder id', async () => {
+  const record = [];
+  const fetchImpl = stubFetch({ me: ME, 'builders/1000094/profile': { bio: 'mine' } }, { record });
+  const res = await lib.resolveLiveIdentity({ session: SESSION, fetchImpl });
+  assert.deepEqual(res.overrides.get('builders/1000094/profile'), { bio: 'mine' });
+  assert.ok(record.includes('builders/1000094/profile'));
+  assert.ok(!record.some((p) => p.includes('/95/')), 'never the checked-in fixture builder id');
+});
+
+await ta('the two activity sections land under DIFFERENT keys (row shapes differ)', async () => {
+  const fetchImpl = stubFetch({
+    me: ME,
+    'builders/1000094/activity?section=tasks': { rows: ['task'] },
+    'builders/1000094/activity?section=goals': { rows: ['goal'] },
+  });
+  const res = await lib.resolveLiveIdentity({ session: SESSION, fetchImpl });
+  assert.deepEqual(res.overrides.get('builders/1000094/activity?section=tasks'), { rows: ['task'] });
+  assert.deepEqual(res.overrides.get('builders/1000094/activity?section=goals'), { rows: ['goal'] });
+});
+
+await ta('a read this rank cannot make keeps its fixture; the rest still resolves', async () => {
+  const res = await lib.resolveLiveIdentity({
+    session: SESSION,
+    fetchImpl: stubFetch({ me: ME, 'inbox/awaiting-nod?limit=20': 403 }),
+  });
+  assert.equal(res.ok, true, 'a partial identity still shows YOUR name, rank and credits');
+  assert.ok(res.skipped.includes('inbox/awaiting-nod'), 'skipped, so the fixture serves it');
+  assert.equal(res.overrides.has('inbox/awaiting-nod'), false);
+});
+
+await ta('every request carries the session bearer, is a GET, and is time-boxed', async () => {
+  const seen = [];
+  const fetchImpl = async (url, init) => {
+    seen.push(init);
+    const p = String(url).split('/api/bongos/v1/')[1];
+    return { ok: p === 'me', status: p === 'me' ? 200 : 404, json: async () => ME };
+  };
+  await lib.resolveLiveIdentity({ session: SESSION, fetchImpl });
+  assert.ok(seen.length > 1);
+  for (const init of seen) {
+    assert.equal(init.headers.authorization, 'Bearer tok');
+    assert.equal(init.method, undefined, 'no method set means GET; the harness never writes');
+    assert.ok(init.signal, 'every read is time-boxed so boot cannot hang');
+  }
+});
+
+console.log(`\nhall_preview_identity: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/worktree_claim_guard.mjs

@@ -0,0 +1,105 @@
+// tests/worktree_claim_guard.mjs
+//
+// task 1002579 — worktree-per-claim, enforced at CLAIM time. The failure it
+// kills: branching in the PRIMARY worktree (the main checkout) instead of a
+// dedicated `.claude/worktrees/<name>` leaves the main checkout parked off
+// `main`, so ship.js's local auto-merge has nowhere to merge INTO and the task
+// strands at `confirmed` — a symptom hours away from its cause.
+//
+// decideWorktreeClaim() is the pure core; these tests pin every branch with
+// injected facts (no git, no repo, no claim).
+//
+// Run:  node tests/worktree_claim_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { decideWorktreeClaim, ESCAPE_FLAG } = require('../scripts/gds/worktree-claim-guard.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const text = (d) => d.lines.join('\n');
+
+// ---- the core case: the primary checkout, on main -------------------------
+t('REFUSE: the main checkout on `main` — the exact shape task 1642 documents', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  assert.equal(d.verdict, 'refuse');
+  assert.match(text(d), /main checkout/i);
+});
+
+t('REFUSE names the fix concretely, with the task id spelled into the commands', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  const s = text(d);
+  assert.match(s, /worktree\.js add 42/, 'names the worktree-create command');
+  assert.match(s, /cd \.claude\/worktrees\/task-42/, 'names where to go');
+  assert.match(s, /claim\.js 42/, 'names the re-run');
+});
+
+t('REFUSE names the escape hatch, so the refusal is never a dead end', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  assert.match(text(d), new RegExp(ESCAPE_FLAG.replace(/-/g, '\-')));
+});
+
+t('a missing task id still yields runnable-shaped guidance, not "undefined"', () => {
+  const s = text(decideWorktreeClaim({ isMainCheckout: true, branch: 'main' }));
+  assert.match(s, /worktree\.js add <task-id>/);
+  assert.doesNotMatch(s, /undefined|null/);
+});
+
+// ---- the already-broken shape: primary checkout parked off main -----------
+t('REFUSE: the main checkout ALREADY parked on a task branch reads as already-broken', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'task-99', taskId: 42 });
+  assert.equal(d.verdict, 'refuse');
+  const s = text(d);
+  assert.match(s, /already parked on `task-99`/, 'names the branch it is stuck on');
+  assert.match(s, /nowhere to merge/, 'names the ship-time consequence');
+});
+
+t('a detached HEAD in the main checkout is not reported as "parked on HEAD"', () => {
+  const s = text(decideWorktreeClaim({ isMainCheckout: true, branch: 'HEAD', taskId: 42 }));
+  assert.doesNotMatch(s, /parked on `HEAD`/);
+});
+
+t('defaultBranch is honoured — a `master` instance is not told main', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'master', defaultBranch: 'master', taskId: 7 });
+  assert.equal(d.verdict, 'refuse');
+  assert.doesNotMatch(text(d), /already parked/, 'master IS the default branch here');
+});
+
+// ---- the escape hatch: loud, but it proceeds ------------------------------
+t('WARN, not refuse, when the escape hatch is given — and it still costs something out loud', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', allowMainCheckout: true, taskId: 42 });
+  assert.equal(d.verdict, 'warn');
+  assert.match(text(d), /confirmed/, 'says what it will cost at ship time');
+  assert.match(text(d), /worktree\.js add 42/, 'still names the better path');
+});
+
+// ---- no false positives ---------------------------------------------------
+t('ALLOW: a real linked worktree is untouched — silently, no lines', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: false, branch: 'claude/task-42', taskId: 42 });
+  assert.equal(d.verdict, 'allow');
+  assert.deepEqual(d.lines, []);
+});
+
+t('ALLOW: a linked worktree that happens to be on `main` is still fine', () => {
+  assert.equal(decideWorktreeClaim({ isMainCheckout: false, branch: 'main' }).verdict, 'allow');
+});
+
+t('ALLOW: tree kind UNKNOWN fails open — a guard that cannot see must not block', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: null, branch: null, taskId: 42 });
+  assert.equal(d.verdict, 'allow');
+  assert.deepEqual(d.lines, []);
+});
+
+t('ALLOW: called with no facts at all (every probe threw) still fails open', () => {
+  assert.equal(decideWorktreeClaim().verdict, 'allow');
+});
+
+console.log(`\nworktree_claim_guard: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);