@bongos/core 1.19.629 → 1.19.630

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.629",
-  "core_contract": "1.19.629",
-  "source_commit": "80bf853bd558fa5134bd5bddcb0e4804579fc27e",
+  "core_version": "1.19.630",
+  "core_contract": "1.19.630",
+  "source_commit": "8ec5a34a79092057e64af1c4c3762d0b3901efb9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T22:26:18.376Z",
+  "built_at": "2026-09-09T23:03:56.905Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 466,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2098,
+    "functional_verbatim": 2099,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2588,
-  "tree_sha256": "c5bd187e5ed644428b20c65f6fee6c2b6b122ae4952a3e36e19b84cfa2e4d722",
+  "file_count": 2589,
+  "tree_sha256": "9937af1178174c35ad4b6fd94cc34d318d04bbc74ec18d9f469b0ba163740e05",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -397,7 +397,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "07caf5c1db2cfd16c92713891055b477982aef4dd847af67042b742293e6a9ce"
+      "sha256": "c109144665c545407dc0a56a8d08e77b277d7a1636ab3740d0e81e43c563f616"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1887,12 +1887,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "8adebe11d51d4bbce7e5acacc003ce923e820f0d8532541d3f5a74ed07570ce8"
+      "sha256": "72bfc066767c1c7301516d4f747c8a29725c2d623b5be1d916e6baa11e20a988"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "2059cb9b02d6a20e4b1297c866db9f717bb3514ec49ab2454c776c806775d3da"
+      "sha256": "ac3c10aa8cc2cdad0d6878a7b2c51bb668b5207a2cd9649ee87da871e190494e"
     },
     {
       "path": "docs/architecture.md",
@@ -2767,7 +2767,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "aba3d7e763196a3052a53ee81f5327e0caad5274bd4de41b09b031b2277c82d2"
+      "sha256": "d70ae49d22a6ae226ad46e3c8d5fbaa0954a8d14697cdb96760f42bc24be7ced"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2932,7 +2932,7 @@
     {
       "path": "docs/recipes/multi-builder-merge.md",
       "mode": "0000644",
-      "sha256": "0f7f91a22ab5b689ab733cac5615ace8068ef8f98c8ab7ef9bb61313c16a3122"
+      "sha256": "1770644d6a4ee631d505dbbe4e682f4b6134744746a828a1af503ecc8bb4f759"
     },
     {
       "path": "docs/recipes/ops-gotchas.md",
@@ -5592,7 +5592,7 @@
     {
       "path": "modules/lifecycle/db-claims.js",
       "mode": "0000644",
-      "sha256": "dbce7de39b91cdd1843ba26efc3f3be76690a7112aaa3b1b0406a9b9f98dfb32"
+      "sha256": "23ed6051b8b9283410f23e10862b6b65361cbf2f95489cd1fc50dfd4584f5c71"
     },
     {
       "path": "modules/lifecycle/db-deps-criteria.js",
@@ -5627,7 +5627,7 @@
     {
       "path": "modules/lifecycle/db-ship.js",
       "mode": "0000644",
-      "sha256": "e48d877a5951f02153c7384217421b2b04a3a1fed215b61ac41fc5b0b8355ded"
+      "sha256": "a7a3f24e8cc01953e09c19c9dcb8f4a5a58bdd31fe8cf0076dd7cbb102491cf2"
     },
     {
       "path": "modules/lifecycle/db-tasks.js",
@@ -5642,7 +5642,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "af6af95c05aa6cc76c0e49cb0a99bfb24685b3efb66df0f90883c3301baeede0"
+      "sha256": "95ff6bc6e9f4ad652dc2aa6bc2c7c520409a2115c714cb4ba867fc80413691e8"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5797,7 +5797,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "6bc32c6ae4029748d6099701f25fc17d5875b2ff005de5ad2cacbc023092c32c"
+      "sha256": "8a4f6d5513b97e84c44695b88e42c6e5bdc1875e97202be41caf6c739b2fa42e"
     },
     {
       "path": "modules/lifecycle/routes/closeness.js",
@@ -7697,12 +7697,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "41fdf5ef9ec5b4cb8a9f7a85f0efeba2595895fc5688c3c78702652fe4002d67"
+      "sha256": "8ce2c5dbcf03a0638065b823be4fd0bab26ed8695ba9693bc99b090ef6e0f237"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c8bb2a1526d2abc3ba1bcb859d83ca86a081fd7c89a178f45f5b39a481ecaebe"
+      "sha256": "94be508ef7535b26470470845f7631d438c0716cba55a09a5de676eb65ca2cad"
     },
     {
       "path": "public-docs/index.html",
@@ -7947,7 +7947,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "7c81b6c9e85aab5f230f72a4638402061fa516d7bb9fb7997b1151bef5b117e6"
+      "sha256": "d925dfa3831cb3bd16b2ff1761344bd4bedf7d916613fffd9dc5d9574244f525"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -7972,7 +7972,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "eaa4c3a172009d5ce825e528f5077a480e034658501a7d0c532a7807886beb9e"
+      "sha256": "c3f5d95c3e586ea711f4e0cef245da9f8106bf4c803aa4c7b2d0025657562680"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8822,7 +8822,7 @@
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "9cc28796753779cc054036bbaae841ff798d27c92ad98e37ff877662b3f063ce"
+      "sha256": "95b5fa325ea0407dd6cd3d9ae3a03a0a0f0478a0bfcf76d77cf36b13a7c36bea"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -8847,7 +8847,7 @@
     {
       "path": "scripts/gds/ship-io.js",
       "mode": "0000644",
-      "sha256": "d881d3de837a0d13f2fcaddac7aec17969e8c2d395db238fe9bf257a0925deff"
+      "sha256": "9db82555be2472f9bd6bdefdfb90411138e767fb7acd10f0d561152c1754426e"
     },
     {
       "path": "scripts/gds/ship-land.js",
@@ -9442,7 +9442,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "46df738e31dab69636774474ec6714365bf625a395df0a0e5ab4ecbacf178b16"
+      "sha256": "9f6fac692c0299219829477c40982314b29fc7fa1854a3544b6cc104ac97791a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10004,6 +10004,11 @@
       "mode": "0000644",
       "sha256": "d47a0f20617d3bf80cef4d24c816ffa53a045165cd83494a0c8d4c83b7ad16ef"
     },
+    {
+      "path": "tests/claim_resolve_worktree_lock.mjs",
+      "mode": "0000644",
+      "sha256": "6e5ff3acb835fd6219136ee2a5e144841076a82733915cc7111688f707464442"
+    },
     {
       "path": "tests/claims_bind_session.mjs",
       "mode": "0000644",

package/clients/bongos-client/index.d.ts

@@ -229,7 +229,7 @@ export interface PostClaimsBatchRequest { task_ids: unknown[]; worktree_name?: s
 export interface PostClaimsBatchResponse { claims: unknown }
 export interface PostClaimsBatchValidateRequest { task_ids: unknown[] }
 export interface PostClaimsIdReleaseOnBehalfRequest { reason: string }
-export interface PostClaimsIdResolveRequest { outcome: "shipped" | "abandoned" | "partial"; notes_md?: string; value_summary?: string; verification?: Record<string, unknown>; force?: boolean; committed_files?: string[]; sandbox_review?: Record<string, unknown> }
+export interface PostClaimsIdResolveRequest { outcome: "shipped" | "abandoned" | "partial"; notes_md?: string; value_summary?: string; verification?: Record<string, unknown>; force?: boolean; committed_files?: string[]; sandbox_review?: Record<string, unknown>; resolver_worktree?: string }
 export interface PostClaimsRequest { task_id: StringifiableId; worktree_name?: string; head_sha?: string; bind_session?: boolean; enforce_touches?: boolean }
 export interface PostClaimsResponse { claim: unknown; task: unknown; just_unlocked: unknown; overlap_warning: unknown; reward: unknown }
 export interface PostConnectionsIdAcceptResponse { status: unknown }

package/docs/api/openapi.json

@@ -19564,6 +19564,10 @@
           },
           "sandbox_review": {
             "type": "object"
+          },
+          "resolver_worktree": {
+            "type": "string",
+            "maxLength": 200
           }
         },
         "required": [

package/docs/api-reference.md

@@ -141,7 +141,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | POST | `/api/bongos/claims` | `any-builder` | `task_id`, `worktree_name`, `head_sha`, `bind_session`, `enforce_touches` | own work (claim a ready task); Xenos additionally filtered to newcomer_friendly rows inside db.claimTask (returns rank_too_low_for_task 4… |
 | POST | `/api/bongos/claims/:id/release-on-behalf` | `metic+archon` | `reason` | POST /claims/:id/release-on-behalf — V3.R14 (task 238). |
-| POST | `/api/bongos/claims/:id/resolve` | `any-builder` | `outcome`, `notes_md`, `value_summary`, `verification`, `force`, `committed_files`, `sandbox_review` | resolve own claim (ship/abandon); ownership checked in db.resolveClaim (NOT_YOUR_CLAIM). |
+| POST | `/api/bongos/claims/:id/resolve` | `any-builder` | `outcome`, `notes_md`, `value_summary`, `verification`, `force`, `committed_files`, `sandbox_review`, `resolver_worktree` | resolve own claim (ship/abandon); ownership checked in db.resolveClaim (NOT_YOUR_CLAIM). |
 | POST | `/api/bongos/claims/batch` | `any-builder` | `task_ids`, `worktree_name`, `bind_session` | Atomic multi-claim. |
 | POST | `/api/bongos/claims/batch/release` | `any-builder` | `claim_ids`, `force` | Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned'). |
 | POST | `/api/bongos/claims/batch/validate` | `any-builder` | `task_ids` | Dry-run validate (task 1758) — read-only twin of claimTasksBatch's pre-flight checks. |

package/docs/module-api-changelog.md

@@ -1707,5 +1707,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.627 with no explicit bump. run 34397967061. (task 1002620)
   1.19.629 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.628 with no explicit bump. run 34412159317. (task 1002620)
+  1.19.630 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.629 with no explicit bump. run 34415169250. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/multi-builder-merge.md

@@ -24,7 +24,7 @@ This recipe is the audit deliverable for [#269](https://example.com/builders#/ta
 |---|---|---|---|
 | **`main` worktree** (`REPO_ROOT`): checkout, `git fetch`, `git merge`, `git push origin main`, post-merge smoke, `~/deploy.sh` | **Yes — the single hot resource.** One checkout, one HEAD. | **`merge-lock` mutex** (`.git/otb-automerge.lock`) — held by `ship.js` auto-merge AND `/merge-mode`. | This is the surface [#269](https://example.com/builders#/task/269) closes end-to-end. |
 | **`claims` table** (claim/release) | Yes | Postgres txn + `uniq_active_claim_per_task` unique index + touches-overlap check (`db.js claimTask`) | Deterministic. `ALREADY_CLAIMED` / `TOUCHES_CONFLICT` are clean refusals, not corruption. |
-| **`creator_session_id` on claims** | Yes | `CLAIM_SESSION_MISMATCH` (migration 013) | Only the session that created a claim may ship/release it — prevents cross-session interference. |
+| **The claim's working tree** (`worktree_name`, falling back to `creator_session_id`) | Yes | `CLAIM_SESSION_MISMATCH` (migration 013; re-keyed to the tree by task 1003767, following the same fix to the claim-side guard in task 1002570) | Only the WORKING TREE that created a claim may ship/release it — a ship publishes the whole branch a tree owns, so resolving from elsewhere would land the wrong commits. Keyed on the tree, **not** the auth session: one login is shared by every concurrent worktree and is re-issued by `/builder-reauth`, which used to strand the claim outright. Where no tree is named on either side (a plain clone, or an older CLI sending no `resolver_worktree`) the historical session compare still applies. `force` remains the override. |
 | **`worktree_name` uniqueness** | Yes | Server-side disambiguation in `claimTask` (V3.R51 / [#270](https://example.com/builders#/task/270)) | Two claims with the same worktree name → second gets a suffix. |
 | **`migration_counter`** (migration number allocation) | Yes | `UPDATE … RETURNING` inside the claim txn | Atomic; each claim that signals `migrations/` gets a distinct number. |
 | **Feature worktree** (`.claude/worktrees/<name>`) | No — per-builder | n/a | Each builder's feature branch work is isolated. The collision only appears at merge time, on `main`. |

package/modules/lifecycle/db-claims.js

@@ -20,7 +20,7 @@ const { goalMembershipFailures } = require('./claim-feed.js');
 const { unsatisfiedDeps } = require('./db-deps-criteria.js');
 const { claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName, rankAllowsTask, xenosClaimAllowed } = require('./db-rank-authz.js');
 const { sealSessionLog } = require('./db-shared.js');
-const { needsRebaseTasksForBuilder } = require('./db-ship.js');
+const { needsRebaseTasksForBuilder, shouldRefuseClaimResolve } = require('./db-ship.js');
 const { REWARD_SUGGESTION_CAP, rewardGateAssignment } = require('./db-tasks.js');
 
 // -------------------------------------------------------------------------
@@ -725,7 +725,7 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
 // still releases. Mirrors resolveClaim's per-claim effects (released_at +
 // outcome, task → 'ready', sealSessionLog, actual_minutes recompute) and
 // releaseClaimOnBehalf's row-locked batch-read shape.
-async function releaseClaimsBatch({ claimIds, builderId, resolverSessionId, force }) {
+async function releaseClaimsBatch({ claimIds, builderId, resolverSessionId, resolverWorktree = null, force }) {
   if (!Array.isArray(claimIds) || claimIds.length === 0) {
     throw { code: 'BATCH_EMPTY' };
   }
@@ -752,8 +752,19 @@ async function releaseClaimsBatch({ claimIds, builderId, resolverSessionId, forc
       if (!claim) { failures.push({ claim_id: claimId, reason: 'CLAIM_NOT_FOUND' }); continue; }
       if (claim.builder_id !== builderId) { failures.push({ claim_id: claimId, reason: 'NOT_YOUR_CLAIM' }); continue; }
       if (claim.released_at) { failures.push({ claim_id: claimId, reason: 'ALREADY_RESOLVED' }); continue; }
-      if (!force && claim.creator_session_id && resolverSessionId &&
-          claim.creator_session_id !== resolverSessionId) {
+      // task 1003767: the SAME decision resolveClaim uses, not a third copy of
+      // the auth-session compare (this was the second of three). Batch release
+      // has no CLI caller passing a tree yet, so resolverWorktree is normally
+      // null here and the decision falls back to the session compare — today's
+      // behaviour exactly. Wired anyway so a re-auth cannot strand a batch
+      // release the moment a caller does send one.
+      if (shouldRefuseClaimResolve({
+        claimSessionId: claim.creator_session_id,
+        resolverSessionId,
+        claimWorktree: claim.worktree_name,
+        resolverWorktree,
+        force,
+      }).refuse) {
         failures.push({ claim_id: claimId, reason: 'CLAIM_SESSION_MISMATCH', claimWorktree: claim.worktree_name ?? null });
         continue;
       }

package/modules/lifecycle/db-ship.js

@@ -15,9 +15,75 @@ const { pool, withTx, insertAuditLog } = api;
 const log = api.logger('lifecycle');
 const seams = api;
 const doneWhen = require('./done-when.js');
-const { THETES_GRADUATION_THRESHOLD, maybeAutoGraduateToThetes } = require('./db-rank-authz.js');
+const { THETES_GRADUATION_THRESHOLD, maybeAutoGraduateToThetes, foldWorktreeName } = require('./db-rank-authz.js');
 const { mostRecentClaimHolderId, sealSessionLog, staleClaimHourPredicate } = require('./db-shared.js');
 
+// shouldRefuseClaimResolve — may THIS caller resolve THIS claim? (task 1003767)
+//
+// The guard exists to catch a builder shipping the wrong claim from the wrong
+// place: /builder-ship publishes the whole branch a working tree owns, so a
+// resolve arriving from a different tree than the one that did the work lands
+// somebody else's commits. The route has always described it that way ("catches a
+// builder accidentally shipping from the wrong worktree", routes/claims.js).
+//
+// But it was IMPLEMENTED as `creator_session_id !== resolverSessionId`, and that
+// is the AUTH-TOKEN session — one login shared by every concurrent worktree, and
+// re-issued whenever the builder runs /builder-reauth. So re-authing mid-claim
+// made the builder's own claim permanently unresolvable (CLAIM_SESSION_MISMATCH
+// on every ship, with `release --force` — forfeiting graded work — the only exit).
+// A standing "don't run /builder-reauth while holding a claim" warning in the
+// project handoff was the symptom.
+//
+// This is the SAME confusion shouldRefuseSessionClaim (routes/claims.js) was
+// already fixed for; its comment states the rule: "The hazard boundary is the
+// WORKING TREE (one worktree = one branch = one HEAD), NOT the auth session."
+// This is that rule applied to the resolve side.
+//
+// Worktree wins WHERE KNOWN, session is the fallback. When both sides name a
+// tree, that comparison is the whole decision — a re-auth changes the session and
+// is correctly ignored, while a resolve from a genuinely different tree is still
+// refused (the hazard is real, not the guard). When either side does NOT name one
+// — an older CLI that sends no worktree, or a claim made from a plain clone — the
+// tree cannot be compared, so we fall back to the historical session check rather
+// than waving the resolve through. Refusing on the best signal available keeps
+// this a tightening-only change: nothing that was refused before is now allowed
+// except the re-auth case this task exists to fix.
+//
+// Existing skips are unchanged: force=true (the emergency hatch), a claim with no
+// creator_session_id (a web/unbound claim per #616, or one pre-dating the column),
+// and a resolver with no session context at all.
+//
+// Pure + exported so the decision is unit-testable with no DB and no route —
+// the same shape as shouldRefuseSessionClaim. Returns { refuse, reason }.
+function shouldRefuseClaimResolve({
+  claimSessionId,
+  resolverSessionId,
+  claimWorktree = null,
+  resolverWorktree = null,
+  force = false,
+} = {}) {
+  const allow = { refuse: false, reason: null };
+  if (force) return allow;
+  // Nothing to scope to: an unbound/web claim is adoptable by any of the
+  // builder's own sessions, and a session-less resolver predates the check.
+  if (!claimSessionId || !resolverSessionId) return allow;
+
+  // Fold through the SAME normalization every worktree_name ingest point uses,
+  // so '' / '   ' / null all mean "no worktree" here exactly as they do in the
+  // DB index and in shouldRefuseSessionClaim (task 1002522).
+  const claimTree = foldWorktreeName(claimWorktree);
+  const resolverTree = foldWorktreeName(resolverWorktree);
+
+  // Both sides named a working tree → that IS the hazard boundary. Decide on it
+  // alone and ignore the session, which is what makes a re-auth survivable.
+  if (claimTree && resolverTree) {
+    return claimTree === resolverTree ? allow : { refuse: true, reason: 'worktree_mismatch' };
+  }
+
+  // Tree unknown on at least one side → fall back to the session compare.
+  return claimSessionId === resolverSessionId ? allow : { refuse: true, reason: 'session_mismatch' };
+}
+
 // Resolve a claim. Three-state task lifecycle:
 //   active → completed         (builder declared done; awaiting grader)
 //   active → completed → confirmed   (promoted by applyGrade when the subagent
@@ -39,7 +105,7 @@ const { mostRecentClaimHolderId, sealSessionLog, staleClaimHourPredicate } = req
 // at resolveClaim time. Both keys stay in the response shape so existing
 // callers (ship.js) don't break.
 
-async function resolveClaim({ claimId, builderId, outcome, notesMd, valueSummary, verification, resolverSessionId, force, committedFiles = null, sandboxReview = null }) {
+async function resolveClaim({ claimId, builderId, outcome, notesMd, valueSummary, verification, resolverSessionId, resolverWorktree = null, force, committedFiles = null, sandboxReview = null }) {
   return withTx(async (client) => {
     const { rows: claimRows } = await client.query(
       `SELECT c.id, c.task_id, c.builder_id, c.released_at, c.claimed_at,
@@ -53,13 +119,25 @@ async function resolveClaim({ claimId, builderId, outcome, notesMd, valueSummary
     const claim = claimRows[0];
     if (claim.builder_id !== builderId) throw { code: 'NOT_YOUR_CLAIM' };
     if (claim.released_at) throw { code: 'ALREADY_RESOLVED' };
-    // Session lock: only the session that created this claim can resolve it.
-    // Skipped when force=true (emergency), when the claim pre-dates this
-    // migration (creator_session_id IS NULL), or when the resolver has no
-    // session context (legacy path). This closes the cross-session release hole.
-    if (!force && claim.creator_session_id && resolverSessionId &&
-        claim.creator_session_id !== resolverSessionId) {
-      throw { code: 'CLAIM_SESSION_MISMATCH', claimWorktree: claim.worktree_name ?? null };
+    // Resolve lock: only the WORKING TREE that created this claim can resolve it
+    // (task 1003767) — falling back to the creating session where no tree is
+    // named. See shouldRefuseClaimResolve above for why the tree, not the auth
+    // session, is the hazard boundary. Skips: force=true, an unbound/web claim,
+    // or a resolver with no session context. `reason` distinguishes the two
+    // refusal shapes so the CLI can say which one happened.
+    const resolveLock = shouldRefuseClaimResolve({
+      claimSessionId: claim.creator_session_id,
+      resolverSessionId,
+      claimWorktree: claim.worktree_name,
+      resolverWorktree,
+      force,
+    });
+    if (resolveLock.refuse) {
+      throw {
+        code: 'CLAIM_SESSION_MISMATCH',
+        reason: resolveLock.reason,
+        claimWorktree: claim.worktree_name ?? null,
+      };
     }
 
     await client.query(
@@ -1149,4 +1227,5 @@ module.exports = {
   restoreTask,
   setClaimPublishedSha,
   shipTask,
+  shouldRefuseClaimResolve,
 };

package/modules/lifecycle/db.js

@@ -187,6 +187,7 @@ const {
   restoreTask,
   setClaimPublishedSha,
   shipTask,
+  shouldRefuseClaimResolve,
 } = require('./db-ship.js');
 const {
   createOverrideRequest,
@@ -338,6 +339,7 @@ module.exports = {
   releaseClaimsBatch,
   validateClaimBatch,
   resolveClaim,
+  shouldRefuseClaimResolve, // task 1003767 — the pure "may this tree resolve this claim?" decision
   confirmTask,
   abandonTask,
   restoreTask, // ADR 0152 — the abandoned→backlog undo that pairs with the Metic+ abandon grant

package/modules/lifecycle/routes/claims.js

@@ -525,6 +525,11 @@ module.exports = function buildClaimsRouter() {
       // record { stamp, url, method } when a staged game change was reviewed +
       // approved. The server stamps `by`/`at` authoritatively in db.resolveClaim.
       sandbox_review: { type: 'object' },
+      // task 1003767: the working tree this resolve is coming FROM, so the lock
+      // can key on the tree instead of the auth session (which a /builder-reauth
+      // re-issues, previously stranding the claim). Optional — an older CLI omits
+      // it and db.shouldRefuseClaimResolve falls back to the session compare.
+      resolver_worktree: { type: 'string', maxLength: LIMITS.WORKTREE_NAME },
     })) return;
     if (!Number.isFinite(Number(req.params.id))) {
       return res.fail('validation_failed', 400, [{ field: 'id', reason: 'wrong_type', expected: 'integer' }]);
@@ -538,6 +543,7 @@ module.exports = function buildClaimsRouter() {
       force,
       committed_files: committedFiles,
       sandbox_review: sandboxReview, // { stamp, url, method } — server stamps by/at
+      resolver_worktree: resolverWorktree, // task 1003767 — the tree this resolve comes from
     } = req.body || {};
     try {
       const result = await db.resolveClaim({
@@ -548,6 +554,12 @@ module.exports = function buildClaimsRouter() {
         valueSummary: valueSummary ?? null,
         verification: verification ?? null,
         resolverSessionId: req.gdsSession?.session_id ?? null,
+        // task 1003767: the CLI's own working tree. Client-supplied, and used
+        // ONLY to compare against the claim's stored worktree_name — it grants
+        // nothing on its own. A forged value can at most let the builder resolve
+        // THEIR OWN claim (ownership is checked separately, NOT_YOUR_CLAIM),
+        // which `release --force` already lets them do anyway.
+        resolverWorktree: typeof resolverWorktree === 'string' ? resolverWorktree : null,
         force: force === true,
         committedFiles: Array.isArray(committedFiles) ? committedFiles : null,
         sandboxReview: sandboxReview && typeof sandboxReview === 'object' ? sandboxReview : null,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.629",
+  "version": "1.19.630",
   "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

@@ -10,7 +10,7 @@
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote } = require('./cli-lib');
+const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName } = require('./cli-lib');
 const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
 const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
@@ -151,25 +151,9 @@ function captureHeadSha() {
 
 // Auto-detect this claim's worktree name when --worktree is omitted, so the
 // server's one-active-claim guard (keyed on the WORKING TREE, not the shared auth
-// session) can tell genuinely-parallel worktrees apart. Only names a LINKED git
-// worktree — where git-dir != git-common-dir, i.e. a real `.claude/worktrees/<name>`
-// checkout — using its top-level directory basename (the `<name>` the convention
-// already uses). The MAIN checkout returns null (unchanged behaviour: one claim at
-// a time there — parallelism is what worktrees are for). Best-effort: any git
-// hiccup yields null, so this can never break a claim.
-function detectWorktreeName() {
-  try {
-    const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
-    const commonDir = execSync('git rev-parse --git-common-dir', { encoding: 'utf8' }).trim();
-    // Same dir → the main checkout, not a linked worktree → leave unnamed.
-    if (path.resolve(gitDir) === path.resolve(commonDir)) return null;
-    const top = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-    const name = path.basename(top);
-    return name || null;
-  } catch (_) {
-    return null;
-  }
-}
+// session) can tell genuinely-parallel worktrees apart. The detector moved to
+// cli-lib.js in task 1003767 — the ship path now needs the SAME answer to satisfy
+// the resolve lock, and two copies drifting apart would strand a ship.
 
 // task 1278: nudge (don't block) when this session's build scripts are behind
 // origin/main. The completion cards + skills are CLI-script features that ride

package/scripts/gds/cli-lib.js

@@ -14,6 +14,7 @@ const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
+const { execSync } = require('node:child_process');
 const ic = require('../../src/instance-config');
 
 // Session token path — the WRITE target is the configured instance dir
@@ -1101,8 +1102,36 @@ function repairMsysMangledPath(raw, { exepath = process.env.EXEPATH, platform =
   return rawFwd.slice(best.length);
 }
 
+// detectWorktreeName — which linked git worktree is this process running in?
+// Moved here from claim.js in task 1003767 so the CLAIM and the RESOLVE agree on
+// one answer: the server keys both the one-active-claim guard and (now) the
+// resolve lock on the WORKING TREE rather than the shared auth session, and two
+// copies of this detector drifting apart would strand a ship with a name
+// mismatch. One definition, both callers.
+//
+// Only names a LINKED worktree — git-dir != git-common-dir, i.e. a real
+// `.claude/worktrees/<name>` checkout — using its top-level directory basename
+// (the `<name>` the convention already uses). The MAIN checkout returns null,
+// which the server reads as "no tree named" and falls back to the session
+// compare. Best-effort: any git hiccup yields null, so this can never break a
+// claim or a ship.
+function detectWorktreeName() {
+  try {
+    const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+    const commonDir = execSync('git rev-parse --git-common-dir', { encoding: 'utf8' }).trim();
+    // Same dir → the main checkout, not a linked worktree → leave unnamed.
+    if (path.resolve(gitDir) === path.resolve(commonDir)) return null;
+    const top = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    const name = path.basename(top);
+    return name || null;
+  } catch (_) {
+    return null;
+  }
+}
+
 module.exports = {
   API_BASE,
+  detectWorktreeName,
   hallBase,
   productName,
   rewardPolicy,

package/scripts/gds/ship-flow.js

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const { cliClient, requireSession, arg } = require('./cli-lib');
+const { cliClient, requireSession, arg, detectWorktreeName } = require('./cli-lib');
 const { resolveProse, markShipProgress, smokeGateMessages } = require('./ship-honesty.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
 const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
@@ -21,7 +21,7 @@ const { gitOk } = require('./ship-git.js');
 const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight } = require('./ship-preflight-steps.js');
 const { applyBaseOverride, computeChangedFiles, computeGraderBaseline, runSmokeAsync } = require('./ship-grade.js');
 const { buildPriorRoundContext, computeGradeResult, gradeAndRecord, printCreditsAndAchievements, printGradeOutcome } = require('./ship-grade-steps.js');
-const { apiErrorLine, normalizeApiError } = require('./ship-io.js');
+const { apiErrorLine, normalizeApiError, isUnknownFieldRejection } = require('./ship-io.js');
 // task 1003205's carve left pushVia() used at regradeMain but never imported, so
 // EVERY resume of a 'completed' task died with ReferenceError before resolving.
 const { pushVia } = require('./ship-deploy-target.js');
@@ -423,9 +423,7 @@ async function shipMain() {
   // It now lands the task at `completed` when verification (smoke) passes, and
   // stops. The v2 subagent grader (step 2 below) is what gates the credits +
   // the completed→confirmed transition.
-  const r = await (await cliClient()).claims.postClaimsIdResolve({
-    id: ac.claim_id,
-    body: {
+  const resolveBody = {
     outcome: 'shipped',
     notes_md: notes,
     value_summary: summary,
@@ -445,15 +443,57 @@ async function shipMain() {
     // reviewed + approved a staged game change. The server stamps by/at and
     // persists it to tasks.sandbox_review. null = nothing to record.
     sandbox_review: sandboxReview,
-    },
-  });
+    // task 1003767: the working tree this ship is running in, so the server's
+    // resolve lock can key on the TREE instead of the auth session. Without it
+    // a /builder-reauth mid-claim re-issued the session and stranded the ship
+    // with `release --force` (forfeiting graded work) the only way out. Same
+    // detector claim.js uses, so the two names always agree.
+    resolver_worktree: detectWorktreeName(),
+  };
+  let r = await (await cliClient()).claims.postClaimsIdResolve({ id: ac.claim_id, body: resolveBody });
+
+  // FORWARD COMPATIBILITY (task 1003767). The resolve route validates STRICTLY:
+  // an unknown body field is a hard 400, not an ignored extra. @cloudbongos/cli
+  // is published separately from the core and instances pin their own core
+  // version, so a CLI carrying a field the server has not learned yet would
+  // otherwise be unable to ship AT ALL against that instance — the diff that
+  // added `resolver_worktree` hit exactly this on its own ship.
+  //
+  // So: if the server rejects specifically because it does not know
+  // `resolver_worktree`, drop it and retry ONCE. The lock then falls back to
+  // the session compare server-side, which is what an older core did anyway —
+  // no behaviour is lost that that server ever had.
+  //
+  // Deliberately narrow: it retries only when the details name THIS field as
+  // unknown. Any other validation failure — including an unknown field we did
+  // not send on purpose — still surfaces, so this cannot mask a real bug.
+  if (!r.ok && isUnknownFieldRejection(r.status, r.data, 'resolver_worktree')) {
+    console.error("note: this instance's core predates resolver_worktree — retrying without it.");
+    console.error('      (the resolve lock falls back to the session check on that server.)');
+    delete resolveBody.resolver_worktree;
+    r = await (await cliClient()).claims.postClaimsIdResolve({ id: ac.claim_id, body: resolveBody });
+  }
   if (!r.ok) {
     const resolveErr = normalizeApiError(r.data);
     if (resolveErr.code === 'CLAIM_SESSION_MISMATCH') {
       const wt = resolveErr.details.claimWorktree;
-      console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
-      console.error('You can only ship from the session that originally claimed this task.');
-      console.error(`To force-release from this session: node scripts/gds/release.js ${taskId} --force`);
+      // task 1003767: name WHICH lock fired. 'worktree_mismatch' means the claim
+      // really was made in another working tree — the branch this ship would
+      // publish is not the branch that did the work, so shipping here would land
+      // the wrong commits. That is the guard doing its job, and the fix is to run
+      // the ship from the right tree, NOT to force-release. Only a fallback
+      // 'session_mismatch' (no tree named on one side — a plain clone, or an
+      // older CLI) is the historical session case.
+      if (resolveErr.details.reason === 'worktree_mismatch') {
+        console.error(`This claim belongs to a different working tree${wt ? ` (worktree: ${wt})` : ''}.`);
+        console.error(`Ship it from there — its branch holds the work: cd .claude/worktrees/${wt || '<name>'}`);
+        console.error('Shipping from this tree would publish the wrong branch, which is why it is refused.');
+      } else {
+        console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
+        console.error('No working tree was named on one side, so the older session check applied.');
+      }
+      console.error(`If the work is genuinely gone, give the task back: node scripts/gds/release.js ${taskId} --force`);
+      console.error('(--force abandons the claim and forfeits its credits — it is the give-up exit, not the fix.)');
     } else {
       console.error(`resolve failed: ${apiErrorLine(r.data, r.status)}`);
     }

package/scripts/gds/ship-io.js

@@ -57,6 +57,30 @@ function normalizeApiError(data) {
   };
 }
 
+// isUnknownFieldRejection — did the server reject this request ONLY because it
+// does not know the named body field? (task 1003767)
+//
+// WHY THIS EXISTS. The resolve route validates STRICTLY: an unknown body field
+// is a hard 400, not an ignored extra. @cloudbongos/cli ships separately from
+// the core and instances pin their own core version, so a CLI that starts
+// sending a NEW field cannot resolve a claim at all against an instance whose
+// server has not learned it yet — the change that added `resolver_worktree` hit
+// exactly that on its own ship. A caller uses this to drop the field and retry
+// once, degrading to the older server's behaviour instead of failing to ship.
+//
+// Deliberately NARROW: true only when every returned detail names THIS field.
+// If the server also complained about anything else, the request has a real
+// problem and must surface — a blanket "retry without extras" would turn every
+// validation bug into a silent second attempt.
+//
+// Pure + exported so the decision is unit-testable without a server.
+function isUnknownFieldRejection(status, data, field) {
+  if (status !== 400) return false;
+  const details = normalizeApiError(data).details;
+  if (!Array.isArray(details) || details.length === 0) return false;
+  return details.every((d) => d && d.field === field);
+}
+
 // task 1002789: the ONE renderer for a failed API call on the ship path.
 // Every generic bail site used to hand the raw body to console.error (or
 // interpolate `data.error` into a template, which stringifies the ADR 0116
@@ -109,6 +133,7 @@ module.exports = {
   shipPrefsPath,
   apiErrorLine,
   normalizeApiError,
+  isUnknownFieldRejection,
   playShipBell,
   postLandShipOutcome,
 };

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.629'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.630'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/claim_resolve_worktree_lock.mjs

@@ -0,0 +1,257 @@
+// tests/claim_resolve_worktree_lock.mjs
+//
+// task 1003767 — the resolve lock keys on the WORKING TREE, not the auth session.
+//
+// The guard exists to stop a builder shipping a claim from the wrong place:
+// /builder-ship publishes the whole branch a working tree owns, so a resolve
+// arriving from a different tree lands the wrong commits. It was IMPLEMENTED as
+// `creator_session_id !== resolverSessionId` — the AUTH-TOKEN session, which one
+// login shares across every concurrent worktree and which /builder-reauth
+// RE-ISSUES. So re-authing mid-claim made the builder's own claim permanently
+// unresolvable (CLAIM_SESSION_MISMATCH on every ship, `release --force` the only
+// exit, graded work forfeited). This is the same auth-session-vs-worktree
+// confusion shouldRefuseSessionClaim was already fixed for (task 1002570).
+//
+// What these cases defend, in order of how badly it would hurt to lose it:
+//
+//   1. THE RE-AUTH CASE. Same tree, changed session → ALLOW. This is the bug.
+//   2. THE HAZARD IS STILL GUARDED. Different tree → REFUSE, even on one session.
+//      A fix that just deleted the check would pass (1) and silently permit the
+//      commingled ship the guard exists for. Both halves are asserted.
+//   3. TIGHTENING-ONLY. Where no tree is named (older CLI, plain clone), the
+//      historical session compare still applies — nothing previously refused is
+//      now allowed except case (1).
+//   4. THE EXISTING SKIPS survive: force, an unbound/web claim, no resolver
+//      session.
+//
+// DB-free, network-free — the decision is pure, the same shape as
+// shouldRefuseSessionClaim.
+// Run:  node --test tests/claim_resolve_worktree_lock.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { shouldRefuseClaimResolve } = require('../modules/lifecycle/db-ship.js');
+
+// ── 1) the bug this task exists to fix ──────────────────────────────────────────
+test('re-auth mid-claim: same worktree, NEW session → allowed', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-before-reauth',
+    resolverSessionId: 'sess-AFTER-reauth',
+    claimWorktree: 'task-1003767',
+    resolverWorktree: 'task-1003767',
+  });
+  assert.equal(d.refuse, false, '/builder-reauth must not strand the claim it was run beside');
+  assert.equal(d.reason, null);
+});
+
+test('same worktree, same session → allowed (the ordinary happy path)', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1',
+    resolverSessionId: 'sess-1',
+    claimWorktree: 'task-42',
+    resolverWorktree: 'task-42',
+  });
+  assert.equal(d.refuse, false);
+});
+
+// ── 2) the hazard the guard exists for is STILL refused ─────────────────────────
+test('different worktree → refused, even when the session matches', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1',
+    resolverSessionId: 'sess-1',
+    claimWorktree: 'task-100',
+    resolverWorktree: 'task-999',
+  });
+  assert.equal(d.refuse, true, 'shipping from another tree would publish the wrong branch');
+  assert.equal(d.reason, 'worktree_mismatch');
+});
+
+test('different worktree AND different session → refused as a worktree mismatch', () => {
+  // Both signals disagree; the tree is the one that names the real hazard, so the
+  // reason must be the worktree one (the CLI branches its advice on it).
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1',
+    resolverSessionId: 'sess-2',
+    claimWorktree: 'task-100',
+    resolverWorktree: 'task-999',
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.reason, 'worktree_mismatch');
+});
+
+// ── 3) tightening-only: the session fallback where no tree is named ──────────────
+test('no tree on either side, different sessions → still refused (historical check)', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1',
+    resolverSessionId: 'sess-2',
+    claimWorktree: null,
+    resolverWorktree: null,
+  });
+  assert.equal(d.refuse, true, 'a plain clone keeps the old session guard — this is not a loosening');
+  assert.equal(d.reason, 'session_mismatch');
+});
+
+test('no tree on either side, same session → allowed', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-1', claimWorktree: null, resolverWorktree: null,
+  });
+  assert.equal(d.refuse, false);
+});
+
+test('claim named a tree but the resolver did not (older CLI) → session decides', () => {
+  // An older /builder-ship sends no resolver_worktree. It must not be able to
+  // resolve another session's claim just by omitting the field.
+  const refused = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-2', claimWorktree: 'task-7', resolverWorktree: null,
+  });
+  assert.equal(refused.refuse, true, 'omitting the tree must not be a way around the lock');
+  assert.equal(refused.reason, 'session_mismatch');
+
+  const allowed = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-1', claimWorktree: 'task-7', resolverWorktree: null,
+  });
+  assert.equal(allowed.refuse, false, 'an older CLI on its own session still ships fine');
+});
+
+test('resolver named a tree but the claim did not → session decides', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-2', claimWorktree: null, resolverWorktree: 'task-7',
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.reason, 'session_mismatch');
+});
+
+// ── 4) the pre-existing skips are unchanged ─────────────────────────────────────
+test('force=true skips the lock entirely (the emergency hatch)', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1',
+    resolverSessionId: 'sess-2',
+    claimWorktree: 'task-100',
+    resolverWorktree: 'task-999',
+    force: true,
+  });
+  assert.equal(d.refuse, false, 'force must still override even a genuine worktree mismatch');
+});
+
+test('an unbound/web claim (no creator session) is adoptable by any own session', () => {
+  // #616: a claim made in the browser has no working session. Binding it would
+  // force every such builder to release --force before they could ship.
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: null, resolverSessionId: 'sess-cli', claimWorktree: null, resolverWorktree: 'task-7',
+  });
+  assert.equal(d.refuse, false);
+});
+
+test('a resolver with no session context is allowed (legacy path)', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: null, claimWorktree: 'task-7', resolverWorktree: 'task-9',
+  });
+  assert.equal(d.refuse, false);
+});
+
+// ── 5) normalization agrees with every other worktree_name ingest point ─────────
+// foldWorktreeName (task 1002522) is the ONE normalization: '' and whitespace-only
+// both mean "no worktree", matching the DB index's COALESCE(worktree_name, '').
+// If this decision folded differently it could allow a resolve the index-backed
+// claim guard considers a different tree.
+test("'' and whitespace-only fold to 'no tree named', not to a tree called ''", () => {
+  const blank = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-2', claimWorktree: '', resolverWorktree: '',
+  });
+  assert.equal(blank.refuse, true, "two ''-named sides are worktree-LESS, so the session compare applies");
+  assert.equal(blank.reason, 'session_mismatch');
+
+  const spaces = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-1', claimWorktree: '   ', resolverWorktree: 'task-7',
+  });
+  assert.equal(spaces.refuse, false, 'whitespace-only is not a tree name; same session still ships');
+});
+
+test('surrounding whitespace is trimmed, not treated as a different tree', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-A',
+    resolverSessionId: 'sess-B',
+    claimWorktree: 'task-1003767',
+    resolverWorktree: '  task-1003767  ',
+  });
+  assert.equal(d.refuse, false, 'an untrimmed name must not strand a ship on a phantom mismatch');
+});
+
+test('tree comparison is exact, not a prefix match', () => {
+  const d = shouldRefuseClaimResolve({
+    claimSessionId: 'sess-1', resolverSessionId: 'sess-1', claimWorktree: 'task-100', resolverWorktree: 'task-1000',
+  });
+  assert.equal(d.refuse, true, 'task-1000 is a different tree from task-100');
+  assert.equal(d.reason, 'worktree_mismatch');
+});
+
+// ── 6) degrades safely on odd input (never throws) ──────────────────────────────
+test('no arguments at all does not throw and allows (nothing to scope to)', () => {
+  const d = shouldRefuseClaimResolve();
+  assert.equal(d.refuse, false);
+  assert.equal(d.reason, null);
+});
+
+// ── 7) forward compatibility: a new CLI must still ship against an OLDER core ───
+// The resolve route validates STRICTLY — an unknown body field is a hard 400, not
+// an ignored extra (routes/_helpers.js validate(), strict defaults on). The core
+// ships separately from @cloudbongos/cli and instances pin their own version, so
+// a CLI that starts sending resolver_worktree cannot resolve AT ALL against a
+// server that has not learned it. This was not theoretical: the very ship of this
+// change was refused `validation_failed [HTTP 400]` by prod, which runs an older
+// core. The CLI drops the field and retries once; these pin that decision.
+const { isUnknownFieldRejection } = require('../scripts/gds/ship-io.js');
+
+// The EXACT envelope prod returned on the refused ship (ADR 0116 shape, with
+// reason 'unknown_field' from validate()'s strict branch).
+const oldCoreRejection = {
+  error: {
+    code: 'validation_failed',
+    message: 'validation_failed',
+    details: [{ field: 'resolver_worktree', reason: 'unknown_field' }],
+  },
+};
+
+test('an older core rejecting only resolver_worktree triggers the retry', () => {
+  assert.equal(isUnknownFieldRejection(400, oldCoreRejection, 'resolver_worktree'), true);
+});
+
+test('a rejection naming OTHER fields too must NOT be retried away', () => {
+  // A real validation bug alongside ours has to surface, not be masked by a
+  // silent second attempt that drops one field and fails again for the rest.
+  const mixed = {
+    error: {
+      code: 'validation_failed',
+      details: [
+        { field: 'resolver_worktree', reason: 'unknown_field' },
+        { field: 'outcome', reason: 'missing' },
+      ],
+    },
+  };
+  assert.equal(isUnknownFieldRejection(400, mixed, 'resolver_worktree'), false);
+});
+
+test('a rejection about a DIFFERENT field alone is not our case', () => {
+  const other = {
+    error: { code: 'validation_failed', details: [{ field: 'notes_md', reason: 'too_long' }] },
+  };
+  assert.equal(isUnknownFieldRejection(400, other, 'resolver_worktree'), false);
+});
+
+test('only a 400 counts — a 403/409/500 is never an unknown-field rejection', () => {
+  for (const status of [403, 409, 500, 200]) {
+    assert.equal(isUnknownFieldRejection(status, oldCoreRejection, 'resolver_worktree'), false,
+      `status ${status} must not trigger the retry`);
+  }
+});
+
+test('an empty or malformed details payload does not trigger the retry', () => {
+  assert.equal(isUnknownFieldRejection(400, { error: { code: 'validation_failed', details: [] } }, 'resolver_worktree'), false,
+    'no details means we cannot attribute the failure to our field');
+  assert.equal(isUnknownFieldRejection(400, {}, 'resolver_worktree'), false);
+  assert.equal(isUnknownFieldRejection(400, null, 'resolver_worktree'), false);
+  assert.equal(isUnknownFieldRejection(400, { error: 'flat_string_error' }, 'resolver_worktree'), false);
+});