kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/__tests__/task-2281-singleton-readers.test.js

@@ -0,0 +1,64 @@
+// TASK_2281 — remaining singleton current_stream.json readers must not treat a foreign session as self.
+//   H  headless auto-claim guard (_isOwnClaimMarker): singleton names foreign live session == marker owner -> NOT self
+//   O  dispatch _getOwnConversationId: no env + singleton conv -> null; env -> env
+//   I  integration merge-lock owner (currentSessionId): unproven -> 'unknown'; hmap-proven -> boot_sid; release/heartbeat unaffected
+// Usage: node .formation/tools/__tests__/task-2281-singleton-readers.test.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const WT = path.resolve(__dirname, '..', '..', '..');
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2281_'));
+fs.mkdirSync(path.join(SB, '.kenaz/specialist/sessions'), { recursive: true });
+fs.mkdirSync(path.join(SB, '.formation'), { recursive: true });
+const stream = (sid, cid) => fs.writeFileSync(path.join(SB, '.kenaz/specialist/current_stream.json'),
+  JSON.stringify({ session_id: sid, pid: process.pid, ...(cid ? { conversation_id: cid } : {}) }));
+const hmap = (conv, sid) => fs.writeFileSync(path.join(SB, '.kenaz/specialist/sessions/hmap_' + conv + '.json'), JSON.stringify({ boot_sid: sid }));
+const setEnv = (conv) => { if (conv) process.env.CLAUDE_CODE_SESSION_ID = conv; else delete process.env.CLAUDE_CODE_SESSION_ID; };
+let pass = 0, fail = 0;
+const check = (name, cond, detail) => { console.log((cond ? 'PASS' : 'FAIL') + ' | ' + name + (cond ? '' : ' | ' + detail)); cond ? pass++ : fail++; };
+const log = console.log;
+const quiet = (fn) => { console.log = () => {}; try { return fn(); } finally { console.log = log; } };
+
+const dispatch = require(path.join(WT, '.formation/tools/dispatch.js'));
+const integ = require(path.join(WT, '.formation/tools/integration.js'));
+try {
+  // ── H: headless selfClaimed ──
+  stream('sF', 'convF'); setEnv('convMe'); // convMe unbound; singleton = foreign live F
+  const foreignConvMarker = { owner_session: 'sF', owner_conversation_id: 'convF' };
+  const foreignSidMarker = { owner_session: 'sF' };
+  check('H1 foreign conv-marker == singleton -> not self', dispatch._isOwnClaimMarker(foreignConvMarker, SB) === false, 'treated as self');
+  check('H2 foreign session-only marker == singleton -> not self', dispatch._isOwnClaimMarker(foreignSidMarker, SB) === false, 'treated as self');
+  hmap('convMe', 'sMe');
+  check('H3 control: proven own conv marker -> self', dispatch._isOwnClaimMarker({ owner_session: 'sMe', owner_conversation_id: 'convMe' }, SB) === true, 'not self');
+  check('H4 control: proven own session-only marker -> self', dispatch._isOwnClaimMarker({ owner_session: 'sMe' }, SB) === true, 'not self');
+  check('H5 control: other proven conv marker -> not self', dispatch._isOwnClaimMarker({ owner_session: 'sX', owner_conversation_id: 'convX' }, SB) === false, 'self');
+  setEnv(null);
+  check('H6 no env, singleton == marker -> not self (unproven)', dispatch._isOwnClaimMarker(foreignConvMarker, SB) === false, 'treated as self');
+
+  // ── O: _getOwnConversationId ──
+  check('O1 no env + singleton conv -> null', dispatch._getOwnConversationId(SB) === null, String(dispatch._getOwnConversationId(SB)));
+  setEnv('convEnv');
+  check('O2 control: env conv -> env conv', dispatch._getOwnConversationId(SB) === 'convEnv', String(dispatch._getOwnConversationId(SB)));
+
+  // ── I: merge-lock owner ──
+  const readL = () => JSON.parse(fs.readFileSync(integ.lockPath(SB), 'utf8'));
+  setEnv('convUnbound'); stream('sF', 'convF');
+  check('I1 unproven + foreign singleton -> owner unknown', integ.currentSessionId(SB) === 'unknown', integ.currentSessionId(SB));
+  setEnv('convMe');
+  check('I2 control: hmap-proven -> boot_sid', integ.currentSessionId(SB) === 'sMe', integ.currentSessionId(SB));
+  // holder's own heartbeat + release still work with owner 'unknown' (they key on pid)
+  setEnv('convUnbound');
+  integ.writeLock(SB, 'TASK_X');
+  check('I3 lock written with owner unknown', readL().owner_session === 'unknown', JSON.stringify(readL()));
+  const hb0 = readL().heartbeat_at;
+  const t = Date.now(); while (Date.now() - t < 15) { /* ensure ts advance */ }
+  integ.touchLockHeartbeat(SB);
+  check('I4 holder heartbeat still refreshes (unknown owner)', readL().heartbeat_at > hb0 && readL().owner_session === 'unknown', JSON.stringify(readL()));
+  check('I5 holder release still works (unknown owner)', quiet(() => integ.releaseLock(SB)) === true && !fs.existsSync(integ.lockPath(SB)), 'lock remained');
+} finally {
+  setEnv(null);
+  try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+console.log('---');
+console.log('RESULT: ' + pass + ' pass, ' + fail + ' fail');
+process.exit(fail ? 1 : 0);

package/core/.formation/tools/__tests__/task2030-worktree-node-modules.test.js

@@ -0,0 +1,221 @@
+'use strict';
+/**
+ * TASK_2030 — Formation/cross-project worktrees (utils.createWorktree) got
+ * ZERO node_modules (root + every workspace package, e.g. prisma generated
+ * dirs). Root cause: TASK_1844's node_modules provisioning (linkNodeModules)
+ * and its mandatory pre-remove guard (unlinkNodeModulesLinks) live ONLY in the
+ * Agent-tool WorktreeCreate hook (.claude/hooks/worktree-create.js). Formation
+ * unit worktrees AND dispatch.js's cross-project target_repo_worktree both go
+ * through utils.createWorktree/removeWorktree, which never called either
+ * helper — so Ansuz had to hand-junction directories per dispatch, risking the
+ * TASK_1844 junction-through-delete hazard on cleanup (Git for Windows
+ * recurses THROUGH a node_modules junction on `git worktree remove --force`
+ * and EMPTIES the link target — the MAIN checkout's node_modules).
+ *
+ * Fix (utils.js): createWorktree calls the hook's linkNodeModules() on both
+ * the fresh-create and reuse-clean-worktree success paths; removeWorktree
+ * calls the hook's unlinkNodeModulesLinks() before `git worktree remove
+ * --force`. Both helpers are required lazily from the hook module (never
+ * copied) via linkNodeModulesBestEffort/unlinkNodeModulesBestEffort, which
+ * formations.js (squad removeWorktree) and headless.js (exit-handler cleanup)
+ * also now call before their own `git worktree remove --force` sites.
+ *
+ * Sections (each in its own throwaway mkdtemp repo — NEVER the main repo).
+ * IMPORTANT: "pre-fix behaviour" is expressed as a RAW git baseline run in the
+ * SAME test process, never by loading old source out of git history (`git show
+ * HEAD:...`) — this repo's HEAD legitimately contains the fix once this task
+ * is committed/merged, so a control that depends on "HEAD predates the fix"
+ * would fail permanently the moment it lands. The raw-git baseline IS what
+ * pre-fix createWorktree/removeWorktree actually did (index-lock wait / retry
+ * backoff aside): a bare `git worktree add` / `git worktree remove --force`
+ * with no linking or unlinking step, run right next to the fixed function in
+ * the same repo:
+ *   A  utils.createWorktree links root + nested-package node_modules into the
+ *      worktree (content readable through the link); utils.removeWorktree
+ *      removes the worktree AND leaves both source sentinels intact.
+ *   B  CONTROL: a raw `git worktree add` (the pre-fix baseline) gets NO
+ *      node_modules. TREATMENT: utils.createWorktree, same repo, DOES link —
+ *      proving the fix adds real linking behaviour the baseline lacks.
+ *   C  (Windows only; skipped elsewhere, same as post-complete/task1876.test.js
+ *      Section C). CONTROL: a hand-built junction + raw `git worktree remove
+ *      --force` (the pre-fix baseline) EMPTIES a source sentinel. TREATMENT:
+ *      identical setup removed via utils.removeWorktree (the fix) leaves the
+ *      sentinel intact — proving the guard is load-bearing, not decorative.
+ *
+ * Run: node .formation/tools/__tests__/task2030-worktree-node-modules.test.js
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const UTILS_PATH = path.resolve(__dirname, '..', 'utils.js');
+
+let failures = 0;
+function check(name, cond, detail) {
+  if (cond) { console.log('  PASS  ' + name); }
+  else { failures += 1; console.error('  FAIL  ' + name + (detail ? ' — ' + detail : '')); }
+}
+
+function git(cmd, cwd) {
+  return execSync(cmd, { cwd, encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }).trim();
+}
+function gitSafe(cmd, cwd) { try { return git(cmd, cwd); } catch { return null; } }
+
+function makeGitRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git('git init -q', dir);
+  git('git config user.email "t2030@test.local"', dir);
+  git('git config user.name "T2030"', dir);
+  git('git config commit.gpgsign false', dir);
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'node_modules/\n');
+  fs.writeFileSync(path.join(dir, 'README.md'), 'throwaway fixture\n');
+  git('git add -A', dir);
+  git('git commit -q --no-verify -m "init"', dir);
+}
+
+/**
+ * Root node_modules/ (gitignored, real dir) + a tracked packages/x/ (so the
+ * worktree checkout actually has that directory to link into) with its own
+ * gitignored node_modules/. Each carries a distinct sentinel file.
+ */
+function addNodeModulesSentinels(repo) {
+  const rootNm = path.join(repo, 'node_modules');
+  fs.mkdirSync(rootNm, { recursive: true });
+  fs.writeFileSync(path.join(rootNm, 'SENTINEL_ROOT.txt'), 'root-sentinel\n');
+
+  fs.mkdirSync(path.join(repo, 'packages', 'x'), { recursive: true });
+  fs.writeFileSync(path.join(repo, 'packages', 'x', 'package.json'), '{"name":"x"}\n');
+  git('git add -- packages/x/package.json', repo);
+  git('git commit -q --no-verify -m "add packages/x"', repo);
+
+  const pkgNm = path.join(repo, 'packages', 'x', 'node_modules');
+  fs.mkdirSync(pkgNm, { recursive: true });
+  fs.writeFileSync(path.join(pkgNm, 'SENTINEL_PKG.txt'), 'pkg-sentinel\n');
+}
+
+function readOrNull(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } }
+
+const tmpRoots = [];
+function makeSection(tag) {
+  const tmpRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 't2030' + tag + '-')));
+  tmpRoots.push(tmpRoot);
+  const repo = path.join(tmpRoot, 'repo');
+  makeGitRepo(repo);
+  return { tmpRoot, repo };
+}
+
+try {
+  // ══ Section A: current (fixed) utils.js links + guards ═══════════════════
+  console.log('[A] utils.createWorktree links node_modules; utils.removeWorktree preserves sources');
+  {
+    const { tmpRoot, repo } = makeSection('a');
+    addNodeModulesSentinels(repo);
+    const utils = require(UTILS_PATH);
+
+    const worktreePath = path.join(tmpRoot, 'wt-a');
+    utils.createWorktree(repo, worktreePath, 'task/t2030a');
+
+    const rootLink = path.join(worktreePath, 'node_modules', 'SENTINEL_ROOT.txt');
+    const pkgLink = path.join(worktreePath, 'packages', 'x', 'node_modules', 'SENTINEL_PKG.txt');
+    check('AC: root node_modules resolvable through the link', readOrNull(rootLink) === 'root-sentinel\n', rootLink);
+    check('AC: nested package node_modules resolvable through the link', readOrNull(pkgLink) === 'pkg-sentinel\n', pkgLink);
+
+    // Idempotent reuse path (same branch, clean worktree) must not throw and
+    // must leave the links intact.
+    utils.createWorktree(repo, worktreePath, 'task/t2030a');
+    check('AC: reuse-path leaves links intact', readOrNull(rootLink) === 'root-sentinel\n');
+
+    utils.removeWorktree(repo, worktreePath);
+    check('AC: worktree removed', !fs.existsSync(worktreePath), worktreePath);
+    check('AC: source root node_modules sentinel survives',
+      readOrNull(path.join(repo, 'node_modules', 'SENTINEL_ROOT.txt')) === 'root-sentinel\n');
+    check('AC: source nested package node_modules sentinel survives',
+      readOrNull(path.join(repo, 'packages', 'x', 'node_modules', 'SENTINEL_PKG.txt')) === 'pkg-sentinel\n');
+  }
+
+  // ══ Section B: raw-git CONTROL vs utils.createWorktree TREATMENT ═════════
+  console.log('[B] control: raw `git worktree add` (pre-fix baseline) does not link — treatment: utils.createWorktree does, same repo');
+  {
+    const { tmpRoot, repo } = makeSection('b');
+    addNodeModulesSentinels(repo);
+    const utils = require(UTILS_PATH);
+
+    // CONTROL: raw git worktree add — exactly what pre-fix createWorktree's
+    // git operation was (retry/backoff/branch-cleanup aside): no linking step.
+    const rawPath = path.join(tmpRoot, 'wt-b-raw');
+    git(`git worktree add -q -b task/t2030b-raw "${rawPath}" HEAD`, repo);
+    const rawRootLink = path.join(rawPath, 'node_modules', 'SENTINEL_ROOT.txt');
+    const rawPkgLink = path.join(rawPath, 'packages', 'x', 'node_modules', 'SENTINEL_PKG.txt');
+    check('CONTROL: raw `git worktree add` has NO root node_modules (pre-fix baseline)',
+      readOrNull(rawRootLink) === null, rawRootLink);
+    check('CONTROL: raw `git worktree add` has NO nested package node_modules (pre-fix baseline)',
+      readOrNull(rawPkgLink) === null, rawPkgLink);
+
+    // TREATMENT: utils.createWorktree (the fix), same repo, a different path.
+    const fixedPath = path.join(tmpRoot, 'wt-b-fixed');
+    utils.createWorktree(repo, fixedPath, 'task/t2030b-fixed');
+    const fixedRootLink = path.join(fixedPath, 'node_modules', 'SENTINEL_ROOT.txt');
+    const fixedPkgLink = path.join(fixedPath, 'packages', 'x', 'node_modules', 'SENTINEL_PKG.txt');
+    check('TREATMENT: utils.createWorktree DOES link root node_modules',
+      readOrNull(fixedRootLink) === 'root-sentinel\n', fixedRootLink);
+    check('TREATMENT: utils.createWorktree DOES link nested package node_modules',
+      readOrNull(fixedPkgLink) === 'pkg-sentinel\n', fixedPkgLink);
+
+    gitSafe(`git worktree remove --force "${rawPath}"`, repo);
+    utils.removeWorktree(repo, fixedPath);
+  }
+
+  // ══ Section C (Windows only): raw-git CONTROL vs utils.removeWorktree TREATMENT ══
+  console.log('[C] control: raw `git worktree remove --force` (pre-fix baseline) empties a source sentinel through a junction — treatment: utils.removeWorktree does not');
+  if (process.platform === 'win32') {
+    // CONTROL: hand-build a junction, then run the RAW git command with no
+    // unlink guard — exactly what pre-fix removeWorktree's body did.
+    {
+      const { tmpRoot, repo } = makeSection('c-control');
+      addNodeModulesSentinels(repo);
+      const wt = path.join(tmpRoot, 'wt-c-control');
+      git(`git worktree add -q -b task/t2030c-control "${wt}" HEAD`, repo);
+      fs.symlinkSync(path.join(repo, 'node_modules'), path.join(wt, 'node_modules'), 'junction');
+
+      const before = readOrNull(path.join(repo, 'node_modules', 'SENTINEL_ROOT.txt'));
+      check('control precondition: source sentinel present before removal', before === 'root-sentinel\n');
+
+      gitSafe(`git worktree remove --force "${wt}"`, repo);
+
+      const after = readOrNull(path.join(repo, 'node_modules', 'SENTINEL_ROOT.txt'));
+      check('CONTROL: raw `git worktree remove --force` EMPTIES the source sentinel (pre-fix hazard reproduced)',
+        after === null, 'sentinel after raw removal: ' + JSON.stringify(after));
+    }
+
+    // TREATMENT: identical setup, removed through utils.removeWorktree (the fix).
+    {
+      const { tmpRoot, repo } = makeSection('c-treatment');
+      addNodeModulesSentinels(repo);
+      const utils = require(UTILS_PATH);
+      const wt = path.join(tmpRoot, 'wt-c-treatment');
+      git(`git worktree add -q -b task/t2030c-treatment "${wt}" HEAD`, repo);
+      fs.symlinkSync(path.join(repo, 'node_modules'), path.join(wt, 'node_modules'), 'junction');
+
+      const before = readOrNull(path.join(repo, 'node_modules', 'SENTINEL_ROOT.txt'));
+      check('treatment precondition: source sentinel present before removal', before === 'root-sentinel\n');
+
+      utils.removeWorktree(repo, wt);
+
+      const after = readOrNull(path.join(repo, 'node_modules', 'SENTINEL_ROOT.txt'));
+      check('TREATMENT: utils.removeWorktree preserves the source sentinel (guard proven load-bearing)',
+        after === 'root-sentinel\n', 'sentinel after fixed removal: ' + JSON.stringify(after));
+    }
+  } else {
+    console.log('  SKIP  section C (junction traversal is a Git-for-Windows behavior)');
+  }
+} finally {
+  for (const t of tmpRoots) {
+    try { fs.rmSync(t, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); }
+    catch { /* Windows lock — tmpdir leak acceptable in fixture */ }
+  }
+}
+
+console.log(failures === 0 ? 'ALL PASS' : failures + ' FAILURE(S)');
+process.exit(failures === 0 ? 0 : 1);

