@bongos/core 1.19.271 → 1.19.272

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.271",
-  "core_contract": "1.19.271",
-  "source_commit": "eeda0eaa782f69e7843920d6ba6027133ffaf889",
+  "core_version": "1.19.272",
+  "core_contract": "1.19.272",
+  "source_commit": "1ddcabf5f0c390df6bf2db273da05131d7c5555d",
   "source_ref": "HEAD",
-  "built_at": "2026-08-21T01:46:51.577Z",
+  "built_at": "2026-08-21T01:58:30.188Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 318,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1709,
-  "tree_sha256": "552e1f0cff6b4913becf9550cc1d368053a56c1022f8ed7c6f373f3028ae69fe",
+  "tree_sha256": "7e96896dddb704ffea439416bad0d7ba6ad81ead9d79ed34212de45a2df50f71",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4472,12 +4472,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "289d96460bbde068311ad18505bfca432c201de66af827055b8ce2ed31ac81be"
+      "sha256": "b77fc259ddf810fa62ea5e745751449a5dc49847311ddf4199a997df9dcd06ed"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2ec9e8fb9b470df255d1de4adc52597ca9f6dac5a301adbdecd0cf249547938d"
+      "sha256": "725dd9f78abd547ef32e6d9a9b886ecf447fa1bd62a747df49943e2a1e047949"
     },
     {
       "path": "public-docs/index.html",
@@ -4997,7 +4997,7 @@
     {
       "path": "scripts/gds/context-pack.js",
       "mode": "0000644",
-      "sha256": "8ca6ee391837d7e1a45e69fc62c4a051f5e3d6060db507cdcbc7a343e2b03bd3"
+      "sha256": "caa5dd1628b00569a5593964f1831641ac12c9a85b8ec132964a1baf67c77350"
     },
     {
       "path": "scripts/gds/control-manifest.js",
@@ -6122,7 +6122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "bc19b591ad45c693adebe95bf3df3e480b174bac7b109df27dd45fb088e78537"
+      "sha256": "67c1067ae657f640493d8bfa3f7001ce64f416d0176afd6e84be387349a9578e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6652,7 +6652,7 @@
     {
       "path": "tests/context_pack.mjs",
       "mode": "0000644",
-      "sha256": "55bd70efd8067e39d6220d14f78c743ce80d8a8ff37988acf00136b5108dc004"
+      "sha256": "09f956c01f169ab7384204a5d43deefa3e57a7d57924072dfa8215f0942c2513"
     },
     {
       "path": "tests/control_manifest.mjs",

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.271",
+  "version": "1.19.272",
   "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/context-pack.js

@@ -25,6 +25,7 @@
 //     and must NEVER throw or block a claim.
 
 const { execFileSync } = require('node:child_process');
+const path = require('node:path');
 
 // The live validators. task-classifier is a pure module (no DB, no network),
 // so importing it from a CLI is safe — same precedent as next-number.js reading
@@ -61,14 +62,70 @@ function apiContract() {
 
 // Resolve the absolute worktree root. runGit throws → fall back to cwd (which is
 // still better than nothing; the builder at least sees the directory they're in).
+//
+// task 1002573: also resolve WHICH KIND of tree this is. The pack used to print
+// the root and then assert "this is the session's tree, not the main checkout"
+// unconditionally — so claiming from the main checkout produced a sentence that
+// was flatly false, and the tooling told the builder to do the one thing that
+// makes the ship unmergeable (ship.js's local auto-merge has nowhere to merge
+// INTO when the receiving tree is the one holding the branch — task 1002572).
+//
+// The signal is the same one claim.js detectWorktreeName() already uses: in the
+// main checkout `--git-dir` and `--git-common-dir` resolve to the same path; in a
+// linked worktree they diverge. isMainCheckout is TRI-STATE — null means "could
+// not tell", and the guidance hedges rather than guessing, because this is a UX
+// surface that must never block a claim.
 function resolveWorktreeRoot({ runGit, cwd }) {
+  let root = null;
+  let degraded = false;
   try {
-    const root = runGit(['rev-parse', '--show-toplevel']).trim();
-    if (root) return { root, degraded: false };
+    root = runGit(['rev-parse', '--show-toplevel']).trim() || null;
   } catch {
     /* fall through */
   }
-  return { root: cwd, degraded: true };
+  if (!root) {
+    root = cwd;
+    degraded = true;
+  }
+  let isMainCheckout = null;
+  try {
+    const gitDir = runGit(['rev-parse', '--git-dir']).trim();
+    const commonDir = runGit(['rev-parse', '--git-common-dir']).trim();
+    if (gitDir && commonDir) {
+      // Both can come back RELATIVE ('.git' in the main checkout), so resolve
+      // against the tree we are describing rather than the process cwd.
+      const base = degraded ? cwd : root;
+      isMainCheckout = path.resolve(base, gitDir) === path.resolve(base, commonDir);
+    }
+  } catch {
+    /* unknown — the guidance hedges */
+  }
+  return { root, degraded, isMainCheckout };
+}
+
+// task 1002573: the guidance line(s) for the resolved tree. Pure, and exported so
+// the "these two must not read the same" property is unit-tested rather than
+// eyeballed. Returns an array of lines (the warning needs more than one).
+function worktreeGuidance(worktree) {
+  const isMain = worktree ? worktree.isMainCheckout : null;
+  if (isMain === true) {
+    return [
+      '    ⚠ THIS IS THE MAIN CHECKOUT — not a per-claim worktree.',
+      '      Working the claim here parks the main checkout off `main`, and the local',
+      '      auto-merge then has nowhere to merge INTO: the ship strands at `confirmed`',
+      '      until the server reconciler (or /merge-mode) catches it. Automation that',
+      '      resets this tree mid-session can also take your uncommitted work with it.',
+      '      Prefer a worktree:  git worktree add .claude/worktrees/<name> -b <branch>',
+    ];
+  }
+  if (isMain === false) {
+    return ['    → edit files + run git HERE. This is the session\'s tree, not the main checkout (the #1 wrong-path footgun).'];
+  }
+  return [
+    '    → edit files + run git HERE.',
+    '    ⚠ Could not tell whether this is the main checkout or a linked worktree. If it is',
+    '      the main checkout, prefer a per-claim worktree — see the warning in /builder-claim.',
+  ];
 }
 
 // OS toolchain facts the corpus showed sessions tripping over. `which` returns a
@@ -148,7 +205,7 @@ function formatContextPack(pack) {
   const lines = [];
   lines.push('🧭 Context pack (so this session starts knowing, not hunting):');
   lines.push(`  Worktree root:  ${worktree.root}`);
-  lines.push('    → edit files + run git HERE. This is the session\'s tree, not the main checkout (the #1 wrong-path footgun).');
+  lines.push(...worktreeGuidance(worktree)); // task 1002573 — tells the TRUTH about which tree this is
   if (worktree.degraded) {
     lines.push('    ⚠ git toplevel unreadable — showing cwd; double-check before writing.');
   }
@@ -217,6 +274,7 @@ module.exports = {
   API_PREFIX,
   apiContract,
   resolveWorktreeRoot,
+  worktreeGuidance, // task 1002573
   osFacts,
   normalizeClaims,
   buildContextPack,

package/src/module-api.js

@@ -969,8 +969,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.269 with no explicit bump. run 32428659648. (task 1002620)
 //   1.19.271 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.270 with no explicit bump. run 32437463473. (task 1002620)
+//   1.19.272 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.271 with no explicit bump. run 32438140524. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.271'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.272'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/context_pack.mjs

@@ -17,6 +17,7 @@ const require = createRequire(import.meta.url);
 const {
   apiContract,
   resolveWorktreeRoot,
+  worktreeGuidance,
   osFacts,
   normalizeClaims,
   buildContextPack,
@@ -177,6 +178,104 @@ t('buildContextPack: composes worktree + claims + api + os from injected runners
   assert.equal(pack.os.platform, 'linux');
 });
 
+// ---- task 1002573: which tree is this, and does the guidance tell the truth ----
+//
+// The pack used to print the root and then assert "this is the session's tree,
+// not the main checkout" UNCONDITIONALLY. Claiming from the main checkout
+// therefore produced a flatly false sentence, and the tooling told the builder to
+// do the one thing that makes the ship unmergeable (the receiving tree is the one
+// holding the branch — task 1002572). The signal was already computed elsewhere
+// (claim.js detectWorktreeName) and simply never surfaced.
+//
+// Stubs mirror real git: in the MAIN checkout `--git-dir` and `--git-common-dir`
+// both answer '.git'; in a LINKED worktree they diverge.
+const gitMain = (args) => {
+  const a = args.join(' ');
+  if (a.includes('--show-toplevel')) return '/repo\n';
+  if (a.includes('--git-common-dir')) return '.git\n';
+  if (a.includes('--git-dir')) return '.git\n';
+  throw new Error(`unexpected git call: ${a}`);
+};
+const gitLinked = (args) => {
+  const a = args.join(' ');
+  if (a.includes('--show-toplevel')) return '/repo/.claude/worktrees/task-1\n';
+  if (a.includes('--git-common-dir')) return '/repo/.git\n';
+  if (a.includes('--git-dir')) return '/repo/.git/worktrees/task-1\n';
+  throw new Error(`unexpected git call: ${a}`);
+};
+
+t('resolveWorktreeRoot: identical git-dir and common-dir ⇒ the MAIN checkout', () => {
+  const r = resolveWorktreeRoot({ runGit: gitMain, cwd: '/elsewhere' });
+  assert.equal(r.root, '/repo');
+  assert.equal(r.degraded, false);
+  assert.equal(r.isMainCheckout, true);
+});
+
+t('resolveWorktreeRoot: diverging git-dir ⇒ a LINKED worktree', () => {
+  const r = resolveWorktreeRoot({ runGit: gitLinked, cwd: '/elsewhere' });
+  assert.equal(r.root, '/repo/.claude/worktrees/task-1');
+  assert.equal(r.isMainCheckout, false);
+});
+
+t('resolveWorktreeRoot: unresolvable tree kind is UNKNOWN (null), never a guess', () => {
+  // toplevel works, but the dir probes fail — the kind must not default to either.
+  const partial = (args) => {
+    if (args.join(' ').includes('--show-toplevel')) return '/repo\n';
+    throw new Error('no');
+  };
+  assert.equal(resolveWorktreeRoot({ runGit: partial, cwd: '/c' }).isMainCheckout, null);
+  // And a total git failure still degrades to cwd without throwing.
+  const dead = resolveWorktreeRoot({ runGit: () => { throw new Error('no git'); }, cwd: '/here' });
+  assert.equal(dead.root, '/here');
+  assert.equal(dead.degraded, true);
+  assert.equal(dead.isMainCheckout, null);
+});
+
+t('worktreeGuidance: the main-checkout text DIFFERS from the worktree text', () => {
+  // The task's own verify criterion: the guidance must not read the same in both
+  // trees. Anything else means the builder is being told the same thing whether
+  // it is true or not.
+  const mainText = worktreeGuidance({ isMainCheckout: true }).join('\n');
+  const wtText = worktreeGuidance({ isMainCheckout: false }).join('\n');
+  assert.notEqual(mainText, wtText);
+  // The old, wrong sentence must NOT appear in the main checkout.
+  assert.doesNotMatch(mainText, /not the main checkout/i,
+    'the main checkout must never be told it is not the main checkout');
+  assert.match(wtText, /not the main checkout/i, 'a real worktree keeps the original line');
+});
+
+t('worktreeGuidance: the main-checkout warning names the CONSEQUENCE, not just the fact', () => {
+  const text = worktreeGuidance({ isMainCheckout: true }).join('\n');
+  assert.match(text, /MAIN CHECKOUT/);
+  assert.match(text, /auto-merge/i, 'says what breaks');
+  assert.match(text, /confirmed/, 'and where the ship strands');
+  assert.match(text, /git worktree add/, 'and gives the command that avoids it');
+});
+
+t('worktreeGuidance: unknown tree kind hedges instead of asserting either', () => {
+  for (const w of [{ isMainCheckout: null }, {}, null, undefined]) {
+    const text = worktreeGuidance(w).join('\n');
+    assert.match(text, /Could not tell/i, `hedged for ${JSON.stringify(w)}`);
+    assert.doesNotMatch(text, /THIS IS THE MAIN CHECKOUT/, 'never assert main');
+    assert.doesNotMatch(text, /This is the session's tree/, 'never assert worktree');
+  }
+});
+
+t('formatContextPack: renders the main-checkout WARNING when that is the truth', () => {
+  const pack = buildContextPack({
+    activeClaims: [{ task_id: 942, title: 'x' }],
+    currentTaskId: 942,
+    cwd: '/fallback',
+    platform: 'linux',
+    runGit: gitMain,
+    runWhich: fakeWhich({ timeout: '/usr/bin/timeout', psql: '/usr/bin/psql' }),
+  });
+  const out = formatContextPack(pack);
+  assert.match(out, /THIS IS THE MAIN CHECKOUT/);
+  assert.doesNotMatch(out, /not the main checkout/i);
+  assert.ok(!/undefined/.test(out), 'no undefined leaked into the rendered pack');
+});
+
 // ---- formatting ------------------------------------------------------------
 t('formatClaims: empty vs held, with the (this one) marker', () => {
   assert.equal(formatClaims([]), '(none held)');
@@ -194,16 +293,20 @@ t('formatOs: names the macOS no-timeout case in prose', () => {
 });
 
 t('formatContextPack: includes worktree root, prefix, a real kind, and warns the wrong-tree footgun', () => {
+  // task 1002573: uses a LINKED-worktree stub. It previously passed an
+  // args-ignoring stub, which returned the same path for every probe — i.e. the
+  // main checkout — while asserting the "not the main checkout" line. The test
+  // was encoding the bug.
   const pack = buildContextPack({
     activeClaims: [{ task_id: 942, title: 'x' }],
     currentTaskId: 942,
     cwd: '/fallback',
     platform: 'linux',
-    runGit: () => '/work/tree\n',
+    runGit: gitLinked,
     runWhich: fakeWhich({ timeout: '/usr/bin/timeout', psql: '/usr/bin/psql' }),
   });
   const out = formatContextPack(pack);
-  assert.match(out, /\/work\/tree/);
+  assert.match(out, /task-1/);
   assert.match(out, /\/api\/bongos/);
   assert.match(out, /feature/);          // a real kind from VALID_KINDS
   assert.match(out, /not the main checkout/i);