@bongos/core 1.21.61 → 1.21.62

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.61",
-  "core_contract": "1.21.61",
-  "source_commit": "af0a03f180373b14387c419d584201ee10f7a5ab",
+  "core_version": "1.21.62",
+  "core_contract": "1.21.62",
+  "source_commit": "105061dd47a96f0d628fd6ef926fd3f325d76ac3",
   "source_ref": "HEAD",
-  "built_at": "2026-10-05T10:43:45.436Z",
+  "built_at": "2026-10-05T21:53:01.352Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 585,
+    "docs_redacted": 586,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 2948,
+    "functional_verbatim": 2949,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3562,
-  "tree_sha256": "0537fa5681807a5c2c7bd9b89d503ede191d00215928234a666c9795d20de7eb",
+  "file_count": 3564,
+  "tree_sha256": "293671547d32416cc06202a1b95675be164a603b599e65c19cc5df0e8d577288",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2284,10 +2284,15 @@
       "mode": "0000644",
       "sha256": "93c863a7f961cd91c052eee2188b16b9f360cec26478dde6225b304ee0e59f7d"
     },
+    {
+      "path": "docs/adr/0366-hall-planning-is-forms-and-a-goal-made-there-carries-its-own-spec-task.md",
+      "mode": "0000644",
+      "sha256": "29c841d193efa7b6f6479e14a6056057138574fcd7b526f667da6f219dece5a7"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "a81d1eeeb26ce4fde1731485e943d82ddb320bc60a5f1782f7a207b94da5fff5"
+      "sha256": "08f66fecefc58d9c09e45841dd9d47514e807934cfcd4621a8bfeaa390afb334"
     },
     {
       "path": "docs/api-reference.md",
@@ -2837,7 +2842,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "fe852dba06c424e3ff2b7b84eb4cc4670690525201f2d1929e9fd5a0340ab522"
+      "sha256": "469982519512666ef5e4f36e65446397b1305c6367446c2fd177c2942d70e334"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2877,7 +2882,7 @@
     {
       "path": "docs/onboarding/diagrams/assertions.json",
       "mode": "0000644",
-      "sha256": "b2e8855cbc2acc539dbd060093a15bdd0a9d073fe8006736552d07676f3d6899"
+      "sha256": "1cda1da05b0a74bc5532e478acbf3d625c49d1a1fac3b75ed967626d95a022bc"
     },
     {
       "path": "docs/onboarding/diagrams/puppeteer-config.json",
@@ -7047,7 +7052,7 @@
     {
       "path": "modules/lifecycle/merge-lock.js",
       "mode": "0000644",
-      "sha256": "aaa5171275b156b67ed9767c341fda462fd6e6e44e4591d9fd21ba1aece996ac"
+      "sha256": "16667b27f462627277da092dd0cf8905cf7144f1a959fdaf3174a9fb41a91da4"
     },
     {
       "path": "modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql",
@@ -7367,7 +7372,7 @@
     {
       "path": "modules/lifecycle/ship-preflight.js",
       "mode": "0000644",
-      "sha256": "3b08535b9a680b6f0eaf0ab2d5e38f8ae77ff5563b517a97c1ab34402f5c7a06"
+      "sha256": "99de217d003dd0a837e8604a7a6fedc28be8e5e589c0e4d70b7f46eca1b4432e"
     },
     {
       "path": "modules/lifecycle/sky.js",
@@ -9957,12 +9962,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b9418adf527e06a17607eff5caea767b391e41fbe70b95a429c493dd72c0e443"
+      "sha256": "32077bf55d5b87cb987c0d64e579df513a72248dc79d719f878d1cfb41f4090d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1be4723fd1f70d91d04a5f8ca95237fd864b704ec61e978e25d3169f6eb29f31"
+      "sha256": "a33111b7630688dd0840cf123940fc0c7efdb751056b554d6cf439831f9813c9"
     },
     {
       "path": "public-docs/index.html",
@@ -9982,7 +9987,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "6921afa5e5ab728375f7dbfe4f8a0b024d4006d65912fa52601145cba74a5c86"
+      "sha256": "68623d6dac838274578a99dd42d1a684e1a6369e2fd7bcb53a2af3778f3b2b68"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -11457,7 +11462,7 @@
     {
       "path": "scripts/gds/ship-grade.js",
       "mode": "0000644",
-      "sha256": "eb0740f3cdc3dc91038320dd9044dc81c05e31212059d772d5c8bf6e9f44b474"
+      "sha256": "5fd40df43c942eb3fcbd24a22c22743e63d2b32efba3c612c7e2fa791ad0f087"
     },
     {
       "path": "scripts/gds/ship-honesty.js",
@@ -11482,12 +11487,12 @@
     {
       "path": "scripts/gds/ship-merge-gate.js",
       "mode": "0000644",
-      "sha256": "34c28500eb2c4324f44c5b3604049c305d7b7921b57557ee325ece88b6293252"
+      "sha256": "fba341724c94b1ab9a56b1b43cda608eaa477f50c6f8e65ec287632367d603a9"
     },
     {
       "path": "scripts/gds/ship-merge.js",
       "mode": "0000644",
-      "sha256": "7b877a3a3cb63c41923b9e6410f042b13263afe88429ade6b32f6d4e90d4fadd"
+      "sha256": "8d37d5c6cbaa1ca0e8363fab6c34159d1e16922fdae11d4ffc17b4d9e2c7f795"
     },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
@@ -11512,7 +11517,7 @@
     {
       "path": "scripts/gds/ship-state.js",
       "mode": "0000644",
-      "sha256": "a22377162ea9449249ee338e434c2b595a4de88743e6dacc290138f0ea9799dc"
+      "sha256": "e465cb391d4518258290d6f53be3a31353e701fb21935f8e1f9ff7b4f38e00a6"
     },
     {
       "path": "scripts/gds/ship-surprise.js",
@@ -12202,7 +12207,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "27af8869982707a3bbb16a65d9d2b0ccca2a40a579448aa9cc8fd10045e5c93d"
+      "sha256": "b5dc083bafe5265707463d0de6a151f21dd83a2849d7e8eeded08215ddce59cb"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -15332,7 +15337,7 @@
     {
       "path": "tests/merge_lock.mjs",
       "mode": "0000644",
-      "sha256": "5617e46b1e07ceb5fd537ae1192a27c88e8ce5d1fd06f219190f90aaebd64a5a"
+      "sha256": "03888ba034c0af2af764575b4b6c2b37e1f1eb54c7dc02b39ce4590e5a4b5451"
     },
     {
       "path": "tests/metrics.mjs",
@@ -17022,7 +17027,7 @@
     {
       "path": "tests/ship_merge_gate.mjs",
       "mode": "0000644",
-      "sha256": "b498d2820f6e17948cb8a86637d16b248a3349ebd9933343dd4b335a239497b7"
+      "sha256": "28ad67a5ee8be6807f8d16149ea42cb837b7bc4e4084068b74d8e944db09d291"
     },
     {
       "path": "tests/ship_post_land_verify.mjs",
@@ -17032,7 +17037,7 @@
     {
       "path": "tests/ship_preflight.mjs",
       "mode": "0000644",
-      "sha256": "b86e826355cf786328a7d1301abebd9c7c8b5c5b7ad82b9d2ebcb3d6e35285a9"
+      "sha256": "325980877dc43ea902de03cf938a85f29700f0443ca040efe75873b5f4f210b9"
     },
     {
       "path": "tests/ship_premerge.mjs",
@@ -17074,6 +17079,11 @@
       "mode": "0000644",
       "sha256": "46856ed6c15ec0cca70e9d2541b4e17331de3c2336eb45dc1e36de1241b5440a"
     },
+    {
+      "path": "tests/ship_vendored_instance.mjs",
+      "mode": "0000644",
+      "sha256": "75aa59accad12d197202457ed36281e5d3eca1040762a5045972c4b10cf09006"
+    },
     {
       "path": "tests/ship_zero_commit.mjs",
       "mode": "0000644",

package/docs/adr/0366-hall-planning-is-forms-and-a-goal-made-there-carries-its-own-spec-task.md

@@ -0,0 +1,85 @@
+# ADR 0366 — Hall planning is forms; a goal made there carries its own spec task, and the interviews stay in the CLI
+
+- **Status:** accepted
+- **Date:** 2026-10-05
+- **Task:** [task 1003461](https://cloudbongos.com/builders#/task/1003461) (spike, goal 1000089 — Working area 3, BONGOS-V2)
+- **Builds on:** [ADR 0086](0086-goal-scoped-work-hierarchy.md) (goals and the scope wall), [ADR 0154](0154-goal-owner-criterion-authoring.md) (a goal's owner authors its criteria), [ADR 0264](0264-the-ten-working-areas.md) §1 (working area 3: "users edit, scope and manage work without ever prompting Claude")
+- **Decided with:** the owner, 2026-10-05 — two questions; the scope answer was the owner's own (D3), the hand-off answer was the recommended option (D4).
+
+## Context
+
+Goal 1000089 wants the hall to plan work: create a task, a goal, a criterion. Two CLI flows do this today, and both are **interviews**, not forms:
+
+- **`/goal-create`** (`.claude/skills/goal-create/SKILL.md`). Phases 1–3 are marked *"autonomous; ask nothing"*: Claude picks the version, decides **reuse vs create** against the live goal board, infers the **scope wall** from the planned work's file paths and checks it against the live module roster, drafts 2–4 criteria and 3–8 seed tasks with dependencies. Phase 4 asks the human only the grey areas (at most 4 questions) and one approval. Phase 5 writes goal → criteria → tasks.
+- **`/planning-session`** (`.claude/skills/planning-session/SKILL.md`). A whole version: a written spec file under `docs/specs/`, a multi-round interview that runs *"until nothing material is left"*, then a migration, a seed script, dependency ranking and promotion. Creating a version is Archon-only (ADR 0250 §6).
+
+The spike's question: which of these steps are form-shaped, which must stay interviews (named, so nobody half-builds them), and whether anything wants a third shape. The constraint: every write already exists behind a server rank floor (`task.create`, `goal.create`, `criterion.create`, the Archon wall on a protected scope); the spike decides **surface only**.
+
+### The evidence
+
+Read the two flows for which inputs a person can **know** versus which Claude **infers**:
+
+| Input | Who supplies it today | Shape |
+|---|---|---|
+| A task's title, description, goal | the person | form — and the goal picker already exists: `GET /goals/suggestions` feeds the hall composer (`sky-composer.js`, task 1003069) |
+| A task's kind, criterion link | the server already infers it: `POST /tasks` auto-classifies kind; `GET /goals/:id/suggest-criteria` ranks criteria | form, with the server's suggestion shown |
+| A goal's name, subtitle, description, version, category | the person (goal-create *drafts* them, but they are statements of intent, and `GET /work-categories` is a plain list) | form |
+| A criterion's outcome text | the person, for a goal they own (ADR 0154) | form — the slug `criterion_id` is derivable from the text, and a 409 collision is a sentence, not a judgement |
+| Satisfying a criterion | already in the hall (`goals-page.js`) | form (exists) |
+| Reuse vs create a goal | Claude reads the board and judges | **interview** — though a form can *show* the suggester's candidates and let the person choose |
+| A goal's **scope wall** | Claude infers from file paths, checks the roster | **interview** — and the roster is not readable by the hall at all (`module-scope-map` is server-only; the hall gets only a derived `scope_protected` flag, `goal-route-authz.js` `decorateGoalScope`) |
+| Criteria drafted from a description; seed tasks and their dependency edges | Claude | **interview** |
+| A version: spec, multi-round interview, migration, seed script, ranking | Claude with the owner, Archon-only to create | **interview** |
+
+And two precedents show the in-between shape already exists in the hall: the idea composer asks a **server-defined question sequence** with skip and cancel and no Claude (`sky-composer.js`, the base-v2 template), and the hall already **composes a prompt for a session to finish** (`task-lib.js` `buildPromptForTask`, the bulk toolbar's sequential and parallel prompts, collab's "Copy for Session Start").
+
+## Decision
+
+**D1 — Form-shaped; build in the hall.** Every step whose inputs the person knows:
+1. Create a task under a goal (title, description, goal via the existing suggester; kind and criterion offered from the server's own suggestions). → [task 1003462](https://cloudbongos.com/builders#/task/1003462).
+2. Create a goal: a **name** field and a separate **subtitle/description** (goal 1000072's convention — a title is a name, not its own explanation), version, category. **No scope field** (D3). Before the name is submitted the form shows the suggester's matching open goals, so "reuse instead" is a click and the judgement stays the person's. → [task 1003463](https://cloudbongos.com/builders#/task/1003463).
+3. Attach a criterion to a goal the person owns or manages: the outcome text; the slug is derived from it. → task 1003463.
+
+Every refusal the server already makes — `task.create` / `goal.create` / `criterion.create` floors, the Archon wall on a protected scope, ADR 0154's `bad_goal_id` for a goal the actor does not hold — is rendered as copy. The forms never pre-filter themselves into a shape that hides one (1003463's own rule).
+
+**D2 — Interview-shaped; stays in the CLI, deliberately absent from the hall.** Named so nobody half-builds them:
+- planning a **version** (`/planning-session`) — the spec file, the multi-round interview, the migration, the seed script, the ranking, and creating a version at all;
+- **inferring a goal's scope wall** from the work it will do;
+- **drafting criteria** from a description, and **decomposing a goal into seed tasks** with dependency edges;
+- **judging reuse vs create** beyond showing the suggester's candidates;
+- **carrying achieved goals forward** across a version boundary (the planning session's rescope).
+
+A hall form for any of these would be the title-field-and-textarea the spike warned against: worse than the CLI it replaces, because the CLI's value *is* the inference.
+
+**D3 — The third shape: a goal made in the hall carries its own spec task (the owner's answer).** A goal created from the hall form is created with a task inside it — **"Spec goal N: its scope, criteria and first tasks"** — and the goal's other work waits behind that task until it ships. Someone claims it like any task and does the interview half in a session (`/goal-create`, finishing an existing goal rather than creating one). This is the "draft the hall composes and a session finishes" shape, but recorded in the ledger as a claimable, creditable task rather than a prompt on someone's clipboard. Concretely:
+- `POST /goals` grows an opt-in `spec_task: true` (the hall form sends it; `/goal-create`, which specs inline, does not). The server creates the spec task in the same request, `source_ref = goal-<id>-spec` so a retry is idempotent, promoted to `ready` so it can be claimed.
+- While that task is unshipped, every task created in the goal gets a **dependency** on it, so a claim is refused `DEPS_NOT_SHIPPED` — the existing gate, not a new one. Once it ships, the dependents auto-promote as they do today.
+- The walls do not move. Setting the scope uses the existing `POST /goals/:id/scope` (`goal.scope.widen`, owner or manager, Archon for a protected key) and criteria use `criterion.create` under ADR 0154. A claimer who does not hold the goal drafts the scope and criteria and hands them to the owner — `/goal-create`'s existing off-ramp — rather than gaining anything.
+
+No new permission and no migration: the spec task is identified by its `source_ref`, and blocking is an ordinary dependency.
+
+**D4 — An optional hand-off button.** On a goal's page, a **"Plan with Claude"** button copies a prompt that continues from that goal (its open spec task when there is one, else `/goal-create` against the goal for seed tasks). It is an extra, never a requirement: every D1 step works without it, so ADR 0264's "without ever prompting Claude" holds.
+
+## Consequences
+
+- Goal 1000089's remaining planning work is five tasks (below; the three new ones were filed by this spike as tasks 1004585, 1004586 and 1004587). The CLI flows are unchanged except that `/goal-create` learns to finish an existing goal's spec task.
+- A hall-made goal is visibly **unspecced** until its spec task ships, and its work cannot be claimed early. That is the intent: a goal with no wall and no criteria is the state `/goal-create` exists to prevent, and D3 makes the gap a task instead of a silence.
+- The hall never needs the module roster, so the protected list stays server-only.
+- Risk: a spec task nobody claims stalls its goal. It is an ordinary ready task, visible on the board and in the goal; if this proves common, an age nudge is the follow-up, not a softer block.
+
+## The task list for the rest of the criterion
+
+| Task | Shape | Depends on |
+|---|---|---|
+| [task 1003462](https://cloudbongos.com/builders#/task/1003462) — Create a task from the hall, attached to its goal | form (D1.1) | — |
+| [task 1004585](https://cloudbongos.com/builders#/task/1004585) — A goal made in the hall carries a spec task that gates its other work (server: `spec_task`, the dependency) | D3 | — |
+| [task 1003463](https://cloudbongos.com/builders#/task/1003463) — Author a goal and a done-when criterion from the hall | form (D1.2, D1.3) | task 1004585 |
+| [task 1004586](https://cloudbongos.com/builders#/task/1004586) — `/goal-create` finishes an existing goal's spec task | D3, CLI | task 1004585 |
+| [task 1004587](https://cloudbongos.com/builders#/task/1004587) — "Plan with Claude" hand-off button on a goal | D4 | task 1004585 |
+
+## Alternatives considered
+
+- **A scope picker in the goal form** (checkboxes of code areas, protected ones marked). Rejected in favour of D3 by the owner: scope is inferred from the work, and a person ticking boxes before the work is understood is the half-built interview D2 forbids. It would also have needed a new roster read.
+- **No scope at all for hall goals.** Rejected: an open wall with no criteria and nobody responsible for fixing it is the catch-all failure ADR 0086 retired.
+- **Port `/goal-create` into the hall as a guided form** (the idea composer's question sequence). Rejected: the composer's questions are fixed; goal-create's are decided by what it reads, which is exactly the part a script cannot do.
+- **The hand-off as the only path** (every hall planning action copies a prompt). Rejected: it breaks working area 3's thesis outright.

package/docs/adr/README.md

@@ -484,3 +484,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0363 | [**Who decides what is a per-project table, changed only by a passed amendment** ([task 1004529](https://cloudbongos.com/builders#/task/1004529), goal 1000125). **D1:** `government_decision_rules`, one row per building: `gate` (as today), `board` (the charter only), `nobody` (vacant) or a membership predicate with decide / first / consent / majority / unanimous / sign-off. **D2:** the seeded defaults are today, and a malformed row reads as its default. **D3:** written only inside the transaction that closes a `decision_rules` amendment as passed; JS guard + SQL condition + trigger; no settings route. **D4:** eight building matters join the board's three subjects, openable only where a row names a sitting; sign-off is the author rule. **D5:** People's rank assignments defer to People's row (`checkActAlone`); a passed People matter acts. **D6:** the docket's buildings carry who decides.](0363-who-decides-what-is-a-table-changed-only-by-amendment.md) | government / Governor City |
 | 0364 | [**Repo access is asked at sign-in on the hub, and held for as long as the builder stays signed in** ([task 1004549](https://cloudbongos.com/builders#/task/1004549)). Amends ADR 0143 and 0155. **D1:** every sign-in door on the hub's own pages carries `repos=1`; the hall and CLI stay identity-only. **D2:** the repo token's TTL is the web session's remaining life; a web sign-out deletes it, a CLI logout does not. **D3:** a draft at a wizard step beside a stored create keeps its place on a reload or a GitHub round-trip.](0364-repo-access-is-asked-at-sign-in-and-held-for-the-session.md) | auth / GitHub / create wizard |
 | 0365 | [**A guild engages a project through each member's own door** ([task 1002303](https://cloudbongos.com/builders#/task/1002303)). Amends ADR 0336 D7's invite half after ADR 0353. **D1:** the engagement row as D7 specified, plus `guild_id` on the echo (the latest application decides the label). **D2:** a guild applies = each member applies as themselves through the relay, naming the engagement. **D3:** a project invites a guild = the hub records it and returns one hall hand-off link per public-roster member; no hub-written invites, the one-step relay stays deferred. **D4:** a project is named only when on the map and public, for both kinds. **D5:** the label rides the applicant-profile read; the queue is R28's. **D6:** the D4.4 guild cards are their own task.](0365-a-guild-engages-a-project-through-each-members-own-door.md) | guilds / invites / applications |
+| 0366 | [**Hall planning is forms; a goal made there carries its own spec task, and the interviews stay in the CLI** ([task 1003461](https://cloudbongos.com/builders#/task/1003461), goal 1000089). Spike answer. **D1:** form-shaped, build in the hall: create a task under a goal, create a goal (name + subtitle, version, category, no scope field), attach a criterion to a goal you hold; every server refusal rendered as copy. **D2:** interview-shaped, deliberately absent from the hall: version planning, scope inference, drafting criteria and seed tasks, reuse-vs-create judgement, carry-forward. **D3 (owner):** a hall-made goal is created with a "Spec goal N" task (`POST /goals` `spec_task: true`, `source_ref goal-<id>-spec`) and every task in the goal depends on it until it ships; no new permission, no migration. **D4:** an optional "Plan with Claude" hand-off button.](0366-hall-planning-is-forms-and-a-goal-made-there-carries-its-own-spec-task.md) | lifecycle / planning |

package/docs/module-api-changelog.md

@@ -2949,5 +2949,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.59 with no explicit bump. run 37294675301. (task 1002620)
   1.21.61 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.60 with no explicit bump. run 37298331673. (task 1002620)
+  1.21.62 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.61 with no explicit bump. run 37378745989. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/onboarding/diagrams/assertions.json

@@ -22,8 +22,8 @@
     ],
     "default_rank": "xenos",
     "wired_ranks": [
-      "xenos",
       "archon",
+      "xenos",
       "thetes",
       "metic"
     ],

package/modules/lifecycle/merge-lock.js

@@ -10,7 +10,7 @@
 // ship-vs-merge-mode, and merge-mode-vs-merge-mode are all serialized.
 // (V3.R50 / #269, criterion C6.)
 //
-// The lock is a plain file at <repoRoot>/.git/otb-automerge.lock. We don't use
+// The lock is a plain file at <common git dir>/otb-automerge.lock (see lockPath). We don't use
 // flock(2): ships and merge runs happen on macOS, where flock over an
 // iCloud-synced filesystem is unreliable, and the holder may be a short-lived
 // CLI process (the manual /merge-mode case has no long-lived owner). The file
@@ -43,14 +43,54 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { execSync } = require('node:child_process');
+const { execSync, execFileSync } = require('node:child_process');
 
 const AUTO_STALE_MS = 10 * 60 * 1000; // crashed automated ship
 const MANUAL_STALE_MS = 30 * 60 * 1000; // operator walked away mid-merge-mode
 const INDEX_LOCK_GRACE_MS = 60 * 1000; // a git index.lock younger than this may be a LIVE op
 
+// lockPath — the lockfile lives in the repo's COMMON git dir (task 1004584).
+// When `main` is checked out in a LINKED worktree, <root>/.git is a FILE (a
+// `gitdir:` pointer), so the old <root>/.git/otb-automerge.lock was an ENOENT
+// on every acquire. The common dir is the same folder from every worktree, so
+// a ship from any of them and the merge-lock CLI all contend for ONE file.
+// A primary checkout (.git is a directory) short-circuits without spawning git;
+// when git cannot answer, the historical path is kept.
 function lockPath(repoRoot) {
-  return path.join(repoRoot, '.git', 'otb-automerge.lock');
+  return path.join(commonGitDir(repoRoot), 'otb-automerge.lock');
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch (_) { return false; }
+}
+
+// Ask git for a path inside the repo's git dirs, absolute. `args` is the
+// rev-parse tail (['--git-common-dir'] or ['--git-path', 'index.lock']). Null
+// when the root is not a repo or git is unavailable.
+function gitRevParsePath(repoRoot, args) {
+  try {
+    const out = execFileSync('git', ['rev-parse', ...args], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!out) return null;
+    return path.isAbsolute(out) ? out : path.resolve(repoRoot, out);
+  } catch (_) {
+    return null;
+  }
+}
+
+function commonGitDir(repoRoot) {
+  const dotGit = path.join(repoRoot, '.git');
+  if (isDir(dotGit)) return dotGit;
+  return gitRevParsePath(repoRoot, ['--git-common-dir']) || dotGit;
+}
+
+// The worktree's OWN index.lock — per-worktree, so a linked main keeps it in
+// .git/worktrees/<name>/, not under the common dir.
+function indexLockPath(repoRoot) {
+  const dotGit = path.join(repoRoot, '.git');
+  if (isDir(dotGit)) return path.join(dotGit, 'index.lock');
+  return gitRevParsePath(repoRoot, ['--git-path', 'index.lock']) || path.join(dotGit, 'index.lock');
 }
 
 // Synchronous sleep without spawning a process (ship.js is execSync-style and
@@ -76,9 +116,11 @@ function pidAlive(pid) {
 }
 
 // Parse the lockfile into { pid, ts, mode } or null if absent/unreadable.
-function readLock(repoRoot) {
+// `file` lets a caller that already resolved lockPath skip re-resolving it (for
+// a linked worktree that is a git spawn per call).
+function readLock(repoRoot, file = lockPath(repoRoot)) {
   try {
-    const [p, t, m] = fs.readFileSync(lockPath(repoRoot), 'utf8').split('\n');
+    const [p, t, m] = fs.readFileSync(file, 'utf8').split('\n');
     const pid = parseInt(p, 10);
     const ts = parseInt(t, 10) || 0;
     const mode = m && m.trim() === 'manual' ? 'manual' : 'auto';
@@ -118,7 +160,7 @@ function recoverWorktree(repoRoot, { now = Date.now, runner = execSync } = {}) {
   //    live git process could still own it. A fresh lock means a live op
   //    (possibly a holder that just acquired after us); never yank that.
   try {
-    const lk = path.join(repoRoot, '.git', 'index.lock');
+    const lk = indexLockPath(repoRoot);
     const st = fs.statSync(lk); // throws ENOENT when absent → nothing to clear
     if (now() - st.mtimeMs > INDEX_LOCK_GRACE_MS) fs.unlinkSync(lk);
   } catch (_) {
@@ -176,7 +218,7 @@ function acquire(repoRoot, opts = {}) {
       return true;
     } catch (e) {
       if (e.code !== 'EEXIST') throw e;
-      const rec = readLock(repoRoot);
+      const rec = readLock(repoRoot, p); // p resolved once, before the loop
       if (isStale(rec, now())) {
         let reclaimed = false;
         try {
@@ -206,10 +248,11 @@ function acquire(repoRoot, opts = {}) {
 function release(repoRoot, opts = {}) {
   const { pid = process.pid, force = false } = opts;
   try {
-    const rec = readLock(repoRoot);
+    const file = lockPath(repoRoot);
+    const rec = readLock(repoRoot, file);
     if (!rec) return;
     if (force || rec.mode === 'manual' || rec.pid === pid) {
-      fs.unlinkSync(lockPath(repoRoot));
+      fs.unlinkSync(file);
     }
   } catch (_) {
     /* already gone */
@@ -251,6 +294,7 @@ module.exports = {
   MANUAL_STALE_MS,
   INDEX_LOCK_GRACE_MS,
   lockPath,
+  indexLockPath,
   pidAlive,
   readLock,
   isStale,

package/modules/lifecycle/ship-preflight.js

@@ -245,6 +245,31 @@ function cleanupMacFinderDupRefs(cwd) {
   return deleted;
 }
 
+// worktreeBlocks — `git worktree list --porcelain` as [{ dir, branch, bare }], in
+// git's order (the primary checkout first). Null when git can't answer. The one
+// parser behind findMainWorktree and findPrimaryWorktree.
+function worktreeBlocks(cwd) {
+  try {
+    const out = execSync('git worktree list --porcelain', {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out.split('\n\n').filter(Boolean).map((block) => {
+      const wt = { dir: null, branch: null, bare: false };
+      for (const raw of block.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('worktree ')) wt.dir = line.slice('worktree '.length);
+        else if (line.startsWith('branch refs/heads/')) wt.branch = line.slice('branch refs/heads/'.length);
+        else if (line === 'bare') wt.bare = true;
+      }
+      return wt;
+    });
+  } catch (_) {
+    return null; // not a git repo, or git not available — caller falls back
+  }
+}
+
 function findMainWorktree(cwd) {
   // The auto-merge in ship.js runs git on the worktree that has `main`
   // checked out. Feature work happens in linked worktrees under
@@ -260,28 +285,20 @@ function findMainWorktree(cwd) {
   //   branch refs/heads/claude/feature
   //
   // Returns the worktree path whose branch is `main`, or null if none.
-  try {
-    const out = execSync('git worktree list --porcelain', {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    const blocks = out.split('\n\n').filter(Boolean);
-    for (const block of blocks) {
-      let dir = null;
-      let branch = null;
-      for (const line of block.split('\n')) {
-        if (line.startsWith('worktree ')) dir = line.slice('worktree '.length);
-        else if (line.startsWith('branch refs/heads/')) {
-          branch = line.slice('branch refs/heads/'.length);
-        }
-      }
-      if (branch === 'main' && dir) return dir;
-    }
-  } catch (_) {
-    // Not a git repo or git not available — caller will fall back.
-  }
-  return null;
+  const main = (worktreeBlocks(cwd) || []).find((wt) => wt.branch === 'main' && wt.dir);
+  return main ? main.dir : null;
+}
+
+// findPrimaryWorktree — the repo's primary checkout (the first block of
+// `git worktree list --porcelain`), whatever branch it is on. The fallback merge
+// target when NO worktree has `main` checked out (task 1004584): it is still the
+// instance's own checkout, so ship can say "this is on X, not main" instead of
+// falling back to the core package folder — which in a vendored instance is
+// node_modules/@bongos/core, not a repo at all. Null for a bare primary or when
+// git can't answer.
+function findPrimaryWorktree(cwd) {
+  const first = (worktreeBlocks(cwd) || [])[0];
+  return first && !first.bare && first.dir ? first.dir : null;
 }
 
 // task 932: post-ship working-tree CLOSE-OUT plan (pure). The mirror image of
@@ -308,5 +325,6 @@ module.exports = {
   cleanupMacFinderDupRefs,
   gitDirFor,
   findMainWorktree,
+  findPrimaryWorktree,
   closeoutPlan,
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.61",
+  "version": "1.21.62",
   "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/release-notes.json

@@ -9138,5 +9138,15 @@
       "id": "1004570",
       "text": "A project owner now sees a Danger zone in their project's settings, with links straight to the place where they can take the project offline or delete it. Nobody else sees it, and self-hosted projects don't show it."
     }
+  ],
+  "1.21.62": [
+    {
+      "id": "1003461",
+      "text": "Decided how planning works in the hall: simple forms for creating tasks, goals and criteria, while version planning stays a guided Claude session. A goal made in the hall now comes with its own 'spec this goal' task that the r"
+    },
+    {
+      "id": "1004584",
+      "text": "Shipping finished tasks now works for projects that install Bongos as a package, so their work lands instead of getting stuck halfway."
+    }
   ]
 }

package/scripts/gds/ship-grade.js

@@ -9,6 +9,7 @@
 'use strict';
 
 const crypto = require('node:crypto');
+const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { cliClient } = require('./cli-lib');
 const grader = require('../../modules/grading/grader');
@@ -22,7 +23,10 @@ const grader = require('../../modules/grading/grader');
 const { hasCopyOrVisualWork } = require('../../modules/lifecycle/cascade.js');
 const { resolveBuilderModel } = require('./ship-memory-sync.js');
 const { argvOut, gitArgvOk, gitOk, shellOk } = require('./ship-git.js');
-const { GRADER_DIFF_CHAR_CAP, GRADER_TIMEOUT_MS, REPO_ROOT, noteServerReward } = require('./ship-state.js');
+const { GRADER_DIFF_CHAR_CAP, GRADER_TIMEOUT_MS, CORE_ROOT, REPO_ROOT, noteServerReward } = require('./ship-state.js');
+
+// The core's smoke suite, by absolute path from the package dir (task 1004584).
+const SMOKE_SCRIPT = path.join(CORE_ROOT, 'scripts', 'gds', 'smoke-gds.js');
 
 // ---------- Step 1+2: local verification ----------
 
@@ -380,10 +384,13 @@ async function runNoArtifactGrader({ task, valueSummary, notes, runOpts: extraOp
 }
 
 function runSmoke() {
-  // `cwd: REPO_ROOT` + a relative script path is robust to spaces or other
-  // shell metacharacters that may appear in the absolute repo path on some
-  // machines.
-  const okPms = shellOk(`"${process.execPath}" scripts/gds/smoke-gds.js`, { cwd: REPO_ROOT });
+  // The script is addressed from CORE_ROOT, never cwd-relative: in a vendored
+  // instance it lives under node_modules/@bongos/core, not under the instance
+  // checkout, and the relative form died MODULE_NOT_FOUND after a clean merge —
+  // which then reset main and stranded the task at confirmed (task 1004584).
+  // cwd stays the instance checkout so instance config resolves as before; the
+  // JSON.stringify quoting survives spaces in either path.
+  const okPms = shellOk(`"${process.execPath}" ${JSON.stringify(SMOKE_SCRIPT)}`, { cwd: REPO_ROOT });
   return { ran: true, clean: okPms };
 }
 
@@ -394,7 +401,7 @@ function runSmoke() {
 // post-merge smoke call keeps the sync form (nothing overlaps there).
 function runSmokeAsync() {
   return new Promise((resolve) => {
-    const child = spawn(process.execPath, ['scripts/gds/smoke-gds.js'], {
+    const child = spawn(process.execPath, [SMOKE_SCRIPT], {
       cwd: REPO_ROOT, stdio: 'inherit', windowsHide: true,
     });
     child.on('error', () => resolve({ ran: true, clean: false }));

package/scripts/gds/ship-merge-gate.js

@@ -168,7 +168,32 @@ function removeProbe(repoRoot, dir) {
 // tip as it stood BEFORE the branch was merged in (in ship-merge.js that is
 // origin/main, since the ff-only step immediately above it guarantees the two
 // are the same commit).
+// gateApplies — does this repo carry the fitness gate at all? A VENDORED
+// instance (core under node_modules/@bongos/core) has no scripts/gds/fitness.js
+// of its own — fitness is the core's architecture gate, and the core ran it in
+// its own CI before it was published. Without this the gate read the missing
+// file as 'unmeasurable' on BOTH sides and blocked every vendored land
+// (task 1004584). It only stands down when the pre-merge base lacks the file
+// too, so a branch that DELETES fitness.js from the core is still measured
+// (and blocked as unmeasurable) rather than waved through.
+function gateApplies(repoRoot, baseSha) {
+  if (fs.existsSync(path.join(repoRoot, 'scripts', 'gds', 'fitness.js'))) return true;
+  if (!baseSha) return true;
+  try {
+    execFileSync('git', ['cat-file', '-e', `${baseSha}:scripts/gds/fitness.js`], {
+      cwd: repoRoot, stdio: 'ignore', shell: false,
+    });
+    return true; // the base had it — this merge removed it; measure (and block)
+  } catch (_) {
+    return false; // neither side carries the gate — nothing to run
+  }
+}
+
 function gateMergeResult({ repoRoot, baseSha, log = console.log }) {
+  if (!gateApplies(repoRoot, baseSha)) {
+    log('  fitness: this repo carries no scripts/gds/fitness.js (a vendored instance) — gate not applicable');
+    return { block: false, reason: 'not-applicable' };
+  }
   log('  fitness against post-merge state...');
   const mergeClean = runFitnessAt(repoRoot);
   const baseClean = mergeClean ? true : probeBaseClean(repoRoot, baseSha);
@@ -179,6 +204,7 @@ function gateMergeResult({ repoRoot, baseSha, log = console.log }) {
 
 module.exports = {
   fitnessOutcome,
+  gateApplies,
   gateMergeResult,
   gateMessage,
   mergeGateVerdict,

package/scripts/gds/ship-merge.js

@@ -31,7 +31,7 @@ const { runSmoke } = require('./ship-grade.js');
 const { gateMergeResult } = require('./ship-merge-gate.js');
 const { dbOnlyIgnoredNotice } = require('./ship-honesty.js');
 const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateCopyInventory, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
-const { REPO_ROOT } = require('./ship-state.js');
+const { MAIN_CHECKED_OUT, REPO_ROOT } = require('./ship-state.js');
 const { envPrefix } = require('../../src/instance-config');
 
 // zeroCommitVerdict — dbOnly is deliberately consulted ONLY at zero commits
@@ -265,9 +265,14 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
       // — the branch lands fine via a PR. Tagged PR-recoverable so autoMerge falls
       // back instead of parking the task at 'confirmed' unpaid. The reason +
       // nextStep are kept for the case where the fallback itself bails.
+      // task 1004584: when NO worktree holds main at all, say exactly that and
+      // how to fix it — REPO_ROOT is then the primary checkout by fallback, and
+      // "work in your own worktree" is advice the builder already followed.
       return landBailed(
-        `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`,
-        '/merge-mode',
+        MAIN_CHECKED_OUT
+          ? `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`
+          : `no worktree of this repo has main checked out (the main checkout ${REPO_ROOT} is on ${onMain}) — run \`git checkout main\` there, then re-ship`,
+        MAIN_CHECKED_OUT ? '/merge-mode' : `git -C "${REPO_ROOT}" checkout main && node scripts/gds/ship.js ${taskId}`,
         LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
       );
     }
@@ -448,6 +453,10 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
 
 module.exports = {
   autoMerge,
+  // task 1004584: the local merge leg on its own, so the vendored-instance
+  // regression test can read a bail's reason without the PR fallback (which
+  // needs an authed gh) swallowing it.
+  mergeLocally,
   // task 1004322: the held page tweak's publish-only path.
   publishHeld,
   // task 1002572 (PART 2): the pure recovery command for a ship run from main —

package/scripts/gds/ship-state.js

@@ -18,7 +18,7 @@
 'use strict';
 
 const path = require('node:path');
-const { findMainWorktree } = require('../../modules/lifecycle/ship-preflight');
+const { findMainWorktree, findPrimaryWorktree } = require('../../modules/lifecycle/ship-preflight');
 
 // The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
 // task 1002469). Cached module-level because the credits print + the completion
@@ -43,10 +43,43 @@ function getServerReward() {
 const GRADER_DIFF_CHAR_CAP = 250_000;
 const GRADER_TIMEOUT_MS = 240_000; // 4 min — Opus on a big diff with Read tool calls
 
-// Where auto-merge runs — the worktree that has `main` checked out, not the
-// feature worktree this script lives in. Falls back to two-levels-up if we
-// can't ask git (e.g. fresh clone with no `main` worktree set up yet).
-const REPO_ROOT = findMainWorktree(__dirname) || path.resolve(__dirname, '..', '..');
+// TWO ROOTS, not one (task 1004584). In the core's own repo they are the same
+// folder, which is how a single REPO_ROOT served both jobs for so long. In a
+// VENDORED instance — the core installed as node_modules/@bongos/core — they are
+// not, and conflating them broke every land (mercury, core 1.21.20):
+//   CORE_ROOT     — where the core's own scripts live (the package dir). Every
+//                   core script ship spawns (smoke-gds.js, …) is addressed from
+//                   here, never by a cwd-relative path.
+//   INSTANCE_ROOT — the instance repo's checkout that auto-merge runs in: the
+//                   worktree with `main` checked out (primary OR linked). With no
+//                   `main` anywhere it is the primary checkout, so the merge leg
+//                   bails with "on X, not main" — never the package dir, which is
+//                   not a repo and turned the bail into an ENOENT on the lock.
+// Git is asked from __dirname first (unchanged for the core repo), then from the
+// process cwd (the feature worktree ship is run from) as a backstop.
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+
+// resolveRoots — the pure resolution, with git injected so the vendored layouts
+// are unit-testable. `mainCheckedOut` is false when no worktree holds `main`;
+// ship-merge names that case in its bail instead of a generic "on X".
+function resolveRoots({
+  dirname = __dirname,
+  cwd = process.cwd(),
+  findMain = findMainWorktree,
+  findPrimary = findPrimaryWorktree,
+} = {}) {
+  const core = path.resolve(dirname, '..', '..');
+  const main = findMain(dirname) || findMain(cwd);
+  if (main) return { coreRoot: core, instanceRoot: main, mainCheckedOut: true };
+  const primary = findPrimary(dirname) || findPrimary(cwd);
+  return { coreRoot: core, instanceRoot: primary || core, mainCheckedOut: false };
+}
+
+const { instanceRoot: INSTANCE_ROOT, mainCheckedOut: MAIN_CHECKED_OUT } = resolveRoots();
+// The historical name every ship phase imports. It always meant "the checkout
+// auto-merge runs in", i.e. the instance root — kept as an alias so the phases
+// that only ever wanted that do not churn.
+const REPO_ROOT = INSTANCE_ROOT;
 
 // Sound playback is COSMETIC — the ship pipeline must NEVER depend on it. Guard
 // the require so a missing/broken player (e.g. .claude/sounds/ absent on a fresh
@@ -68,6 +101,10 @@ module.exports = {
   GRADER_DIFF_CHAR_CAP,
   GRADER_TIMEOUT_MS,
   REPO_ROOT,
+  CORE_ROOT,
+  INSTANCE_ROOT,
+  MAIN_CHECKED_OUT,
+  resolveRoots,
   playSound,
   BEHIND_MAIN_LIMIT,
 };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.61'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.62'; // 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('discord'); log.info('mounted');

package/tests/merge_lock.mjs

@@ -9,6 +9,7 @@
 
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -292,6 +293,63 @@ test('recoverWorktree: clean reclaim → no churn (no abort, no reset)', () => {
   }
 });
 
+// ---- linked worktrees (task 1004584) ----
+// When `main` is checked out in a LINKED worktree, <root>/.git is a FILE, so the
+// old <root>/.git/otb-automerge.lock was ENOENT on every acquire. The lock now
+// lives in the common git dir — the same file from every worktree.
+
+function realRepoWithLinkedWorktree() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-mergelock-linked-'));
+  const run = (cmd) => execSync(cmd, { cwd: dir, stdio: 'ignore' });
+  run('git init -q -b trunk');
+  run('git config user.email t@t.t');
+  run('git config user.name t');
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'x\n');
+  run('git add a.txt');
+  run('git commit -q -m init');
+  const linked = path.join(dir, 'wt-main');
+  run(`git worktree add -q -b main "${linked}"`);
+  return { dir, linked };
+}
+
+test('lockPath: from a linked worktree, resolves to the COMMON git dir (same file as the primary)', () => {
+  const { dir, linked } = realRepoWithLinkedWorktree();
+  try {
+    assert.ok(fs.statSync(path.join(linked, '.git')).isFile(), 'precondition: .git is a gitdir pointer file');
+    assert.equal(
+      fs.realpathSync.native(path.dirname(lock.lockPath(linked))),
+      fs.realpathSync.native(path.join(dir, '.git')),
+    );
+    assert.equal(path.basename(lock.lockPath(linked)), 'otb-automerge.lock');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('acquire/release: work from a linked main worktree, and the primary sees the hold', () => {
+  const { dir, linked } = realRepoWithLinkedWorktree();
+  try {
+    assert.equal(lock.acquire(linked, { waitMs: 0 }), true);
+    assert.equal(lock.readLock(dir).pid, process.pid, 'the primary must see the hold the linked worktree took');
+    assert.equal(lock.acquire(dir, { waitMs: 0, sleep: () => {} }), false, 'a second holder from the primary must be refused');
+    lock.release(linked);
+    assert.equal(lock.readLock(dir), null);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('indexLockPath: a linked worktree keeps its index.lock in its OWN git dir', () => {
+  const { dir, linked } = realRepoWithLinkedWorktree();
+  try {
+    const p = lock.indexLockPath(linked);
+    assert.equal(path.basename(p), 'index.lock');
+    assert.match(p.replace(/\\/g, '/'), /\.git\/worktrees\/wt-main\/index\.lock$/);
+  } finally {
+    cleanup(dir);
+  }
+});
+
 // ---- runner ----
 
 let pass = 0;

package/tests/ship_merge_gate.mjs

@@ -17,6 +17,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -170,3 +171,65 @@ test('an unmeasurable base blocks rather than waving the ship through', () => {
   // it could not measure, and null blocks.
   assert.equal(gate.mergeGateVerdict({ mergeClean: false, baseClean: null }).block, true);
 });
+
+// ---- gateApplies (task 1004584) ----
+// A VENDORED instance (core under node_modules/@bongos/core) carries no
+// scripts/gds/fitness.js of its own, so both sides read 'unmeasurable' and every
+// vendored land was blocked. The gate stands down ONLY when the base lacked the
+// file too — a branch that deletes fitness.js from the core is still measured.
+function gitRepo(withFitness) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'merge-gate-applies-'));
+  const run = (cmd) => execSync(cmd, { cwd: dir, stdio: 'ignore' });
+  run('git init -q -b main');
+  run('git config user.email t@t.t');
+  run('git config user.name t');
+  fs.writeFileSync(path.join(dir, 'README.md'), 'x\n');
+  if (withFitness) {
+    fs.mkdirSync(path.join(dir, 'scripts', 'gds'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'scripts', 'gds', 'fitness.js'), 'process.exit(0);\n');
+  }
+  run('git add -A');
+  run('git commit -q -m base');
+  const baseSha = execSync('git rev-parse HEAD', { cwd: dir, encoding: 'utf8' }).trim();
+  return { dir, baseSha };
+}
+
+test('gateApplies: a repo that carries fitness.js is always gated', () => {
+  const { dir, baseSha } = gitRepo(true);
+  try {
+    assert.equal(gate.gateApplies(dir, baseSha), true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('gateApplies: a vendored instance (no fitness.js on either side) stands the gate down', () => {
+  const { dir, baseSha } = gitRepo(false);
+  try {
+    assert.equal(gate.gateApplies(dir, baseSha), false);
+    const verdict = gate.gateMergeResult({ repoRoot: dir, baseSha, log: () => {} });
+    assert.deepEqual(verdict, { block: false, reason: 'not-applicable' });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('gateApplies: a merge that DELETES fitness.js from a gated base is still measured (and blocked)', () => {
+  const { dir, baseSha } = gitRepo(true);
+  try {
+    fs.rmSync(path.join(dir, 'scripts', 'gds', 'fitness.js'));
+    execSync('git commit -q -am "drop the gate"', { cwd: dir, stdio: 'ignore' });
+    assert.equal(gate.gateApplies(dir, baseSha), true, 'the base had the gate, so its removal must not wave the merge through');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('gateApplies: with no base sha it cannot prove the gate was never there → gated', () => {
+  const { dir } = gitRepo(false);
+  try {
+    assert.equal(gate.gateApplies(dir, null), true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/tests/ship_preflight.mjs

@@ -13,7 +13,7 @@ import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const {
-  parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan,
+  parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, findPrimaryWorktree, closeoutPlan,
   untrackedPaths, untrackedLeftBehind, untrackedWarningLines,
 } = require('../modules/lifecycle/ship-preflight.js');
 // task 1001436: the preflight step itself + the ship-input resolver it is handed.
@@ -318,6 +318,51 @@ test('findMainWorktree: returns null outside any git repo', () => {
   }
 });
 
+// ---- findPrimaryWorktree (task 1004584) ----
+// The merge target when NO worktree has main: the primary checkout, whatever it
+// is on — so ship can say "check out main there" instead of falling back to the
+// core package dir (a vendored instance's node_modules/@bongos/core).
+
+test('findPrimaryWorktree: from a linked worktree, returns the primary checkout even when it is off main', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-primarywt-'));
+  try {
+    execSync('git init -q -b trunk', { cwd: tmp });
+    execSync('git config user.email t@t.t && git config user.name t', { cwd: tmp });
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp });
+    execSync('git branch feature', { cwd: tmp });
+    const wt = path.join(tmp, 'linked');
+    execSync(`git worktree add -q "${wt}" feature`, { cwd: tmp });
+
+    assert.equal(findMainWorktree(wt), null, 'precondition: no worktree is on main');
+    const found = findPrimaryWorktree(wt);
+    assert.ok(found, 'expected a path');
+    assert.equal(fs.realpathSync.native(found), fs.realpathSync.native(tmp));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('findPrimaryWorktree: a BARE primary is not a checkout to merge in → null', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-primarywt-bare-'));
+  try {
+    const bare = path.join(tmp, 'repo.git');
+    execSync(`git init -q --bare -b main "${bare}"`, { cwd: tmp });
+    assert.equal(findPrimaryWorktree(bare), null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('findPrimaryWorktree: returns null outside any git repo', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-primarywt-nogit-'));
+  try {
+    assert.equal(findPrimaryWorktree(tmp), null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
 // ---- closeoutPlan (task 932) ----
 
 test('closeoutPlan: clean tree → clean:true, no leftover', () => {

package/tests/ship_vendored_instance.mjs

@@ -0,0 +1,259 @@
+// tests/ship_vendored_instance.mjs
+//
+// task 1004584 — `bongos ship` could not land a task in a VENDORED instance (the
+// core installed as node_modules/@bongos/core). Reported from mercury on core
+// 1.21.20, Windows, laptop deploy mode. One REPO_ROOT meant both "the instance
+// repo" (merge target, lock) and "where the core's scripts live" (smoke), and in a
+// vendored instance those are two different folders:
+//
+//   1. no worktree had `main` checked out → REPO_ROOT fell back to the package
+//      dir → the merge lock opened node_modules/@bongos/core/.git/… → ENOENT;
+//   2. `main` checked out in a LINKED worktree → <root>/.git is a FILE → the same
+//      ENOENT on the lock;
+//   3. `main` in the primary checkout → the merge succeeded, then the post-merge
+//      smoke ran `node scripts/gds/smoke-gds.js` cwd-relative to the instance →
+//      MODULE_NOT_FOUND → ship reset main and the task stuck at `confirmed`.
+//
+// This builds the real layout and runs ship's real local merge leg in it: a bare
+// origin, an instance clone whose node_modules/@bongos/core holds a COPY of the
+// core files ship loads, a per-task linked worktree on the task branch, and a
+// child process that requires the vendored copy of ship-merge.js and calls
+// mergeLocally from the feature worktree — the shape `bongos ship` runs in.
+//
+// What is stubbed, and why: smoke-gds.js (the real one probes a live server — the
+// stub only proves it was found at the CORE path and run), and cli-lib's
+// cliClient (the land-proof POST). The deploy mode is pinned to laptop by env so
+// no gh probe runs. Everything else — git, the lock, the fitness gate, the push
+// to origin — is the real code against real repos.
+//
+// Run:  node tests/ship_vendored_instance.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const TASK = 4242;
+const BRANCH = `task-${TASK}`;
+
+// The core as an install would carry it: every tracked file under the paths the
+// package ships code from (media skipped — nothing on the merge leg reads it).
+// Read from the working tree, so the test exercises the code being changed.
+// Built ONCE into a template and copied into each fixture.
+const CORE_FILES = execFileSync('git', ['ls-files', '-z', 'src', 'scripts', 'modules', 'config', 'package.json', '.claude/sounds'], {
+  cwd: REPO, encoding: 'utf8',
+}).split('\0').filter((f) => f && !/\.(png|jpe?g|webp|gif|svg|mp3|wav|ogg)$/i.test(f) && fs.existsSync(path.join(REPO, f)));
+const CORE_TEMPLATE = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-vendored-core-'));
+for (const rel of CORE_FILES) {
+  const dst = path.join(CORE_TEMPLATE, rel);
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(path.join(REPO, rel), dst);
+}
+
+// A git env that ignores the developer's own config (hooks, signing, drivers).
+const emptyCfg = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-vendored-cfg-')), 'gitconfig');
+fs.writeFileSync(emptyCfg, '');
+const GIT_ENV = {
+  ...process.env,
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: emptyCfg,
+  GIT_AUTHOR_NAME: 'Vendored Test', GIT_AUTHOR_EMAIL: 'vendored@example.test',
+  GIT_COMMITTER_NAME: 'Vendored Test', GIT_COMMITTER_EMAIL: 'vendored@example.test',
+};
+function git(cwd, ...args) {
+  return execFileSync('git', args, { cwd, env: GIT_ENV, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function writeFile(p, body) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+}
+
+// Build one fixture. `mainAt`: 'primary' | 'linked' | 'none'.
+function buildFixture(mainAt) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `bongos-vendored-${mainAt}-`));
+  const origin = path.join(root, 'origin.git');
+  const inst = path.join(root, 'instance');
+  git(root, 'init', '--bare', '-b', 'main', origin);
+  git(root, 'clone', '-q', origin, inst);
+  git(inst, 'checkout', '-q', '-b', 'main');
+  writeFile(path.join(inst, '.gitignore'), 'node_modules/\n');
+  writeFile(path.join(inst, 'README.md'), '# a vendored instance\n');
+  git(inst, 'add', '.');
+  git(inst, 'commit', '-q', '-m', 'instance: initial');
+  git(inst, 'push', '-q', '-u', 'origin', 'main');
+
+  // The vendored core, where `npm install` would put it.
+  const core = path.join(inst, 'node_modules', '@bongos', 'core');
+  fs.cpSync(CORE_TEMPLATE, core, { recursive: true });
+  // The smoke stub records WHERE it was run from — the bug was it not being found.
+  writeFile(path.join(core, 'scripts', 'gds', 'smoke-gds.js'),
+    "require('fs').writeFileSync(process.env.SMOKE_MARKER, JSON.stringify({ script: __filename, cwd: process.cwd() }));\n");
+
+  // The task's own worktree + branch, carrying one commit.
+  const feature = path.join(root, 'wt-task');
+  git(inst, 'worktree', 'add', '-q', '-b', BRANCH, feature, 'main');
+  writeFile(path.join(feature, 'feature.txt'), 'the work\n');
+  git(feature, 'add', 'feature.txt');
+  git(feature, 'commit', '-q', '-m', 'the task work');
+
+  // Where `main` lives.
+  let mainDir = inst;
+  if (mainAt !== 'primary') {
+    git(inst, 'checkout', '-q', '-b', 'scratch'); // the primary checkout leaves main
+    if (mainAt === 'linked') {
+      mainDir = path.join(root, 'wt-main');
+      git(inst, 'worktree', 'add', '-q', mainDir, 'main');
+    } else {
+      mainDir = null;
+    }
+  }
+  return { root, origin, inst, core, feature, mainDir };
+}
+
+// Run ship's local merge leg from the vendored copy, in the feature worktree.
+function runMergeLeg(fx) {
+  const marker = path.join(fx.root, 'smoke-ran.json');
+  const runner = path.join(fx.root, 'run-merge.js');
+  fs.writeFileSync(runner, `
+    const path = require('path');
+    const core = ${JSON.stringify(fx.core)};
+    const cli = require(path.join(core, 'scripts', 'gds', 'cli-lib.js'));
+    cli.cliClient = async () => ({ tasks: { postTasksIdAttestGate: async () => ({ ok: true, status: 200, data: { tip_recorded: true } }) } });
+    const state = require(path.join(core, 'scripts', 'gds', 'ship-state.js'));
+    const { mergeLocally } = require(path.join(core, 'scripts', 'gds', 'ship-merge.js'));
+    mergeLocally(${TASK}, 'vendored land').then(
+      (o) => { console.log('ROOTS ' + JSON.stringify({ core: state.CORE_ROOT, instance: state.INSTANCE_ROOT, main: state.MAIN_CHECKED_OUT })); console.log('RESULT ' + JSON.stringify(o)); },
+      (e) => { console.log('THREW ' + JSON.stringify({ code: e.code, message: e.message })); process.exitCode = 1; },
+    );
+  `);
+  const env = { ...GIT_ENV, SMOKE_MARKER: marker, BONGOS_DEPLOY_MODE: 'laptop'};
+  for (const k of ['BONGOS_DEPLOY_SSH_TARGET', 'OTB_DEPLOY_SSH_TARGET', 'BONGOS_DEPLOY_HEALTHZ_URL', 'OTB_DEPLOY_HEALTHZ_URL']) delete env[k];
+  const r = spawnSync(process.execPath, [runner], { cwd: fx.feature, env, encoding: 'utf8', timeout: 120000 });
+  const out = `${r.stdout || ''}\n${r.stderr || ''}`;
+  const line = (tag) => {
+    const l = out.split('\n').find((s) => s.startsWith(`${tag} `));
+    return l ? JSON.parse(l.slice(tag.length + 1)) : null;
+  };
+  return { out, result: line('RESULT'), roots: line('ROOTS'), threw: line('THREW'), marker };
+}
+
+// The two failure signatures from the report. (Not a blanket ENOENT match: ship's
+// best-effort doc regenerators also run on this leg and grumble about the core's
+// docs/ folder in a vendored layout — non-fatal by design, and not this bug.)
+const LOCK_ENOENT = /ENOENT[^\n]*otb-automerge\.lock/;
+const SMOKE_MISSING = /Cannot find module[^\n]*smoke-gds/;
+const same = (a, b) => path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+const commonLock = (fx) => path.join(fx.inst, '.git', 'otb-automerge.lock');
+
+let passed = 0;
+let failed = 0;
+const fixtures = [];
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+function assertLanded(fx, run) {
+  assert.equal(run.threw, null, `the merge leg threw: ${JSON.stringify(run.threw)}\n${run.out}`);
+  assert.ok(run.result, `no result line:\n${run.out}`);
+  assert.equal(run.result.ok, true, `expected a land, got ${JSON.stringify(run.result)}\n${run.out}`);
+  assert.ok(!LOCK_ENOENT.test(run.out), `the merge lock hit ENOENT:\n${run.out}`);
+  assert.ok(!SMOKE_MISSING.test(run.out), `smoke-gds.js was not found:\n${run.out}`);
+  // the smoke ran — from the CORE package, with the instance checkout as cwd
+  const smoke = JSON.parse(fs.readFileSync(run.marker, 'utf8'));
+  assert.ok(same(path.dirname(smoke.script), path.join(fx.core, 'scripts', 'gds')), `smoke ran from ${smoke.script}`);
+  assert.ok(same(smoke.cwd, fx.mainDir), `smoke cwd was ${smoke.cwd}, expected the main checkout ${fx.mainDir}`);
+  // the work is on origin/main, and the lock is gone
+  git(fx.inst, 'fetch', '-q', 'origin');
+  const files = git(fx.inst, 'ls-tree', '--name-only', 'origin/main');
+  assert.ok(files.split('\n').includes('feature.txt'), `origin/main lacks the task's file:\n${files}`);
+  assert.ok(!fs.existsSync(commonLock(fx)), 'the merge lock was left behind');
+}
+
+console.log('ship merge leg in a vendored instance (task 1004584)');
+
+// ---- resolveRoots, pure: git answers injected, no repo needed ----
+const { resolveRoots } = require(path.join(REPO, 'scripts', 'gds', 'ship-state.js'));
+const VENDORED_DIR = path.join('/inst', 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+const VENDORED_CORE = path.resolve(VENDORED_DIR, '..', '..'); // drive-qualified on Windows, as resolveRoots returns it
+
+await t('resolveRoots: CORE_ROOT is the package dir, INSTANCE_ROOT the worktree with main', () => {
+  const r = resolveRoots({ dirname: VENDORED_DIR, cwd: '/wt-task', findMain: () => '/wt-main', findPrimary: () => '/inst' });
+  assert.deepEqual(r, { coreRoot: VENDORED_CORE, instanceRoot: '/wt-main', mainCheckedOut: true });
+});
+
+await t('resolveRoots: asks from the script dir first, then the process cwd', () => {
+  const asked = [];
+  const r = resolveRoots({
+    dirname: VENDORED_DIR, cwd: '/wt-task',
+    findMain: (d) => { asked.push(d); return d === '/wt-task' ? '/inst' : null; },
+    findPrimary: () => { throw new Error('primary must not be consulted when main was found'); },
+  });
+  assert.deepEqual(asked, [VENDORED_DIR, '/wt-task']);
+  assert.equal(r.instanceRoot, '/inst');
+});
+
+await t('resolveRoots: no main anywhere → the PRIMARY checkout, flagged, never the package dir', () => {
+  const r = resolveRoots({ dirname: VENDORED_DIR, cwd: '/wt-task', findMain: () => null, findPrimary: () => '/inst' });
+  assert.deepEqual(r, { coreRoot: VENDORED_CORE, instanceRoot: '/inst', mainCheckedOut: false });
+});
+
+await t('resolveRoots: git cannot answer at all → the package dir (the core repo itself, pre-git)', () => {
+  const r = resolveRoots({ dirname: VENDORED_DIR, cwd: '/x', findMain: () => null, findPrimary: () => null });
+  assert.deepEqual(r, { coreRoot: VENDORED_CORE, instanceRoot: VENDORED_CORE, mainCheckedOut: false });
+});
+
+// ---- the real merge leg, in a real vendored layout ----
+
+await t('main in the PRIMARY checkout: lands, smoke found under the core package', () => {
+  const fx = buildFixture('primary'); fixtures.push(fx);
+  const run = runMergeLeg(fx);
+  assert.ok(same(run.roots.core, fx.core), `CORE_ROOT ${run.roots.core}`);
+  assert.ok(same(run.roots.instance, fx.inst), `INSTANCE_ROOT ${run.roots.instance}`);
+  assertLanded(fx, run);
+});
+
+await t('main in a LINKED worktree: lands, lock lives in the common git dir', () => {
+  const fx = buildFixture('linked'); fixtures.push(fx);
+  const run = runMergeLeg(fx);
+  assert.ok(same(run.roots.instance, fx.mainDir), `INSTANCE_ROOT ${run.roots.instance}, expected ${fx.mainDir}`);
+  assert.equal(run.roots.main, true);
+  assertLanded(fx, run);
+  // and the lock path ship used is the one the merge-lock CLI uses from anywhere
+  const lock = require(path.join(fx.core, 'modules', 'lifecycle', 'merge-lock.js'));
+  assert.ok(same(lock.lockPath(fx.mainDir), commonLock(fx)), `lockPath(linked main) = ${lock.lockPath(fx.mainDir)}`);
+  assert.ok(same(lock.lockPath(fx.inst), commonLock(fx)));
+});
+
+await t('NO worktree has main: a clear bail naming the fix, never ENOENT, nothing pushed', () => {
+  const fx = buildFixture('none'); fixtures.push(fx);
+  const run = runMergeLeg(fx);
+  assert.equal(run.threw, null, `the merge leg threw: ${JSON.stringify(run.threw)}\n${run.out}`);
+  assert.ok(!LOCK_ENOENT.test(run.out), `the merge lock hit ENOENT:\n${run.out}`);
+  assert.equal(run.roots.main, false);
+  assert.ok(same(run.roots.instance, fx.inst), `fell back to ${run.roots.instance}, not the primary checkout`);
+  assert.ok(!same(run.roots.instance, fx.core), 'fell back to the core package dir');
+  assert.equal(run.result.ok, false);
+  assert.match(run.result.reason, /no worktree of this repo has main checked out/);
+  assert.match(run.result.nextStep, /checkout main/);
+  assert.ok(!fs.existsSync(run.marker), 'smoke ran although nothing was merged');
+  const files = git(fx.inst, 'ls-tree', '--name-only', 'origin/main');
+  assert.ok(!files.split('\n').includes('feature.txt'), 'origin/main changed on a bail');
+  assert.ok(!fs.existsSync(commonLock(fx)), 'the merge lock was left behind');
+});
+
+for (const fx of fixtures) {
+  try { fs.rmSync(fx.root, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+}
+for (const dir of [path.dirname(emptyCfg), CORE_TEMPLATE]) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);