package/core/.formation/tools/__tests__/task2067-worktree-branch-reuse.test.js

@@ -0,0 +1,148 @@
+'use strict';
+/**
+ * TASK_2067 — dispatch.js cross-project subagent: when task/<id> already
+ * exists but its worktree does not (e.g. a cancelled task resumed after
+ * TASK_1055-style workaround), createWorktree used to always attempt
+ * `git worktree add <path> -b <branch> <baseRef>`, which dies on "a branch
+ * named '<branch>' already exists" after 4 retries. dispatch.js's catch then
+ * silently degraded to serial_lock — letting a subsequent agent edit the
+ * TARGET repo's main checkout directly (field report ce1d12b6, TASK_1055).
+ *
+ * Fix (utils.js createWorktree): when deleteBranchIfSafe's guard leaves the
+ * branch in place (it has unique commits vs baseRef -- exactly the resumed-
+ * task case) AND the worktree path does not exist, attach the worktree to
+ * the EXISTING branch (`git worktree add <path> <branch>`, no -b) instead of
+ * falling into the always-fresh -b path. No auto-merge of baseRef into the
+ * reused branch — divergence is reported only (decision: never rewrite a
+ * resumed task's history without the operator seeing it).
+ *
+ * Section A (TREATMENT): current utils.js reuses the branch, the worktree
+ * gets the branch's own commit (not a fresh copy of baseRef), and the return
+ * value reports reusedBranch + divergence.
+ * Section B (NEGATIVE CONTROL): the SAME repro against the PRE-FIX utils.js
+ * (CONTROL_REF, the parent of the TASK_2067 fix commit; this used to read
+ * `main`, which made the control fail forever once the fix merged) read via
+ * `git show` into a temp copy — never a bare `git stash`,
+ * which would race other sessions sharing this worktree's stash stack) fails
+ * exactly as the field report describes: no worktree ever gets created, and
+ * createWorktree throws after exhausting retries on "already exists".
+ *
+ * Run: node .formation/tools/__tests__/task2067-worktree-branch-reuse.test.js
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const UTILS_PATH = path.resolve(__dirname, '..', 'utils.js');
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..'); // for `git show <CONTROL_REF>:...`
+const CONTROL_REF = 'cdb91744c~1'; // pre-TASK_2067 utils.js (~1, not ^: cmd.exe eats ^ in execSync)
+
+let failures = 0;
+function check(name, cond, detail) {
+  if (cond) { console.log('  PASS  ' + name); }
+  else { failures += 1; console.error('  FAIL  ' + name + (detail ? ' — ' + detail : '')); }
+}
+
+function git(cmd, cwd) {
+  return execSync(cmd, { cwd, encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }).trim();
+}
+
+function makeGitRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git('git init -q', dir);
+  git('git config user.email "t2067@test.local"', dir);
+  git('git config user.name "T2067"', dir);
+  git('git config commit.gpgsign false', dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'throwaway fixture\n');
+  git('git add -A', dir);
+  git('git commit -q --no-verify -m "init"', dir);
+}
+
+/**
+ * Reproduces the field report: a task branch with its own committed work,
+ * but NO worktree ever created for it in THIS repo (the resumed-task case —
+ * a prior worktree existed elsewhere/was removed; all that matters here is
+ * "branch exists with unique commits, path is free, branch checked out
+ * nowhere").
+ */
+function setupResumedTaskBranch(repo, branchName) {
+  const baseBranch = git('git rev-parse --abbrev-ref HEAD', repo);
+  git(`git checkout -q -b ${branchName}`, repo);
+  fs.writeFileSync(path.join(repo, 'TASK_MARKER.txt'), 'unique-task-work\n');
+  git('git add -- TASK_MARKER.txt', repo);
+  git(`git commit -q --no-verify -m "task work on ${branchName}"`, repo);
+  git(`git checkout -q ${baseBranch}`, repo); // branch is NOT checked out anywhere now
+  return { baseBranch };
+}
+
+const tmpRoots = [];
+function makeSection(tag) {
+  const tmpRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 't2067' + tag + '-')));
+  tmpRoots.push(tmpRoot);
+  const repo = path.join(tmpRoot, 'repo');
+  makeGitRepo(repo);
+  return { tmpRoot, repo };
+}
+
+const BRANCH = 'task/task_x';
+
+try {
+  // ══ Section A: TREATMENT — current (fixed) utils.js reuses the branch ═══
+  console.log('[A] fixed utils.createWorktree attaches to the existing branch instead of failing');
+  {
+    const { tmpRoot, repo } = makeSection('a');
+    const { baseBranch } = setupResumedTaskBranch(repo, BRANCH);
+    const utils = require(UTILS_PATH);
+
+    const worktreePath = path.join(tmpRoot, 'wt-a');
+    const result = utils.createWorktree(repo, worktreePath, BRANCH);
+
+    check('AC: createWorktree reports reusedBranch=true', !!(result && result.reusedBranch), JSON.stringify(result));
+    check('AC: worktree created at the target path', fs.existsSync(worktreePath), worktreePath);
+    check('AC: worktree carries the BRANCH commit (attached, not recreated from baseRef)',
+      fs.existsSync(path.join(worktreePath, 'TASK_MARKER.txt')));
+    const wtBranch = git('git rev-parse --abbrev-ref HEAD', worktreePath);
+    check('AC: worktree is checked out on the reused branch', wtBranch === BRANCH, wtBranch);
+    check('AC: divergence reported (branch 1 ahead, 0 behind baseRef) — no auto-merge performed',
+      result && result.divergence && result.divergence.ahead === 1 && result.divergence.behind === 0,
+      JSON.stringify(result && result.divergence));
+    // baseRef itself must be untouched — proves "no automatic merge" default.
+    const baseHasMarker = fs.existsSync(path.join(repo, 'TASK_MARKER.txt'));
+    check('AC: baseRef checkout untouched (no auto-merge into/from the reused branch)', baseHasMarker === false);
+    void baseBranch;
+  }
+
+  // ══ Section B: NEGATIVE CONTROL — main's utils.js still hits the bug ═════
+  console.log(`[B] CONTROL: same repro against pre-fix utils.js (git show ${CONTROL_REF}:..., temp copy) fails on "already exists"`);
+  {
+    const { tmpRoot, repo } = makeSection('b');
+    setupResumedTaskBranch(repo, BRANCH);
+
+    const mainUtilsSrc = git(`git show ${CONTROL_REF}:.formation/tools/utils.js`, REPO_ROOT);
+    const mainUtilsPath = path.join(tmpRoot, 'utils_main_control.js');
+    fs.writeFileSync(mainUtilsPath, mainUtilsSrc);
+    const mainUtils = require(mainUtilsPath);
+
+    const worktreePath = path.join(tmpRoot, 'wt-b');
+    let thrown = null;
+    try {
+      mainUtils.createWorktree(repo, worktreePath, BRANCH);
+    } catch (e) {
+      thrown = e;
+    }
+    check('CONTROL: main\'s createWorktree throws instead of reusing the branch', !!thrown, thrown && thrown.message);
+    check('CONTROL: failure is the reported "already exists" defect, not something else',
+      !!(thrown && /already exists/i.test(thrown.message)), thrown && thrown.message);
+    check('CONTROL: no worktree was ever created on main (bug reproduced faithfully)', !fs.existsSync(worktreePath), worktreePath);
+  }
+} finally {
+  for (const t of tmpRoots) {
+    try { fs.rmSync(t, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); }
+    catch { /* Windows lock — tmpdir leak acceptable in fixture */ }
+  }
+}
+
+console.log(failures === 0 ? 'ALL PASS' : failures + ' FAILURE(S)');
+process.exit(failures === 0 ? 0 : 1);

