klypix-mcp 1.71.0 → 1.72.0

package/bin/klypix-install.mjs

@@ -71,7 +71,7 @@ const CODEX_CONFIG = path.join(HOME, '.codex', 'config.toml');
 const HOOK_MARK = 'global-brain-hook';
 const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
 const fwd = (p) => p.replace(/\\/g, '/');
-const copyRetrySleepSync = (ms) => {
+const retrySleepSync = (ms) => {
     try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
     catch { /* best effort */ }
 };
@@ -81,7 +81,7 @@ function copyFileRobust(src, dest, tries = 8) {
         catch (error) {
             const retryable = ['EBUSY', 'EPERM', 'EACCES'].includes(error?.code);
             if (!retryable || attempt === tries) throw error;
-            copyRetrySleepSync(20 * attempt);
+            retrySleepSync(20 * attempt);
         }
     }
 }
@@ -174,6 +174,44 @@ function reportCodex(result) {
 // update hook runs install per project, so every project heals once). Only the
 // known npx/node launch is migrated; a hand-customized command / invalid JSON is
 // left untouched, and the original is backed up. Best-effort, never throws.
+// ── Windows rename hardening (1.71.1) ───────────────────────────────────────
+// Every atomic commit in this installer is a rename-over-destination, and on
+// Windows that throws EPERM/EBUSY/EACCES while ANY process briefly holds the
+// target — an AV scan, an indexer, or, routinely on a developer machine, the
+// live MCP servers reading the very bundle we are replacing. Measured 2026-08-15:
+// three failures in one session with 7-14 servers live, on .mcp-runtime.json and
+// brain-history.mjs; each retry succeeded immediately.
+//
+// The failure is loud rather than silent, and a manual re-run fixes it — but
+// this is the FIRST command a new user types, and a raw EPERM stack at that
+// moment is a bad first contact. So the installer now outlasts a transient
+// holder using the SAME bounded backoff the brain write funnel has used since
+// 1.68.0 (klypix-format.mjs atomicWrite): ~2.7s total, then rethrow. A
+// persistent holder still fails loudly — delayed is acceptable, silently wrong
+// is not, and pretending we wrote a file we did not would be far worse.
+const RENAME_RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_BACKOFF_MS = [40, 120, 300, 700, 1500];
+/** fs.renameSync that outlasts a transient Windows lock on the destination. */
+function renameSyncWithBackoff(from, to) {
+    for (let attempt = 0; ; attempt++) {
+        try { return fs.renameSync(from, to); }
+        catch (e) {
+            if (attempt >= RENAME_BACKOFF_MS.length || !RENAME_RETRYABLE_CODES.has(e?.code)) {
+                // Name the real cause: "EPERM: operation not permitted" tells a
+                // user nothing actionable, and the fix is usually to close the
+                // editors whose servers hold the bundle.
+                if (RENAME_RETRYABLE_CODES.has(e?.code)) {
+                    e.message = `${e.message}\n  ↳ ${path.basename(to)} is held by another process after ~2.7s of retries.`
+                        + '\n    On Windows this is normally a running MCP server, an antivirus scan, or an indexer.'
+                        + '\n    Close your editors (or quit KLYPIX) and run the command again — nothing was left half-written.';
+                }
+                throw e;
+            }
+            retrySleepSync(RENAME_BACKOFF_MS[attempt]);
+        }
+    }
+}
+
 function migrateProjectMcpConfig() {
     try {
         const file = path.join(process.cwd(), '.mcp.json');
@@ -362,7 +400,7 @@ try {
     } catch { /* .prev rollback snapshot is best-effort */ }
     const renameOrder = staged.slice().sort((a, b) => (a.dst === 'global-brain-hook.mjs' ? 1 : 0) - (b.dst === 'global-brain-hook.mjs' ? 1 : 0));
     let n = 0;
-    for (const st of renameOrder) { fs.renameSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
+    for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
 
     // 3) mark the dir an ESM package
     fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({ name: 'klypix-project-brain', private: true, type: 'module' }, null, 2));
@@ -397,7 +435,7 @@ try {
         const tmp = SETTINGS + '.klypix-tmp';
         fs.writeFileSync(tmp, JSON.stringify(settings, null, 2), 'utf8');
         JSON.parse(fs.readFileSync(tmp, 'utf8'));   // verify before swap
-        fs.renameSync(tmp, SETTINGS);
+        renameSyncWithBackoff(tmp, SETTINGS);
     }
 
     // 6) Commit the runtime pointer and version receipt atomically while the
@@ -424,7 +462,7 @@ try {
     };
     const runtimePath = path.join(BRAIN_DIR, '.mcp-runtime.json');
     fs.writeFileSync(runtimePath + '.klypix-new', JSON.stringify(runtime, null, 2) + '\n', 'utf8');
-    fs.renameSync(runtimePath + '.klypix-new', runtimePath);
+    renameSyncWithBackoff(runtimePath + '.klypix-new', runtimePath);
     // A tagged-but-DIRTY checkout keeps via:'npm' (the tag still names the
     // payload identity, and dev:true would stop auto-update from healing the
     // machine back to clean released bytes) but stamps dirty:true + the audit
@@ -437,7 +475,7 @@ try {
             : { brainVersion: VERSION, via: 'npm', dirty: false, installedAt };
     const versionPath = path.join(BRAIN_DIR, '.brain-version.json');
     fs.writeFileSync(versionPath + '.klypix-new', JSON.stringify(versionStamp, null, 2), 'utf8');
-    fs.renameSync(versionPath + '.klypix-new', versionPath);
+    renameSyncWithBackoff(versionPath + '.klypix-new', versionPath);
 
     // 7) migrate THIS project's .mcp.json off npx onto the now-installed local bundle
     //    (heals an existing stale config so the next MCP server spawn runs current).

package/bin/klypix-worker.mjs

@@ -876,7 +876,8 @@ server.registerTool('brain_sync', {
     releaseIntent: z.object({
       version: z.string().max(64).describe('The version this session intends to release (e.g. "1.70.0").'),
       ref: z.string().max(200).describe('The git ref (branch or tag) the release will be cut from.'),
-    }).optional().describe('Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer\'s sync gains a "release in preparation" footer line.'),
+      acknowledge: z.array(z.string().max(40)).max(64).optional().describe('Commit shas this release DELIBERATELY leaves behind. Only needed after a refusal: if the ref would drop finished work, the lease is refused and the response names every sha. Re-declare with those shas here to proceed — and tell the user what they are first.'),
+    }).optional().describe('Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer\'s sync gains a "release in preparation" footer line. A NEW declaration is also checked against what the release would LEAVE BEHIND: if the ref is missing commits that are on trunk or on a branch a live peer session is working on, the lease is REFUSED (nothing is changed) and the response lists them — report those commits to the user, then re-declare with acknowledge:[...] naming each sha if the release should go ahead without them.'),
   },
 }, async ({ project, intent, files, phase, include_context, results, releaseIntent }, extra) => {
   const totalStartedAt = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.71.0",
+  "version": "1.72.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -84,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/mcp-presence.mjs

@@ -40,7 +40,7 @@ import {
 // canonical copy lives in the pure module because that one is import-restricted
 // (crypto only), so it can never grow a dependency this file would inherit.
 import { normalizeFileKey } from './finding-routing.mjs';
-import { cmpSemver3, collectRepoState, repoStateWarnings } from './repo-state.mjs';
+import { cmpSemver3, collectRepoState, releaseAncestry, releaseAncestryWarnings, repoStateWarnings } from './repo-state.mjs';
 import { recordResultManifests } from './result-reconcile.mjs';
 
 export const MCP_HEARTBEAT_MS = 60_000;
@@ -242,8 +242,61 @@ export function validateReleaseIntent(value) {
   if (!ref || ref.length > 200 || /[\u0000-\u001f\u007f\s]/.test(ref)) {
     errors.push('releaseIntent.ref must be a nonempty bounded git ref (branch or tag) with no whitespace or control characters');
   }
+  // acknowledge: the commits this release KNOWINGLY leaves behind. Optional,
+  // and only ever consulted when the ancestry gate found something — see
+  // ancestryAcknowledged. Bounded like every other caller-supplied list.
+  let acknowledge = [];
+  if (value.acknowledge !== undefined && value.acknowledge !== null) {
+    if (!Array.isArray(value.acknowledge)) {
+      errors.push('releaseIntent.acknowledge must be an array of commit shas the release deliberately leaves behind');
+    } else {
+      acknowledge = value.acknowledge
+        .filter((s) => typeof s === 'string')
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => /^[0-9a-f]{4,40}$/.test(s))
+        .slice(0, 64);
+    }
+  }
   if (errors.length) return { provided: true, ok: false, errors };
-  return { provided: true, ok: true, version: version.replace(/^v/i, ''), ref };
+  return { provided: true, ok: true, version: version.replace(/^v/i, ''), ref, acknowledge };
+}
+
+/**
+ * Does this acknowledgement actually name what the release would drop?
+ *
+ * The whole point of the handshake is that a session cannot take the lease
+ * without REPRODUCING the shas it is choosing to leave behind — and a model
+ * that has to reproduce them has, in practice, had to read and relay them.
+ * Nothing in MCP can force an agent to speak to its human; the closest
+ * available thing is to make silence insufficient to proceed.
+ *
+ * Prefix-tolerant in both directions so a caller may echo the short shas we
+ * printed or the full ones from their own `git log`.
+ */
+export function ancestryAcknowledged(ancestry, acknowledge = []) {
+  if (!ancestry) return true;
+  if (ancestry.isDescendant || ancestry.status === 'ok') return true;
+  // WHICH unknowns block, and which do not — the line matters in both
+  // directions, and getting it wrong is expensive either way.
+  //
+  // BLOCKS. 'target-unresolved' means we ARE in a git repo and the ref you
+  // named is not in it: the cheapest bypass in the whole design was a mistyped
+  // or invented ref name, which used to return null and grant the lease in
+  // silence. 'unnameable' means a divergence exists whose commits could not be
+  // listed — an empty list must never satisfy the gate.
+  //
+  // DOES NOT BLOCK. A project with no git at all, or a repo with no trunk and
+  // no peer to compare against, is not an unanswered question — it is a
+  // MEANINGLESS one. Blocking there would stop a designer's brain in a plain
+  // folder, or a brand-new repo with a single branch, from ever declaring a
+  // release. That is a false positive of exactly the kind that teaches people
+  // to ignore the gate.
+  if (ancestry.status === 'unnameable') return false;
+  if (ancestry.status === 'unknown') return ancestry.reason !== 'target-unresolved';
+  const listed = (ancestry.sources || []).flatMap((s) => s.missing || []).map((c) => String(c.sha || '').toLowerCase());
+  if (!listed.length) return false;
+  const given = (acknowledge || []).map((s) => String(s || '').toLowerCase()).filter(Boolean);
+  return listed.every((sha) => given.some((g) => g.startsWith(sha) || sha.startsWith(g)));
 }
 
 const canonicalPathKey = (value) => {
@@ -908,6 +961,38 @@ function gitBranch(cwd) {
   }
 }
 
+/**
+ * The branch THIS SESSION is actually on — the neutral-vendor fix.
+ *
+ * Until 1.72.0 every MCP host reported the branch of the VAULT directory,
+ * because the seam records `cwd: path.dirname(brainPath)`. Only Claude Code
+ * and hooked Codex — the two hosts with lifecycle hooks — supplied a true
+ * per-session branch, so the product was measurably better on those two. For a
+ * layer whose entire claim is that every coding agent is served equally, that
+ * asymmetry is the one defect that cannot be argued away.
+ *
+ * The MCP server is launched BY the host, so its own process.cwd() is the
+ * workspace the user opened for every host that sets it — Cursor, Cline,
+ * Windsurf, VS Code, Codex, Kimi, OpenCode, and anything else that speaks MCP,
+ * with no hook and no host-specific code. A host that launches from its own
+ * install directory simply yields no branch there, and the vault answer stands
+ * exactly as before: strictly more signal, never less.
+ *
+ * Deliberately NOT written into the presence row's `cwd`. That field is
+ * session IDENTITY, and the overlap matcher normalizes declared file paths
+ * against it — moving it would silently change which files count as the same
+ * file, which is a far larger blast radius than this fix is worth.
+ */
+const hostCwdBranch = (vaultDir) => {
+  let hostCwd = null;
+  try { hostCwd = process.cwd(); } catch { hostCwd = null; }
+  if (hostCwd && path.resolve(hostCwd) !== path.resolve(vaultDir || '')) {
+    const fromHost = gitBranch(hostCwd);
+    if (fromHost) return fromHost;
+  }
+  return gitBranch(vaultDir);
+};
+
 const peerFingerprint = (sessions, selfId) => (Array.isArray(sessions) ? sessions : [])
   .filter((session) => session.id !== selfId)
   .map((session) => [
@@ -1646,7 +1731,7 @@ export function createMcpPresence({
       surface,
       branch: branchPrepared !== undefined
         ? branchPrepared
-        : gitBranch(path.dirname(brainPath)),
+        : hostCwdBranch(path.dirname(brainPath)),
       intent,
       intentSource: intent !== undefined ? 'declared' : null,
       files,
@@ -2030,7 +2115,7 @@ export function createMcpPresence({
     // be redirected by a lexical junction retarget.
     if (!preparedClientInfo) preparedClientInfo = clientInfo();
     const preparedBranch = resultBrainPath
-      ? gitBranch(path.dirname(resultBrainPath))
+      ? hostCwdBranch(path.dirname(resultBrainPath))
       : null;
     if (!verifiedBinding()) {
       const report = syncPreflightFailure({
@@ -2364,6 +2449,8 @@ export function createMcpPresence({
     let releaseFooterLine = '';
     let releaseAdvisory = null;
     let releaseAdvisoryText = '';
+    let workAtRisk = null;
+    let workAtRiskText = '';
     {
       const leaseStamp = now();
       let outcome = null;
@@ -2380,15 +2467,63 @@ export function createMcpPresence({
           if (freed.status === 'released') outcome = freed;
         }
       } else if (releaseIntentChecked.provided) {
-        outcome = declareReleaseLease({
-          brainPath,
-          sessionId,
-          version: releaseIntentChecked.version,
-          ref: releaseIntentChecked.ref,
-          client: (preparedClientInfo || {}).client || 'unknown',
-          home,
-          now: leaseStamp,
-        });
+        // ── THE HANDSHAKE (1.72.0) ────────────────────────────────────────
+        // Before a lease is granted, ask the one question nothing used to ask:
+        // would this release leave finished work behind? If it would, REFUSE —
+        // and require the next attempt to name, sha by sha, exactly what it is
+        // choosing to drop.
+        //
+        // A warning attached to a granted lease is one a model may relay or may
+        // not; the founder's correction was that the USER has to be informed.
+        // MCP has no channel to a human, so the strongest honest mechanism is
+        // to make silence insufficient: a session that cannot proceed without
+        // reproducing the missing commits has, in practice, had to surface them.
+        //
+        // Only a NEW declaration is gated. A holder refreshing mid-release is
+        // never re-blocked — that would be an obstacle, not a gate — and a
+        // deliberate off-trunk hotfix is one acknowledged call away.
+        const existingLease = readReleaseLease({ brainPath, home, now: leaseStamp });
+        // recipientKey is module-private in agent-presence; the same normalization
+        // (trim + 160-char bound) reproduced here rather than widening its surface.
+        const holderKey = (v) => String(v || '').trim().slice(0, 160);
+        // EXEMPT THE REF, NOT THE HOLDER. Exempting whoever held the lease let a
+        // session declare a clean ref, take the lease, then re-declare pointing
+        // at a DIRTY one and sail through — the gate exempted them for being the
+        // holder. What deserves exemption is re-declaring the SAME ref that was
+        // already gated; anything else is a new release decision.
+        const sameRefAsHeld = !!existingLease
+          && holderKey(existingLease.holderId) === holderKey(sessionId)
+          && String(existingLease.ref || '') === String(releaseIntentChecked.ref || '');
+        let gateAncestry = null;
+        if (!sameRefAsHeld) {
+          try {
+            const peerBranches = [
+              ...new Set((report.sessions || [])
+                .filter((s) => s?.id !== sessionId)
+                .map((s) => String(s?.branch || '').trim())
+                .filter(Boolean)),
+            ];
+            gateAncestry = releaseAncestry(path.dirname(brainPath), releaseIntentChecked.ref, { peerBranches });
+          } catch {
+            // A probe that throws is not an all-clear either.
+            gateAncestry = { status: 'unknown', reason: 'git-unavailable', ref: releaseIntentChecked.ref, isDescendant: false, missingCount: 0, sources: [], missing: [] };
+          }
+        }
+        if (gateAncestry && !gateAncestry.isDescendant
+          && !ancestryAcknowledged(gateAncestry, releaseIntentChecked.acknowledge)) {
+          outcome = { ok: false, status: 'ancestry-unacknowledged', ancestry: gateAncestry };
+        } else {
+          outcome = declareReleaseLease({
+            brainPath,
+            sessionId,
+            version: releaseIntentChecked.version,
+            ref: releaseIntentChecked.ref,
+            client: (preparedClientInfo || {}).client || 'unknown',
+            home,
+            now: leaseStamp,
+          });
+          if (gateAncestry && !gateAncestry.isDescendant) outcome = { ...outcome, acknowledgedAncestry: gateAncestry };
+        }
       } else if (clearCompletionScope) {
         const freed = freeReleaseLease({ brainPath, sessionId, home, now: leaseStamp });
         if (freed.status === 'released') outcome = freed;
@@ -2412,7 +2547,38 @@ export function createMcpPresence({
         refreshedAt: active.refreshedAt,
         expiresAt: active.expiresAt,
       } : null;
-      if (outcome?.status === 'conflict') {
+      if (outcome?.status === 'ancestry-unacknowledged') {
+        const anc = outcome.ancestry;
+        const shas = (anc.sources || []).flatMap((s) => s.missing || []).map((c) => c.sha);
+        releaseLease = {
+          status: 'refused',
+          kind: 'release-would-leave-work-behind',
+          severity: 'blocking',
+          requested: { version: releaseIntentChecked.version, ref: releaseIntentChecked.ref },
+          ancestry: {
+            trunk: anc.trunk,
+            ref: anc.ref,
+            missingCount: anc.missingCount,
+            sources: anc.sources,
+          },
+          // Exactly what the retry must echo. Named so a caller never has to
+          // guess the shape of the second call.
+          acknowledgeRequired: shas,
+        };
+        releaseText = [
+          'KLYPIX release lease REFUSED — the lease was not taken. No release state changed.',
+          '',
+          ...releaseAncestryWarnings(anc),
+          '',
+          // Deliberately NOT a ready-to-paste call. Pre-rendering the exact
+          // retry made the bypass the easiest thing on screen — an agent could
+          // copy it and never say a word to anyone. The shas are listed above;
+          // reproducing them is the work, and the work is the point.
+          shas.length
+            ? `To proceed anyway, re-send releaseIntent with an "acknowledge" array naming each of the ${shas.length} sha(s) listed above. Only do that after the user has been told and has decided.`
+            : 'This release cannot be acknowledged automatically — the missing work could not be listed. Resolve it with the user before continuing.',
+        ].join('\n');
+      } else if (outcome?.status === 'conflict') {
         const holder = outcome.holder;
         const holderPrefix = prefixFor(holder.holderId);
         releaseLease = {
@@ -2461,8 +2627,78 @@ export function createMcpPresence({
       } else if (active) {
         releaseLease = { status: 'held', holder: holderBlock };
       }
+      // ── Would this release leave finished work behind? (1.72.0) ──────────
+      // Coordination in this engine had always been about files two sessions
+      // are editing RIGHT NOW. Nothing ever asked whether finished work was
+      // actually IN the build being cut — so on 2026-08-15 a release was
+      // prepared from a branch that could not contain three completed commits,
+      // and the FOUNDER noticed, not the tooling.
+      //
+      // It rides the LEASE because that is the one moment a release announces
+      // itself, and it is reported at blocking severity so the declaring
+      // session cannot take the lease and stay quiet: the founder's own
+      // correction was "at least the user should be informed/asked about it".
+      // Advisory in effect, unmissable in delivery — a hotfix cut from a tag is
+      // legitimate, so the human decides, but never unknowingly.
+      if (active && releaseIntentChecked.provided && (outcome?.status === 'taken' || outcome?.status === 'refreshed')) {
+        try {
+          const peerBranches = [
+            ...new Set((report.sessions || [])
+              .filter((s) => s?.id !== sessionId)
+              .map((s) => String(s?.branch || '').trim())
+              .filter(Boolean)),
+          ];
+          const ancestry = releaseAncestry(path.dirname(brainPath), active.ref, { peerBranches });
+          // Only a genuinely DIRTY ancestry is worth repeating on a granted
+          // lease. An unknown that the gate deliberately chose not to block on
+          // (no git, nothing to compare) must not leak a scary CHECK COULD NOT
+          // RUN line into every sync of a plain-folder project — that is the
+          // alarm fatigue this whole design is trying to avoid.
+          const warnings = ancestry && ancestry.status !== 'unknown' ? releaseAncestryWarnings(ancestry) : [];
+          if (warnings.length) {
+            releaseLease = {
+              ...releaseLease,
+              ancestry: {
+                kind: 'release-would-leave-work-behind',
+                severity: 'blocking',
+                trunk: ancestry.trunk,
+                ref: ancestry.ref,
+                missingCount: ancestry.missingCount,
+                sources: ancestry.sources,
+              },
+            };
+            releaseText = `${releaseText}\n\n${warnings.join('\n')}`;
+          }
+        } catch { /* a git probe must never break a sync */ }
+      }
       if (active) {
         releaseFooterLine = `release in preparation: v${active.version} from ${active.ref} (session ${prefixFor(active.holderId)})`;
+        // ── THE THIRD QUESTION (1.72.0) ──────────────────────────────────
+        // The ancestry gate protects the session CUTTING the release. This is
+        // its mirror, for everyone else: "is my finished work going to make it
+        // into the build somebody is preparing right now?"
+        //
+        // Unpushed commits are the common way the answer is no, and the
+        // situation is invisible from both sides — the releaser cannot see a
+        // branch that was never pushed, and the author has no reason to think
+        // about a release they are not cutting. Both halves of the 2026-08-15
+        // miss are this, seen from the two ends.
+        //
+        // Free: aheadBehindOrigin is already collected. Advisory, and only
+        // while a release is genuinely in flight, so it can never become
+        // ambient noise.
+        const ahead = Number(repoState?.aheadBehindOrigin?.ahead || 0);
+        const holderIsSelf = holderBlock && holderBlock.sessionId === sessionId;
+        if (!completing && ahead > 0 && !holderIsSelf) {
+          workAtRisk = {
+            kind: 'unpushed-work-during-release',
+            aheadCount: ahead,
+            upstream: repoState.aheadBehindOrigin.upstream,
+            branch: repoState.branch || null,
+            release: { version: active.version, ref: active.ref },
+          };
+          workAtRiskText = `KLYPIX work-at-risk: a release is being prepared right now (v${active.version} from ${active.ref}), and this checkout has ${ahead} commit(s) on ${repoState.branch || 'HEAD'} that are NOT pushed to ${repoState.aheadBehindOrigin.upstream}. Work that never reached the remote cannot be in that build. If any of it belongs in v${active.version}, say so to the user and coordinate with the release session now (brain_message) — after the cut is far more expensive than before it.`;
+        }
       } else if (!completing && repoState?.packageVersion && repoState?.latestReleaseTag?.version
         && cmpSemver3(repoState.packageVersion, repoState.latestReleaseTag.version) > 0) {
         // Zero-config visibility: nobody declared anything, but this checkout's
@@ -2537,6 +2773,7 @@ export function createMcpPresence({
       // zero-config checkout-ahead advisory when nothing is declared.
       ...(releaseLease ? { releaseLease } : {}),
       ...(releaseAdvisory ? { releaseAdvisory } : {}),
+      ...(workAtRisk ? { workAtRisk } : {}),
       ...(resultReconciliation ? { resultReconciliation: {
         status: resultReconciliation.status,
         claims: resultReconciliation.claims || [],
@@ -2591,6 +2828,7 @@ export function createMcpPresence({
       conflictText,
       repoStateWarning,
       releaseAdvisoryText,
+      workAtRiskText,
       // The one-line footer every peer sees while any release lease is active.
       releaseFooterLine,
     ].filter(Boolean).join('\n\n');

package/src/repo-state.mjs

@@ -45,18 +45,19 @@ const CACHE_MS = 60_000;
 // worth caching too, or every sync in a non-git project re-pays the spawn).
 const repoStateCache = new Map();
 
-function defaultExecGit(args, cwd) {
+function defaultExecGit(args, cwd, timeoutMs) {
   return execFileSync('git', args, {
     cwd,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
-    timeout: GIT_TIMEOUT_MS,
+    // Most probes are rev-parse-fast; patch-id work needs its own budget.
+    timeout: Number(timeoutMs) > 0 ? Number(timeoutMs) : GIT_TIMEOUT_MS,
   });
 }
 
-const makeGit = (execGit) => (cwd, args) => {
+const makeGit = (execGit) => (cwd, args, timeoutMs) => {
   try {
-    const out = execGit(args, cwd);
+    const out = execGit(args, cwd, timeoutMs);
     return typeof out === 'string' ? out.trim() : null;
   } catch {
     return null;   // no git on PATH, not a repo, timeout — all the same: no data
@@ -139,6 +140,274 @@ function repoStateForDir(git, dir) {
   };
 }
 
+// Trunk candidates, most-authoritative first. The remote tracking ref beats a
+// local branch: a local `master` can itself be stale, and the question a
+// release must answer is "does this carry everything the TEAM has landed".
+const TRUNK_REFS = ['origin/master', 'origin/main', 'master', 'main'];
+const MAX_MISSING_LISTED = 8;
+// git cherry has no --max-count, so a pathological divergence is bounded here
+// rather than parsed forever.
+const MAX_CHERRY_SCAN = 500;
+// Measured 670ms on a real 200-commit divergence; the shared 1500ms budget was
+// already failing intermittently and reporting the release as clean.
+const CHERRY_TIMEOUT_MS = 10_000;
+const UNIT_SEP = '';
+
+/**
+ * Would this release leave finished work behind?
+ *
+ * The recorded rule is "never ship a build that is not a descendant of trunk —
+ * the check is ANCESTRY, not version number", and it exists because desktop
+ * 1.3.107 was the highest version number KLYPIX had ever produced while missing
+ * 211 trunk commits and an entire feature. A higher number on an off-trunk
+ * branch is perfect camouflage.
+ *
+ * Until now that rule lived only as a card — recall, which works exactly as
+ * often as somebody exercises it. On 2026-08-15 nobody did: three finished
+ * commits sat on master while a release was cut from a branch that could never
+ * contain them, and the FOUNDER caught it, not the tooling. Coordination in
+ * this engine has always been about files two sessions are editing RIGHT NOW;
+ * nothing ever asked whether finished work was actually IN the build. This is
+ * that missing axis.
+ *
+ * Advisory data, never a refusal — a hotfix cut from a tag is a legitimate
+ * off-trunk release. The caller decides; this only makes it impossible to be
+ * unaware.
+ *
+ * @returns {null|{trunk, ref, isDescendant, missingCount, missing:Array<{sha,subject}>}}
+ *   null when the question cannot be answered (no git, no trunk, unknown ref).
+ */
+export function releaseAncestry(projectDir, ref, { execGit = defaultExecGit, peerBranches = [] } = {}) {
+  const git = makeGit(execGit);
+  const dir = String(projectDir || '');
+  if (!dir) return { status: 'unknown', reason: 'no-project-dir', isDescendant: false, missingCount: 0, sources: [], missing: [] };
+  const target = String(ref || '').trim() || 'HEAD';
+  const shaOf = (r) => git(dir, ['rev-parse', '--verify', `${r}^{commit}`]);
+  const resolves = (r) => shaOf(r) !== null;
+  // A gate that cannot run must SAY SO. Returning null here made "the ref does
+  // not exist" and "git timed out" indistinguishable from "clean" — and the
+  // caller granted the lease silently, which an agent could trigger with a
+  // single mistyped ref name. Unknown is now its own state, and the gateway
+  // treats it as blocking.
+  if (git(dir, ['rev-parse', '--git-dir']) === null) {
+    return { status: 'unknown', reason: 'git-unavailable', ref: target, isDescendant: false, missingCount: 0, sources: [], missing: [] };
+  }
+  const targetSha = shaOf(target);
+  if (targetSha === null) {
+    return { status: 'unknown', reason: 'target-unresolved', ref: target, isDescendant: false, missingCount: 0, sources: [], missing: [] };
+  }
+
+  // ALL trunk candidates, not the first that resolves. First-match-wins picked
+  // origin/master in every normal clone and therefore NEVER compared LOCAL
+  // master — which is exactly where the 2026-08-15 commits sat, unpushed. The
+  // feature was blind to its own motivating incident for any session without a
+  // live peer on that branch. Local trunk ahead of a release ref is precise,
+  // not heuristic, so this adds no squash-merge noise beyond what origin/master
+  // already carries. `origin/HEAD` is probed too, so a repo whose trunk is
+  // `develop` or `trunk` is not left with no gate at all.
+  const trunkRefs = TRUNK_REFS.filter(resolves);
+  const originHead = git(dir, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  if (originHead && !trunkRefs.includes(originHead) && resolves(originHead)) trunkRefs.push(originHead);
+  const trunk = trunkRefs[0] || null;
+
+  // WHY PEER BRANCHES, and not trunk alone — learned the hard way on
+  // 2026-08-15. The trunk check alone said release/1.3.113 was fine: it IS a
+  // descendant of origin/master. But origin/master was 214 commits behind the
+  // LOCAL master where the finished work actually sat, unpushed. Trunk ancestry
+  // catches the 1.3.107 class (a branch forked off trunk long ago); it cannot
+  // catch work that has not reached trunk yet.
+  //
+  // The presence lane is the only thing that knows which branches are live,
+  // which is precisely why this belongs in the coordination engine and not in
+  // one repo's prebuild script. A prebuild gate can only see refs; the lane
+  // sees WHO IS WORKING WHERE.
+  const seen = new Set();
+  const candidates = [];
+  const trunkSet = new Set(trunkRefs);
+  for (const r of [...trunkRefs, ...peerBranches]) {
+    const name = String(r || '').trim();
+    if (!name || name === target || seen.has(name)) continue;
+    // Unresolvable refs are dropped; SAME-SHA refs are deliberately kept. A
+    // release branch cut from trunk and declared immediately is the single most
+    // common legitimate case, and dropping the equal ref left zero candidates —
+    // which the new "cannot answer" path then refused. Kept, the ancestry check
+    // finds it is trivially an ancestor, contributes no source, and the release
+    // reads clean, which is the truth.
+    if (shaOf(name) === null) continue;
+    seen.add(name);
+    candidates.push({ ref: name, kind: trunkSet.has(name) ? 'trunk' : 'peer-branch' });
+  }
+
+  // NO third source, deliberately — and this is a decision, not an omission.
+  // A scan of recently-committed local branches was built and MEASURED against
+  // this repo: it produced 30-62 "missing" commits across 6-14 branches, most of
+  // them work already squash-merged into trunk under different SHAs. Ancestry
+  // cannot see through a squash, so the heuristic manufactures false positives
+  // at exactly the moment someone is trying to ship — and this project has the
+  // scar for that: five consecutive releases reported red over perfect publishes,
+  // and the recorded lesson is that alarm fatigue is itself a release-integrity
+  // defect. Trunk and live-peer branches are both PRECISE (no false positives by
+  // construction), so the gate keeps only those. The cost is stated honestly in
+  // the doc comment above rather than papered over with a noisy proxy.
+
+  if (!candidates.length) {
+    return { status: 'unknown', reason: 'no-comparable-refs', ref: target, trunk, isDescendant: false, missingCount: 0, sources: [], missing: [] };
+  }
+
+  const sources = [];
+  const claimed = new Set();   // shas already attributed to an earlier source
+  for (const cand of candidates) {
+    // `merge-base --is-ancestor` exits 0/1, and makeGit turns a non-zero exit
+    // into null — so null here means "not an ancestor", not "unknown".
+    if (git(dir, ['merge-base', '--is-ancestor', cand.ref, target]) !== null) continue;
+    // `git cherry` INSTEAD OF `rev-list`, and this is the single most important
+    // line in the module. rev-list compares SHAS, so it reported as "missing"
+    // every commit that had been rebased, cherry-picked, or squash-merged into
+    // the target under a new sha — measured on the real repo, that was 30-62
+    // false positives across 6-14 branches, and it forced an otherwise-good
+    // source to be deleted rather than tuned.
+    //
+    // `git cherry <target> <source>` compares PATCH-IDs: `+` means the change
+    // genuinely is not there, `-` means an equivalent change already is.
+    // Verified on real repos: it sees through a rebase, a cherry-pick, and a
+    // single-commit squash. It does NOT see through a squash of several commits
+    // into one (the combined diff cannot match any individual patch-id) — an
+    // honest, documented residue rather than a silent one.
+    //
+    // It also fixes the merge over-count for free: where rev-list said 2 for a
+    // divergence carrying one real change plus its merge commit, cherry says 1.
+    // Count and listing now come from the SAME source, so they can no longer
+    // disagree in the caller's favour — which is what let a merge-only
+    // divergence satisfy the handshake with an empty list.
+    //
+    // TIMEOUT DISCIPLINE, learned the hard way one commit before this shipped:
+    // patch-id computation is far slower than the rev-parse probes this module
+    // was built around, and at the shared 1500ms budget `git cherry` returned
+    // null on the real repo — which the loop read as "nothing missing" and the
+    // gate reported the release as CLEAN. A false negative here is strictly
+    // worse than every false positive this module has ever produced, so cherry
+    // gets its own budget AND a failure is never allowed to mean "clean".
+    const cherry = git(dir, ['cherry', target, cand.ref], CHERRY_TIMEOUT_MS);
+    let count;
+    let shown;
+    let approximate = false;
+    if (cherry !== null) {
+      const missingShas = cherry.split('\n')
+        .filter((l) => l.startsWith('+ '))
+        .map((l) => l.slice(2).trim())
+        .filter(Boolean)
+        .slice(0, MAX_CHERRY_SCAN);
+      count = missingShas.length;
+      if (count <= 0) continue;              // every change is already present
+      shown = missingShas.slice(0, MAX_MISSING_LISTED);
+    } else {
+      // FALL BACK, never skip. rev-list is sha-based so it over-reports
+      // rebases and squashes, but over-reporting is a conversation and
+      // under-reporting is a lost feature. The source is marked approximate so
+      // the text can say the equivalence check could not run.
+      const countRaw = git(dir, ['rev-list', '--count', `${target}..${cand.ref}`]);
+      count = Number(countRaw);
+      if (!Number.isFinite(count) || count <= 0) continue;
+      approximate = true;
+      const fallbackLog = git(dir, ['log', `--max-count=${MAX_MISSING_LISTED}`, '--format=%H', `${target}..${cand.ref}`]);
+      shown = (fallbackLog || '').split('\n').map((s) => s.trim()).filter(Boolean);
+    }
+    if (!shown.length) continue;
+    // One bounded call for the subjects of just what will be shown.
+    const log = git(dir, ['log', '--no-walk', `--format=%h%x1f%s`, ...shown]);
+    const parsed = (log || '').split('\n').filter(Boolean).map((line) => {
+      const sep = line.indexOf(UNIT_SEP);
+      return sep < 0
+        ? { sha: line.trim(), subject: '' }
+        : { sha: line.slice(0, sep).trim(), subject: line.slice(sep + 1).slice(0, 120) };
+    });
+    // Trunk and a peer sitting on trunk are the DEFAULT configuration, so the
+    // same commits would otherwise be counted twice and demanded twice. Each
+    // sha is attributed to the first source that reports it.
+    const missing = parsed.filter((c) => c.sha && !claimed.has(c.sha));
+    for (const c of missing) claimed.add(c.sha);
+    if (!missing.length && count > 0 && parsed.length) continue;   // wholly duplicated source
+    // `approximate` = the patch-id equivalence check could not run for this
+    // source, so the list may include work that is already present under a
+    // different sha. Carried on the source so the text can say so rather than
+    // asserting a precision it does not have.
+    sources.push({ ...cand, missingCount: count, missing, ...(approximate ? { approximate: true } : {}) });
+  }
+
+  if (!sources.length) {
+    return { status: 'ok', trunk, ref: target, isDescendant: true, missingCount: 0, sources: [], missing: [] };
+  }
+  const missingCount = sources.reduce((n, s) => n + s.missingCount, 0);
+  const listed = sources.flatMap((s) => s.missing);
+  return {
+    // A divergence we can count but cannot NAME is still a refusal — the caller
+    // must not be able to acknowledge an empty list.
+    status: listed.length ? 'dirty' : 'unnameable',
+    trunk,
+    ref: target,
+    isDescendant: false,
+    missingCount,
+    sources,
+    // Flattened for the common case of one diverged source.
+    missing: listed.slice(0, MAX_MISSING_LISTED),
+  };
+}
+
+/**
+ * The half that actually matters: lines a HUMAN reads.
+ *
+ * Founder's correction, verbatim — "at least the user should be
+ * informed/asked about it". A structured field only a model consumes is not a
+ * gate, because a model can decline to mention it. These strings ride the
+ * release-lease response at blocking severity, so a session cannot take the
+ * lease and stay quiet about what the release would drop.
+ */
+export function releaseAncestryWarnings(ancestry) {
+  if (!ancestry || ancestry.isDescendant) return [];
+
+  // A gate that could not run is a finding, not a pass. Silence here was how a
+  // mistyped ref, a missing git, or a 1.5s timeout turned the whole check off
+  // while looking exactly like a clean release.
+  if (ancestry.status === 'unknown') {
+    const why = {
+      'git-unavailable': 'git could not be read in this project',
+      'target-unresolved': `the ref "${ancestry.ref}" does not exist here`,
+      'no-comparable-refs': 'there is no trunk or peer branch to compare against',
+      'no-project-dir': 'no project directory was supplied',
+    }[ancestry.reason] || ancestry.reason || 'the check could not run';
+    return [
+      `RELEASE CHECK COULD NOT RUN — ${why}.`,
+      'This is not an all-clear: nothing was verified about what this release would leave out.',
+      'Tell the user, and check by hand that the release branch contains everything it should.',
+    ];
+  }
+
+  const { ref, missingCount, sources } = ancestry;
+  const named = sources.flatMap((s) => s.missing).length;
+  const lines = [
+    `RELEASE WOULD LEAVE WORK BEHIND — ${missingCount} finished commit(s) already exist that this release does not include.`,
+  ];
+  for (const s of sources) {
+    lines.push(s.kind === 'trunk'
+      ? `  ${s.missingCount} commit(s) on ${s.ref} (the main line) are not in ${ref}:`
+      : `  ${s.missingCount} commit(s) on ${s.ref} — a branch someone is working on right now — are not in ${ref}:`);
+    for (const c of s.missing) lines.push(`    · ${c.sha} ${c.subject}`);
+    if (s.missingCount > s.missing.length) lines.push(`    · …and ${s.missingCount - s.missing.length} more not listed`);
+    if (s.approximate) {
+      lines.push('    (this list is approximate — the equivalence check could not run, so some of');
+      lines.push('     these may already be in the release under a different commit id)');
+    }
+  }
+  if (!named) {
+    lines.push('  (none of them could be listed individually — they are merge commits; inspect the range by hand)');
+  }
+  lines.push('');
+  lines.push('WHAT THIS MEANS FOR THE USER: if this release is built now, that work will not be in it,');
+  lines.push('and nobody will notice until someone looks for a feature that is missing.');
+  lines.push('Say this to them in your own words, listing what is above, BEFORE going any further.');
+  return lines;
+}
+
 // Released means "a tag anywhere in the repo names this version" — not only at
 // HEAD, because a checkout routinely moves past the commit it tagged while the
 // version itself stays published.