@bongos/core 1.19.390 → 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.390",
-  "core_contract": "1.19.390",
-  "source_commit": "fca78267668e7bfe1241ef5502900854cb91a59d",
+  "core_version": "1.19.391",
+  "core_contract": "1.19.391",
+  "source_commit": "340dd8cf2dc62375b464f1deb56fa203cb37e47a",
   "source_ref": "HEAD",
-  "built_at": "2026-08-28T01:40:58.750Z",
+  "built_at": "2026-08-28T01:59:37.546Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 339,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1622,
+    "functional_verbatim": 1624,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1983,
-  "tree_sha256": "cfb7d40bbbc5a242cfd992804860f21603eb1faa51af33d4dd6739464e971005",
+  "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": "6df325de41dee29b93290e06d42cba92acbc357b5475c2bbefa70c8f9d96df1b"
+      "sha256": "fa2614ac06762df93cebbd6d3b31ee9aa8610187156003199b894dedb875587c"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1f4bb5de0e76f44c4588ed68adc9731eb8aa0b5e22fd21d26b4f31880a655de0"
+      "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",
@@ -7112,7 +7117,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b0af1d77cee68628e7693a9beab490c3c66d9aa6ff091bc6da61fef4fe0f48a7"
+      "sha256": "b5e645e16766a357b39033daec49842b257e6ce4450718d2f4e76667e4c6f304"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9909,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.390",
+  "version": "1.19.391",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.390",
+      "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.390",
+  "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/src/module-api.js

@@ -1220,8 +1220,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.390'; // 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/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);