package/core/.formation/tools/alaya-gate.js

@@ -0,0 +1,198 @@
+// TASK_2104: shared, dependency-free Alaya relevance gate — extracted out
+// of prompt.js so task-api.js's echoAlayaLessons (TASK_1992) applies the
+// same TASK_2101 cosine-floor + stack-match gate instead of a hand-copied
+// near-duplicate that had neither. Zero deps (no memory-loader/core-resolve)
+// so it still require()s from a sub-project with no .formation/ checkout —
+// callers must treat a require() failure as "gate unavailable" and degrade
+// gracefully (see task-api.js echoAlayaLessons).
+// Shared by: prompt.js appendAlayaLessons(), task-api.js echoAlayaLessons().
+
+'use strict';
+
+/**
+ * Build the cross-project context query shared by Cortex and Alaya lookups:
+ * scope_paths basenames (extension stripped) + up to 4 non-stop-word
+ * keywords from the task title.
+ *
+ * @param {string|object} taskData - task JSON string or parsed object
+ * @returns {string|null} the query string, or null when nothing to query
+ */
+function buildTaskContextQuery(taskData) {
+  let scopePaths = [];
+  let taskTitle = '';
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) {
+      scopePaths = parsed.scope_paths || [];
+      taskTitle = parsed.title || '';
+    }
+  } catch { /* taskData not JSON, skip */ }
+
+  if (scopePaths.length === 0 && !taskTitle) return null;
+
+  // Build query from scope_paths file names + task title keywords
+  const queryParts = [];
+  for (const sp of scopePaths) {
+    const parts = String(sp).replace(/\\/g, '/').split('/');
+    const last = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+    if (last && last.length > 2) queryParts.push(last);
+  }
+  if (taskTitle) {
+    const stopWords = new Set(['the','a','an','is','are','to','of','and','in','for','on','at','by','with','fix','task','add','update']);
+    const words = taskTitle.replace(/[^a-zA-Z0-9_\s]/g, ' ').split(/\s+/).filter(w => w.length > 2 && !stopWords.has(w.toLowerCase()));
+    queryParts.push(...words.slice(0, 4));
+  }
+  if (queryParts.length === 0) return null;
+
+  return [...new Set(queryParts)].join(' ');
+}
+
+// TASK_2101: absolute relevance gate for Alaya lesson injection.
+//
+// Why: alaya_recall's only pre-2101 score is RRF rank fusion (~0.016-0.032),
+// which carries no absolute relevance — lexical overlap on a single common
+// word ("checkpoint", "gate") was enough to rank a bija first regardless of
+// domain. Every bija also had source_count=1 (hub distiller not implemented),
+// so nothing self-corrects via aggregation either. The fix is two gates that
+// must BOTH pass before a bija is even a candidate for injection:
+//   1. cosine floor — the RAW semantic cosine (never the RRF score) must
+//      clear ALAYA_MIN_COSINE_DEFAULT. A bija the semantic arm never scored
+//      (cosine=null: fts-only hit, or bija has no embedding yet) fails the
+//      floor by construction — an unverifiable relevance is not a floor pass.
+//   2. stack match — the bija's coarse tech stack (source_symbol's file
+//      extension/dir, plus tags) must overlap the task's (scope_paths'
+//      extensions/dirs), UNLESS the cosine is very high
+//      (>= ALAYA_STACK_OVERRIDE_COSINE) — a strong enough semantic match can
+//      override a stack that a coarse heuristic failed to resolve.
+//
+// Calibration (R4, measured 2026-09-28 against the live backend, 5 real
+// dispatch queries x top-10 semantic hits = 50 bijas, hand-labelled):
+//   - ArcticEmbedXs cosines are compressed high: clearly irrelevant noise
+//     (payment/CRM/UI-colour/backtest seeds on Rust and JS infra cards)
+//     scored 0.656-0.697; on-topic bijas scored 0.709-0.810. 0.45 (the
+//     earlier placeholder) passed all 50, i.e. it was not a filter at all.
+//   - Confusion at 0.45: 20 on-topic kept, 30 noise kept. At 0.70: 20 kept,
+//     0 noise. The margin is only ~0.012, so treat 0.70 as fitted to a small
+//     sample and re-measure when the bija population changes.
+//   - The stack half of the gate currently has no real signal: every live
+//     bija has source_symbol='' (hub predates the pass-through) and `tags`
+//     are content word-bags, not stack labels. In practice a bija on a task
+//     with scope_paths passes only at >= ALAYA_STACK_OVERRIDE_COSINE (0.8),
+//     so today's effective floor for scoped tasks is 0.8 and 0.70 applies to
+//     unscoped tasks. A3 check (dispatch --dry-run on TASK_2096/2097/2100):
+//     10/10 candidates dropped on each; no noise injected.
+//   - Also seen: the on-topic hits were near-duplicates (8-9 copies of one
+//     "community detection void" / "KuzuDB graph broken" observation) and
+//     months stale (the conditions they describe are fixed). Relevance is
+//     not the only gap: dedup (distiller) and retraction are next.
+const ALAYA_MIN_COSINE_DEFAULT = 0.70;
+const ALAYA_STACK_OVERRIDE_COSINE = 0.8;
+// Candidate pool requested from alaya_recall — wider than the render cap (3)
+// so post-filtering by the two gates still has real candidates to keep.
+const ALAYA_CANDIDATE_POOL = 10;
+
+/**
+ * Coarse stack tokens (lowercase file extensions + 1-2 top path segments)
+ * from a list of paths. Shared by the task side (scope_paths) and the bija
+ * side (source_symbol's `{file_path}:{symbol}:{kind}` shape, split on ':').
+ *
+ * @param {string} normPath - a single '/'-normalised path
+ * @param {Set<string>} tokens - mutated in place
+ */
+function addStackTokens(normPath, tokens) {
+  if (!normPath) return;
+  const extMatch = normPath.match(/\.([a-zA-Z0-9]+)$/);
+  if (extMatch) tokens.add(extMatch[1].toLowerCase());
+  const parts = normPath.split('/').filter(Boolean);
+  if (parts.length > 0) tokens.add(parts[0].toLowerCase());
+  if (parts.length > 1) tokens.add(`${parts[0]}/${parts[1]}`.toLowerCase());
+}
+
+/**
+ * Derive the task's coarse stack from its scope_paths (file extensions +
+ * top-level dirs, e.g. {'rs', 'js', 'dashboard', '.formation/tools'}).
+ * @param {string[]} scopePaths
+ * @returns {Set<string>}
+ */
+function deriveTaskStack(scopePaths) {
+  const tokens = new Set();
+  for (const sp of scopePaths || []) {
+    addStackTokens(String(sp).replace(/\\/g, '/'), tokens);
+  }
+  return tokens;
+}
+
+/**
+ * Derive a bija's coarse stack from its tags (comma-separated string, as
+ * returned by alaya_recall) and its source_symbol (TASK_2101 — hub
+ * pass-through of the originating rune's symbol_stable_id; empty for hubs
+ * that predate the field, or project-level seeds with no single symbol).
+ * @param {object} bija
+ * @returns {Set<string>}
+ */
+function deriveBijaStack(bija) {
+  const tokens = new Set();
+  for (const t of String(bija.tags || '').split(',')) {
+    const tag = t.trim().toLowerCase();
+    if (tag) tokens.add(tag);
+  }
+  const sourceSymbol = String(bija.source_symbol || '');
+  if (sourceSymbol) {
+    const filePath = sourceSymbol.split(':')[0].replace(/\\/g, '/');
+    addStackTokens(filePath, tokens);
+  }
+  return tokens;
+}
+
+/**
+ * Whether a bija passes the TASK_2101 relevance gate: cosine floor AND
+ * (stack overlap OR a cosine high enough to override a stack miss).
+ * A task with no derivable stack (empty scope_paths) cannot be judged on
+ * stack at all, so the stack half of the gate is skipped — the floor alone
+ * still applies.
+ *
+ * @param {object} bija - one alaya_recall result (cosine, tags, source_symbol, ...)
+ * @param {Set<string>} taskStack - from deriveTaskStack
+ * @param {number} floor - ALAYA_MIN_COSINE_DEFAULT (or an override)
+ * @returns {boolean}
+ */
+function passesAlayaRelevanceGate(bija, taskStack, floor) {
+  const cosine = typeof bija.cosine === 'number' ? bija.cosine : null;
+  if (cosine === null || cosine < floor) return false;
+  if (taskStack.size === 0) return true; // no task-side stack signal to judge against
+  if (cosine >= ALAYA_STACK_OVERRIDE_COSINE) return true;
+  const bijaStack = deriveBijaStack(bija);
+  for (const tok of bijaStack) {
+    if (taskStack.has(tok)) return true;
+  }
+  return false;
+}
+
+/**
+ * Dedup a list of alaya_recall bijas: key = id, else first 100 chars of
+ * content. Shared by prompt.js's appendAlayaLessons and task-api.js's
+ * echoAlayaLessons — both queried the same hub, so the same duplicate hubs
+ * (near-identical seeds re-inscribed by different sources) can show up.
+ *
+ * @param {object[]} bijas
+ * @returns {object[]}
+ */
+function dedupBijas(bijas) {
+  const seen = new Set();
+  return (bijas || []).filter(b => {
+    const key = b.id || (b.content || '').slice(0, 100);
+    if (!key || seen.has(key)) return false;
+    seen.add(key); return true;
+  });
+}
+
+module.exports = {
+  buildTaskContextQuery,
+  deriveTaskStack,
+  deriveBijaStack,
+  passesAlayaRelevanceGate,
+  dedupBijas,
+  ALAYA_MIN_COSINE_DEFAULT,
+  ALAYA_STACK_OVERRIDE_COSINE,
+  ALAYA_CANDIDATE_POOL,
+};