klypix-mcp 1.73.2 → 1.75.0

package/bin/klypix-conformance.mjs

@@ -223,12 +223,16 @@ try {
           offeredAt: now - 900,
           acknowledgedAt: now - 500,
           consumedAt: now - 250,
+          // The STRONG claim: this peer sent a real receipt. Without this marker the
+          // record is an auto-lease or unknown, and the renderer must not say
+          // "explicitly" — the conformance fixture has to state which it means.
+          consumedVia: 'receipt',
         }],
         seen: ['finding-owner'],
       }],
       sessions: lane, selfId: 'finding-sender', now,
     });
-    checks.findingReceiptRendered = /explicitly consumed by all 1 target peer\(s\) after model-context delivery \(not human-read\)/.test(renderReceiptSummary(receipt));
+    checks.findingReceiptRendered = /explicitly consumed by all 1 target peer\(s\) via receipt \(not human-read\)/.test(renderReceiptSummary(receipt));
   }
 
   // ── Cross-PC presence: simulated two-machine scenario ─────────────────────

package/bin/klypix-worker.mjs

@@ -562,7 +562,7 @@ server.registerTool('project_map_scan', {
 
 server.registerTool('project_map_drift', {
   title: 'Check brain cards against the repo\'s real files (drift report)',
-  description: 'Read-only drift check: every brain card that references THIS project\'s files is verified against the working tree. Reports cards whose referenced files are gone or moved (with rename candidates by unique basename), and headlines when the checkout itself is behind its origin default branch — in that state a "missing" file may simply not be in this checkout. Slash-joined name enumerations and other-project paths are recognized and skipped, not reported as drift. Nothing is written; fix cards with a CORRECTION marker or by editing them in KLYPIX.',
+  description: 'Read-only drift check: every brain card that references THIS project\'s files is verified against the working tree. Reports cards whose referenced files are gone or moved (with rename candidates by unique basename), and headlines the checkout\'s own position against its origin default branch — reporting BOTH ahead and behind, so a DIVERGED checkout is named as diverged rather than merely behind. In either state a "missing" file may simply not be in this checkout. Slash-joined name enumerations and other-project paths are recognized and skipped, not reported as drift. Nothing is written; fix cards with a CORRECTION marker or by editing them in KLYPIX.',
   annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
   inputSchema: {
     project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
@@ -691,7 +691,7 @@ server.registerTool('brain_note', {
 
 server.registerTool('brain_message', {
   title: 'Message the other live agent sessions on this project (one-time note, not a brain card)',
-  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can send and receive through the shared machine-local presence lane. A supported lifecycle event or KLYPIX tool result offers the note into model-visible context; a later independent supported action acknowledges that offer. Pending/offered notes replay after reconnect, while expiry or capacity loss leaves a failed per-recipient receipt instead of silently disappearing. Acknowledged means a later action followed the offer — it is NOT proof a human read it. Delivery remains OS-user-local, machine-local, bounded by a 24h TTL, and unavailable to a peer that never takes a supported action. Ephemeral and NOT persisted to the brain — for a durable decision use brain_note instead.',
+  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can send and receive through the shared machine-local presence lane. A supported lifecycle event or KLYPIX tool result offers the note into model-visible context; a later independent supported action acknowledges that offer. Pending/offered notes replay after reconnect, while expiry or capacity loss leaves a failed per-recipient receipt instead of silently disappearing. Acknowledged means a later action followed the offer — it is NOT proof a human read it. A note then retires either by an explicit brain_message_receipt ("acted on it") or by AUTO-CONSUMPTION on a further independent action, with no receipt; your receipt line names which, and auto-consumption evidences activity, not uptake. Delivery remains OS-user-local, machine-local, bounded by a 24h TTL, and unavailable to a peer that never takes a supported action. Ephemeral and NOT persisted to the brain — for a durable decision use brain_note instead.',
   inputSchema: {
     text: z.string().describe('The note to deliver (kept to 400 chars).'),
     to: z.string().optional().describe('Target hint — a peer session id-prefix or branch name; omit or "all" for every live session.'),
@@ -790,10 +790,15 @@ 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.'),
-      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.'),
+      acknowledge: z.array(z.string().max(40)).max(1024).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, OR commits any session STAKED a releaseClaim on (even one that has since ended), 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. Acknowledging away a claimed or live-owned commit queues its owner a notification automatically.'),
+    releaseClaim: z.object({
+      shas: z.array(z.string().max(40)).max(20).optional().describe('Commit shas that MUST ride the next release. Stake after committing work a user was promised — the claim OUTLIVES this session (14d), and every future releaseIntent must contain these commits or acknowledge them by name.'),
+      note: z.string().max(160).optional().describe('One line of why — shown verbatim in any refusal that names this claim ("founder was told the Arrow tool ships in the next build").'),
+      withdraw: z.union([z.array(z.string().max(40)).max(20), z.boolean()]).optional().describe('Shas to withdraw from this session\'s claim; [] or true withdraws the whole claim. Only the staking session (or its logical continuation) can withdraw.'),
+    }).optional().describe('Stake a durable claim that specific commits ride the NEXT release — the promise "you\'ll see it in the next build" made machine-readable. Unlike presence rows (which age out ~10min after a session ends), a claim persists until fulfilled (the release ref contains the shas — auto-retired with a courtesy note), withdrawn, or expired (14d). A release that would drop claimed shas is REFUSED until they are acknowledged BY NAME, and acknowledging them away notifies the owner. Use exactly one of shas (stake/extend) or withdraw.'),
   },
-}, async ({ project, intent, files, phase, include_context, results, releaseIntent }, extra) => {
+}, async ({ project, intent, files, phase, include_context, results, releaseIntent, releaseClaim }, extra) => {
   const totalStartedAt = Date.now();
   const report = mcpPresence.sync({
     project,
@@ -802,6 +807,7 @@ server.registerTool('brain_sync', {
     phase,
     results,
     releaseIntent,
+    releaseClaim,
     deliverMessages: include_context !== false,
     actionId: extra?.klypixRequestIdentity?.actionId || '',
     preflight: extra?.klypixBrainSyncPreflight,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.73.2",
+  "version": "1.75.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -83,7 +83,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/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/project-binding-rebind.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": "node test/publish-verdict.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/project-binding-rebind.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-claim-join.mjs && node test/release-claims.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/agent-presence.mjs

@@ -1235,6 +1235,9 @@ function normalizeReleaseLease(raw) {
   const refreshedAt = Number(raw.refreshedAt || raw.takenAt || 0);
   if (!holderId || !version || !ref || !takenAt || !refreshedAt) return null;
   const ttlMs = Math.max(60_000, Number(raw.ttlMs) || RELEASE_LEASE_TTL_MS);
+  const acknowledgedShas = [...new Set((Array.isArray(raw.acknowledgedShas) ? raw.acknowledgedShas : [])
+    .map((x) => String(x || '').trim().toLowerCase())
+    .filter((x) => /^[0-9a-f]{4,40}$/.test(x)))].slice(0, 2048);
   return {
     holderId,
     holderClient: String(raw.holderClient || 'unknown').slice(0, 40),
@@ -1244,6 +1247,7 @@ function normalizeReleaseLease(raw) {
     refreshedAt,
     ttlMs,
     expiresAt: refreshedAt + ttlMs,
+    ...(acknowledgedShas.length ? { acknowledgedShas } : {}),
   };
 }
 
@@ -1327,6 +1331,14 @@ export function declareReleaseLease({
   home,
   now = Date.now(),
   ttlMs = RELEASE_LEASE_TTL_MS,
+  // Shas this declaration acknowledged away (ancestry + claims). PERSISTED on
+  // the lease so a holder's refresh does not have to re-litigate them: without
+  // this, the natural refresh pattern — keep attaching the same releaseIntent —
+  // was refused on the very claim the holder had already acknowledged, the
+  // else-chain skipped the refresh, and the lease starved mid-build: the exact
+  // failure the lease-loss warning exists for, rebuilt by the claims gate
+  // (2026-08-17 review blocker B1, found independently by all four lenses).
+  acknowledgedShas = [],
 }) {
   const holderId = recipientKey(sessionId);
   const nextVersion = releaseLeaseVersionKey(version);
@@ -1338,6 +1350,14 @@ export function declareReleaseLease({
       return { write: false, outcome: { ok: false, status: 'conflict', holder: verdict.lease } };
     }
     const stillMine = mine && verdict?.status === 'active';
+    // Union with what the held lease already acknowledged — a re-declare with a
+    // NEW acknowledgement must extend the record, never erase the history that
+    // keeps the holder's refresh from re-refusing.
+    const priorAcks = stillMine && Array.isArray(verdict.lease.acknowledgedShas)
+      ? verdict.lease.acknowledgedShas : [];
+    const acks = [...new Set([...priorAcks, ...(Array.isArray(acknowledgedShas) ? acknowledgedShas : [])]
+      .map((x) => String(x || '').trim().toLowerCase())
+      .filter((x) => /^[0-9a-f]{4,40}$/.test(x)))].slice(0, 2048);
     const stored = {
       schemaVersion: 1,
       holderId,
@@ -1347,6 +1367,7 @@ export function declareReleaseLease({
       takenAt: stillMine ? verdict.lease.takenAt : now,
       refreshedAt: now,
       ttlMs: Math.max(60_000, Number(ttlMs) || RELEASE_LEASE_TTL_MS),
+      ...(acks.length ? { acknowledgedShas: acks } : {}),
     };
     const reclaimed = !stillMine && verdict ? verdict.status : null;
     return {
@@ -1430,6 +1451,191 @@ export function freeReleaseLease({ brainPath, sessionId, home, now = Date.now()
   } });
 }
 
+// ── Release claims — "my commits ride the next build", surviving session exit ─
+//
+// The presence half of the release gate dies with its session: rows age out in
+// ~10 minutes, after which a dropped commit reverts to an anonymous sha, and a
+// commit on a branch NO live session is on never enters the ancestry comparison
+// at all. Field shape (2026-08-17, founder-surfaced): a session promises "you'll
+// see it in the next build", closes, and the next release passes every gate
+// while silently leaving that work behind — the exact v1.3.120 failure, one
+// session-lifetime later. A claim is that promise made DURABLE: shas + owner +
+// note, persisted in the lane, checked against EVERY releaseIntent ref until it
+// is fulfilled, withdrawn, or expires.
+//
+// Deliberately NOT a lease: claims never conflict with each other, any number
+// may coexist, and fulfilment is mechanical (the shas are contained in the
+// release ref). Same identity model as the lease (a claim survives id rotation
+// via the logical-session match), same atomic lane write, same fail-loud
+// bounding — a store the gate depends on must never silently drop an entry.
+export const RELEASE_CLAIM_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+export const RELEASE_CLAIMS_MAX = 32;
+export const RELEASE_CLAIM_SHAS_MAX = 20;
+
+const claimSha = (value) => {
+  const s = String(value || '').trim().toLowerCase();
+  return /^[0-9a-f]{4,40}$/.test(s) ? s : null;
+};
+
+function normalizeReleaseClaim(raw, now = Date.now()) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const ownerId = recipientKey(raw.ownerId);
+  const shas = [...new Set((Array.isArray(raw.shas) ? raw.shas : []).map(claimSha).filter(Boolean))]
+    .slice(0, RELEASE_CLAIM_SHAS_MAX);
+  const stakedAt = Number(raw.stakedAt || 0);
+  if (!ownerId || !shas.length || !stakedAt) return null;
+  const expiresAt = Number(raw.expiresAt || 0) || (stakedAt + RELEASE_CLAIM_TTL_MS);
+  if (now >= expiresAt) return null;
+  return {
+    ownerId,
+    ownerClient: String(raw.ownerClient || 'unknown').slice(0, 40),
+    ownerLogicalId: recipientKey(raw.ownerLogicalId) || null,
+    branch: String(raw.branch || '').slice(0, 120) || null,
+    note: String(raw.note || '').replace(/\s+/g, ' ').trim().slice(0, 160) || null,
+    shas,
+    stakedAt,
+    expiresAt,
+  };
+}
+
+const liveReleaseClaims = (raw, now = Date.now()) => (Array.isArray(raw) ? raw : [])
+  .map((c) => normalizeReleaseClaim(c, now))
+  .filter(Boolean);
+
+// A claim belongs to the caller when any identity in the caller's set matches
+// the identity the claim recorded — the same rotation-tolerant rule the lease
+// uses, because "the same conversation after /clear" must still own its claim.
+const sessionOwnsClaim = (claim, sessions, callerId) => {
+  const key = recipientKey(callerId);
+  if (!key || !claim) return false;
+  if (claim.ownerId === key || claim.ownerLogicalId === key) return true;
+  const me = (Array.isArray(sessions) ? sessions : [])
+    .find((s) => recipientKey(s.id) === key) || null;
+  if (!me) return false;
+  const mine = new Set([recipientKey(me.id), recipientKey(me.logicalSessionId),
+    ...normalizeAliases(me.aliases).map(recipientKey)].filter(Boolean));
+  return mine.has(claim.ownerId) || (claim.ownerLogicalId && mine.has(claim.ownerLogicalId));
+};
+
+function mutateReleaseClaims({ brainPath, home, now, mutate }) {
+  if (!brainPath) return { ok: false, status: 'no-brain' };
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  if (!acquireLock(lockFile)) return { ok: false, status: 'lane-locked' };
+  try {
+    const laneRead = readMutableLane(laneFile);
+    if (!laneRead.ok) return { ok: false, status: laneRead.reason };
+    const data = laneRead.data;
+    const sessions = pruneSessions(data.sessions, now);
+    const claims = liveReleaseClaims(data.releaseClaims, now);
+    const result = mutate({ data, sessions, claims });
+    if (result.write) {
+      const next = { ...data };
+      if (!result.claims || !result.claims.length) delete next.releaseClaims;
+      else next.releaseClaims = result.claims;
+      fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+      writeLaneFileAtomic(laneFile, JSON.stringify(next));
+    }
+    return result.outcome;
+  } finally {
+    releaseLock(lockFile);
+  }
+}
+
+// Stake (or extend) this session's claim. One claim per owner: re-staking
+// UNIONS the shas and refreshes note/expiry, so a session adding a second
+// commit does not spawn a second entry. The lane bound fails LOUD — silently
+// dropping a claim the gate depends on is the 1.74.0 livelock lesson applied
+// to a different store.
+export function stakeReleaseClaim({ brainPath, sessionId, client, logicalSessionId, branch, shas, note, home, now = Date.now() }) {
+  const ownerId = recipientKey(sessionId);
+  const cleanShas = [...new Set((Array.isArray(shas) ? shas : []).map(claimSha).filter(Boolean))];
+  if (!ownerId) return { ok: false, status: 'no-session' };
+  if (!cleanShas.length) return { ok: false, status: 'no-valid-shas' };
+  if (cleanShas.length > RELEASE_CLAIM_SHAS_MAX) {
+    return { ok: false, status: 'too-many-shas', limit: RELEASE_CLAIM_SHAS_MAX, given: cleanShas.length };
+  }
+  return mutateReleaseClaims({ brainPath, home, now, mutate: ({ sessions, claims }) => {
+    const mineIndex = claims.findIndex((c) => sessionOwnsClaim(c, sessions, ownerId));
+    if (mineIndex < 0 && claims.length >= RELEASE_CLAIMS_MAX) {
+      return { write: false, outcome: { ok: false, status: 'claims-full', limit: RELEASE_CLAIMS_MAX } };
+    }
+    const existing = mineIndex >= 0 ? claims[mineIndex] : null;
+    // The union must never silently shed a promised sha (review blocker B2 —
+    // executed: stake 15 + extend 10 reported 'extended' while 5 promised shas
+    // vanished; the v1.3.120 silent-drop class recurring inside its own fix).
+    const unionSize = new Set([...(existing?.shas || []), ...cleanShas]).size;
+    if (unionSize > RELEASE_CLAIM_SHAS_MAX) {
+      return { write: false, outcome: {
+        ok: false, status: 'claim-would-overflow',
+        limit: RELEASE_CLAIM_SHAS_MAX, existing: (existing?.shas || []).length, adding: cleanShas.length,
+      } };
+    }
+    const merged = {
+      ownerId,
+      ownerClient: String(client || existing?.ownerClient || 'unknown').slice(0, 40),
+      ownerLogicalId: recipientKey(logicalSessionId) || existing?.ownerLogicalId || null,
+      branch: String(branch || existing?.branch || '').slice(0, 120) || null,
+      note: String(note || existing?.note || '').replace(/\s+/g, ' ').trim().slice(0, 160) || null,
+      shas: [...new Set([...(existing?.shas || []), ...cleanShas])],
+      stakedAt: existing?.stakedAt || now,
+      expiresAt: now + RELEASE_CLAIM_TTL_MS,
+    };
+    const next = mineIndex >= 0
+      ? claims.map((c, i) => (i === mineIndex ? merged : c))
+      : [...claims, merged];
+    return { write: true, claims: next, outcome: { ok: true, status: mineIndex >= 0 ? 'extended' : 'staked', claim: merged } };
+  } });
+}
+
+// Withdraw shas from this session's claim (empty/omitted shas = the whole
+// claim). Only the owner's identity set can withdraw — a releasing session
+// must acknowledge a foreign claim through the gate, never delete it.
+export function withdrawReleaseClaim({ brainPath, sessionId, shas, home, now = Date.now() }) {
+  const ownerId = recipientKey(sessionId);
+  if (!ownerId) return { ok: false, status: 'no-session' };
+  const drop = new Set((Array.isArray(shas) ? shas : []).map(claimSha).filter(Boolean));
+  return mutateReleaseClaims({ brainPath, home, now, mutate: ({ sessions, claims }) => {
+    const mineIndex = claims.findIndex((c) => sessionOwnsClaim(c, sessions, ownerId));
+    if (mineIndex < 0) return { write: false, outcome: { ok: true, status: 'no-claim' } };
+    const mine = claims[mineIndex];
+    const kept = drop.size
+      ? mine.shas.filter((s) => ![...drop].some((d) => s.startsWith(d) || d.startsWith(s)))
+      : [];
+    const next = kept.length
+      ? claims.map((c, i) => (i === mineIndex ? { ...mine, shas: kept } : c))
+      : claims.filter((_, i) => i !== mineIndex);
+    return { write: true, claims: next, outcome: { ok: true, status: kept.length ? 'trimmed' : 'withdrawn', remaining: kept.length } };
+  } });
+}
+
+// Retire specific (claim owner, shas) pairs after a release FULFILLS them —
+// called by the gateway on a granted lease whose ref contains the shas. Whole
+// claims disappear only when every sha they carry is fulfilled.
+export function retireFulfilledClaims({ brainPath, fulfilled, home, now = Date.now() }) {
+  const byOwner = new Map((Array.isArray(fulfilled) ? fulfilled : [])
+    .map((f) => [recipientKey(f?.ownerId), new Set((f?.shas || []).map(claimSha).filter(Boolean))]));
+  if (!byOwner.size) return { ok: true, status: 'nothing-to-retire' };
+  return mutateReleaseClaims({ brainPath, home, now, mutate: ({ claims }) => {
+    let changed = false;
+    const next = claims.map((c) => {
+      const done = byOwner.get(c.ownerId);
+      if (!done || !done.size) return c;
+      const kept = c.shas.filter((s) => !done.has(s));
+      if (kept.length !== c.shas.length) changed = true;
+      return kept.length ? { ...c, shas: kept } : null;
+    }).filter(Boolean);
+    if (!changed) return { write: false, outcome: { ok: true, status: 'nothing-to-retire' } };
+    return { write: true, claims: next, outcome: { ok: true, status: 'retired' } };
+  } });
+}
+
+// Read-only: live claims. Lock-free like every other read surface.
+export function readReleaseClaims({ brainPath, home, now = Date.now() } = {}) {
+  if (!brainPath) return [];
+  return liveReleaseClaims(readLane(laneFileFor(brainPath, home)).releaseClaims, now);
+}
+
 // A long-lived MCP worker can observe SessionEnd(A) and then receive the first
 // request for a brand-new Codex thread B. That is rotation, not a rekey: A's
 // tombstone, scope, message audience/receipts, and authorship must remain bound
@@ -2200,6 +2406,15 @@ export function postPresenceMessage({
   dedupeKey = '',
   home,
   now = Date.now(),
+  // Machine-addressed notifications only (claim owners, ancestry owners): the
+  // exact recipient id is KNOWN, and the recipient being offline is the very
+  // case the notification exists for — a staked claim outlives its session, so
+  // its owner may be gone when the release that drops their work is declared.
+  // The message waits directed in the lane (24h TTL, sender-visible dead-letter
+  // on expiry) and greets the owner's next session. NEVER set this for
+  // hand-typed targets: the exactly-one-live-row refusal below is what keeps an
+  // ambiguous prefix from queuing a note nobody will ever receive.
+  allowOfflineTarget = false,
 }) {
   const body = neutralizeMarkers(String(text || '').replace(/\s+/g, ' ').trim().slice(0, 400));
   if (!brainPath || !from || !body) return { posted: false, message: null, reason: 'invalid-message' };
@@ -2238,7 +2453,11 @@ export function postPresenceMessage({
     // unsafe: it may be an ambiguous UUID prefix or duplicated branch. Refuse
     // instead of queuing a note whose visible `to` never had a recipient.
     if (!broadcast && candidateIds.length !== 1) {
-      return { posted: false, message: null, reason: 'target-not-unique' };
+      if (!(allowOfflineTarget && candidateIds.length === 0)) {
+        return { posted: false, message: null, reason: 'target-not-unique' };
+      }
+      // Offline machine-known recipient: address the exact id we were handed.
+      candidateIds.push(String(target).slice(0, 160));
     }
     const message = {
       id: sha16(`${from}|${to}|${body}|${now}|${crypto.randomBytes(4).toString('hex')}`),
@@ -2471,7 +2690,7 @@ export function formatReceivedMessages(messages, now = Date.now(), decay = {}, s
     lines.push(`- from ${senderLabel} (${ageMin}m ago): ${neutralizeMarkers(String(message.text || '').replace(/\s+/g, ' ').trim().slice(0, 400))}`);
     const receipts = group.map((item) => messageDeliveryReceipt(item, sessionId)).filter(Boolean);
     if (receipts.length) {
-      lines.push(`  Receipt(s): ${receipts.map((receipt) => `${receipt.messageId}:${receipt.offerToken}`).join(', ')}. After incorporating ${receipts.length === 1 ? 'it' : 'them'}, call brain_message_receipt with each exact message_id and offer_token.`);
+      lines.push(`  Receipt(s): ${receipts.map((receipt) => `${receipt.messageId}:${receipt.offerToken}`).join(', ')}. After incorporating ${receipts.length === 1 ? 'it' : 'them'}, call brain_message_receipt with each exact message_id and offer_token — that is the ONLY way the sender learns you acted on ${receipts.length === 1 ? 'it' : 'them'}. If you skip it, your next independent action auto-consumes ${receipts.length === 1 ? 'this note' : 'these notes'} and the sender is told only that ${receipts.length === 1 ? 'it was' : 'they were'} auto-consumed.`);
     }
     const info = messageDecayInfo({ ...message, ts: oldestTs }, now, decay);
     if (info) lines.push(`  ${info.stampText}`);

package/src/finding-routing.mjs

@@ -511,6 +511,14 @@ const receiptRecordMap = (message) => {
       state: ['pending', 'offered', 'acknowledged', 'consumed', 'failed'].includes(raw?.state)
         ? raw.state : 'offered',
       reason: raw?.reason ? String(raw.reason) : null,
+      // HOW consumption happened, not just THAT it did. Dropping this during
+      // normalization is the root cause of the receipt surfaces calling every
+      // consumption "explicit": the distinction was recorded on disk by
+      // agent-presence and then discarded one layer before the renderer, so no
+      // renderer could tell the strong claim from the weak one. Only the two
+      // values the writer actually sets are honoured; anything else is unknown.
+      consumedVia: raw?.consumedVia === 'receipt' || raw?.consumedVia === 'auto-lease'
+        ? raw.consumedVia : null,
     });
   }
   // Historical `seen` was stamped before output transport/model injection. It
@@ -551,6 +559,17 @@ export function summarizeReceipts({ messages, sessions, selfId, now = Date.now()
     const failed = stateIds('failed');
     const pending = candidateIds.filter((id) => !records.has(id) || records.get(id)?.state === 'pending');
     const unresolved = [...pending, ...offered, ...acknowledged].map((id) => String(id).slice(0, 8));
+    // WHY consumption is split: 'consumed' is reached two very different ways.
+    // 'receipt' is the strong claim — the recipient named the message id and offer
+    // token, i.e. "I acted on it". 'auto-lease' is the weak one — a later independent
+    // action merely followed the offer, which is evidence of activity, not of uptake.
+    // An ABSENT consumedVia is UNKNOWN, never auto-lease: the field is serialized only
+    // when set (agent-presence.mjs:507) and deleted on state reset (:588), so records
+    // written by an older bundled engine carry no marker and must not be miscounted.
+    const via = (id) => records.get(id)?.consumedVia || null;
+    const consumedByReceipt = consumed.filter((id) => via(id) === 'receipt');
+    const consumedByLease = consumed.filter((id) => via(id) === 'auto-lease');
+    const consumedUnknownVia = consumed.filter((id) => via(id) === null);
     return {
       id: m.id,
       to: m.to || 'all',
@@ -560,6 +579,9 @@ export function summarizeReceipts({ messages, sessions, selfId, now = Date.now()
       text: String(m.text || '').slice(0, 120),
       acknowledged: acknowledged.length,
       consumed: consumed.length,
+      consumedByReceipt: consumedByReceipt.length,
+      consumedByLease: consumedByLease.length,
+      consumedUnknownVia: consumedUnknownVia.length,
       // Compatibility alias for programmatic consumers. It now means a later
       // model-context acknowledgement milestone (including subsequently
       // consumed deliveries), never `seen` and never human-read.
@@ -571,6 +593,8 @@ export function summarizeReceipts({ messages, sessions, selfId, now = Date.now()
       offeredIds: offered.map((id) => String(id).slice(0, 8)),
       acknowledgedIds: acknowledged.map((id) => String(id).slice(0, 8)),
       consumedIds: consumed.map((id) => String(id).slice(0, 8)),
+      consumedByReceiptIds: consumedByReceipt.map((id) => String(id).slice(0, 8)),
+      consumedByLeaseIds: consumedByLease.map((id) => String(id).slice(0, 8)),
       failedIds: failed.map((id) => String(id).slice(0, 8)),
       deadLetterReason: m.deadLetter?.reason ? String(m.deadLetter.reason) : null,
     };
@@ -578,6 +602,35 @@ export function summarizeReceipts({ messages, sessions, selfId, now = Date.now()
   return { sent: receipts.length, receipts };
 }
 
+// ONE phrase, shared by every receipt surface. Two renderers drifting apart is how
+// "explicitly consumed" survived after auto-lease made it untrue on most paths, so
+// the wording lives in exactly one place and both callers below must use it.
+// `receipt.consumed === receipt.candidates` is the caller's precondition.
+export function fullConsumptionPhrase(receipt) {
+  const weak = (receipt.consumedByLease || 0) + (receipt.consumedUnknownVia || 0);
+  if (!weak) {
+    return `explicitly consumed by all ${receipt.candidates} target peer(s) via receipt (not human-read)`;
+  }
+  const parts = [];
+  if (receipt.consumedByReceipt) parts.push(`${receipt.consumedByReceipt} by explicit receipt`);
+  if (receipt.consumedByLease) parts.push(`${receipt.consumedByLease} auto-consumed after a later independent action`);
+  if (receipt.consumedUnknownVia) parts.push(`${receipt.consumedUnknownVia} consumed by an unrecorded route`);
+  return `consumed by all ${receipt.candidates} target peer(s) — ${parts.join(', ')}; auto-consumption is not proof the note was acted on, and never proof a human read it`;
+}
+
+// Shown only when some peers consumed by the weak route, so a partial line still
+// distinguishes uptake from mere activity.
+function partialConsumptionSplit(receipt) {
+  if (!receipt.consumed) return '';
+  const weak = (receipt.consumedByLease || 0) + (receipt.consumedUnknownVia || 0);
+  if (!weak) return '';
+  // 'auto-consumed' is itself a mechanism claim; an unknown-route record (older
+  // engine wrote it) must not be folded into it (2026-08-17 review catch).
+  return receipt.consumedUnknownVia
+    ? ` (${receipt.consumedByReceipt || 0} by receipt, ${weak} auto-consumed or unrecorded)`
+    : ` (${receipt.consumedByReceipt || 0} by receipt, ${weak} auto-consumed)`;
+}
+
 // One honest line per receipt. `pending` is listed by id-prefix up to 4 — a name
 // you can chase beats a number you can't.
 export function renderReceipt(receipt) {
@@ -590,14 +643,14 @@ export function renderReceipt(receipt) {
     return `- ${who}, ${age}: queued with no live local target snapshot; no local delivery is claimed. “${receipt.text}”`;
   }
   if (receipt.consumed === receipt.candidates && !receipt.failed) {
-    return `- ${who}, ${age}: explicitly consumed by all ${receipt.candidates} target peer(s) after model-context delivery (not human-read). “${receipt.text}”`;
+    return `- ${who}, ${age}: ${fullConsumptionPhrase(receipt)}. “${receipt.text}”`;
   }
   const pending = receipt.pendingIds.slice(0, 4).join(', ');
   const more = receipt.pendingIds.length > 4 ? ` +${receipt.pendingIds.length - 4} more` : '';
   const offered = receipt.offered ? ` · offered ${receipt.offered}, awaiting later-action ack` : '';
   const acknowledged = receipt.acknowledged ? ` · acknowledged ${receipt.acknowledged}, awaiting explicit consumption` : '';
   const failed = receipt.failed ? ` · failed ${receipt.failed}${failure ? ` (${failure})` : ''}` : '';
-  return `- ${who}, ${age}: consumed ${receipt.consumed} of ${receipt.candidates}${offered}${acknowledged}${failed}${pending ? ` · unresolved ${pending}${more}` : ''}. “${receipt.text}”`;
+  return `- ${who}, ${age}: consumed ${receipt.consumed} of ${receipt.candidates}${partialConsumptionSplit(receipt)}${offered}${acknowledged}${failed}${pending ? ` · unresolved ${pending}${more}` : ''}. “${receipt.text}”`;
 }
 
 // Compact, text-free receipt for surfaces that must stay cheap (SessionStart
@@ -615,14 +668,14 @@ export function renderReceiptSummary(summary) {
       : `📬 Your last note${target} (${age}): queued with no live local target snapshot; no local delivery claimed.`;
   }
   if (receipt.consumed === receipt.candidates && !receipt.failed) {
-    return `📬 Your last note${target} (${age}): explicitly consumed by all ${receipt.candidates} target peer(s) after model-context delivery (not human-read).`;
+    return `📬 Your last note${target} (${age}): ${fullConsumptionPhrase(receipt)}.`;
   }
   const pending = receipt.pendingIds.slice(0, 4).join(', ');
   const more = receipt.pendingIds.length > 4 ? ` +${receipt.pendingIds.length - 4} more` : '';
   const offered = receipt.offered ? ` · offered ${receipt.offered}, awaiting ack` : '';
   const acknowledged = receipt.acknowledged ? ` · acknowledged ${receipt.acknowledged}, awaiting explicit consumption` : '';
   const failed = receipt.failed ? ` · failed ${receipt.failed}${failure ? ` (${failure})` : ''}` : '';
-  return `📬 Your last note${target} (${age}): consumed ${receipt.consumed} of ${receipt.candidates}${offered}${acknowledged}${failed}${pending ? ` · unresolved ${pending}${more}` : ''}.`;
+  return `📬 Your last note${target} (${age}): consumed ${receipt.consumed} of ${receipt.candidates}${partialConsumptionSplit(receipt)}${offered}${acknowledged}${failed}${pending ? ` · unresolved ${pending}${more}` : ''}.`;
 }
 
 export function renderReceipts(summary, { limit = 3 } = {}) {

package/src/global-brain-hook.mjs

@@ -958,7 +958,11 @@ function peerFooter(sid) {
             const legend = marked.some(f => f.endsWith('*')) ? ' (* = observed from live edits, scope not declared)' : '';
             warn = `  · ⚠️ both edited: ${marked.join(', ')} — expect a conflict, KEEP BOTH${legend}`;
         }
-        else if (p.branch && myBranch && p.branch === myBranch) warn = '  · ⚠️ same branch — pull/rebase before you commit';
+        // State the fact, never the git operation. This runs in a latency-sensitive
+        // hook and must not spawn git, so it cannot know whether the branch is merely
+        // behind or has DIVERGED — and on a diverged branch "pull/rebase" is advice
+        // the real state contradicts. Naming the collision is what this footer is for.
+        else if (p.branch && myBranch && p.branch === myBranch) warn = '  · ⚠️ same branch — your commits will interleave; coordinate before you commit';
         // Unique over the full live list (not just shown peers) — the MSG router
         // resolves a prefix against every row, so uniqueness must match that set.
         lines.push(`- session ${shortestUniquePeerPrefix(list, p.id)} · ${bits.join(' · ')}${warn}`);
@@ -966,7 +970,7 @@ function peerFooter(sid) {
     // v1.32.0 law: a truncated list must never render as a complete one. This
     // overflow line is unconditional — never subject to any budget.
     if (peers.length > 4) lines.push(`- …and ${peers.length - 4} more live session(s) not shown — \`npx klypix-mcp doctor\` or brain_sync lists all.`);
-    lines.push('Coordinate BEFORE touching shared files: reply with `🧠 MSG [<their id-prefix or branch>]: <text>` (or call `brain_message`). KLYPIX queues it for supported lifecycle/MCP actions and replays it until the receiving model explicitly records consumption with `brain_message_receipt`. Check the brain for durable decisions/ships.');
+    lines.push('Coordinate BEFORE touching shared files: reply with `🧠 MSG [<their id-prefix or branch>]: <text>` (or call `brain_message`). KLYPIX queues it for supported lifecycle/MCP actions and replays it until the offer is acknowledged; the receiver then either records uptake with `brain_message_receipt` or a further independent action auto-consumes it without one. Check the brain for durable decisions/ships.');
     return lines.join('\n');
 }
 

package/src/klypix-core.mjs

@@ -1189,7 +1189,7 @@ export async function opBrainMessage({ vault, canvas, text: msgText, to, via, fr
   const message = result.message;
   const candidates = Array.isArray(message.candidateIds) ? message.candidateIds.length : 0;
   return {
-    blocks: [text(`📨 queued in this project's coordination lane (to: ${message.to}; id: ${message.id}) — ${candidates} live target session(s) were snapshotted. Delivery is pending until a supported lifecycle/MCP action offers it into model-visible context; it replays through acknowledgement until the receiver explicitly records consumption with brain_message_receipt. This is a coordination receipt, not proof a human read it and not a brain card — use brain_note for durable project decisions.`)],
+    blocks: [text(`📨 queued in this project's coordination lane (to: ${message.to}; id: ${message.id}) — ${candidates} live target session(s) were snapshotted. Delivery is pending until a supported lifecycle/MCP action offers it into model-visible context, and it replays until the offer is acknowledged. AFTER acknowledgement it retires one of two ways: the receiver calls brain_message_receipt with the exact message id and offer token ("acted on it"), or a further independent action AUTO-CONSUMES it without any receipt. Your receipt line names which. Auto-consumption is not proof the note was acted on, and no path here is proof a human read it. Not a brain card — use brain_note for durable project decisions.`)],
     message,
   };
 }

package/src/klypix-format.mjs

@@ -2002,6 +2002,33 @@ export function rankForQuestion(struct, question, { semantic = null, k = 10, as_
         // the embedding side, not from reweighting here. The kept behaviors are
         // pinned numerically in test/retrieval-fusion.mjs — a change that trips
         // that suite must re-run the harness before shipping.
+        //
+        // THE EMBEDDING SIDE WAS THEN SWEPT TOO (2026-08-17, n=113 frozen v2,
+        // real 2,553-card brain, production contract via embedTexts — prefix,
+        // CLS, normalize; ordering = this function's semantic formula):
+        //   bge-small q8 (ships)  MRR .436 · @5 61 · paraphrase 46   baseline
+        //   bge-small fp32        MRR .456 · @5 60 · paraphrase 46   — so the
+        //     q8 quantization is NOT the ceiling; the 384-dim model is.
+        //   bge-base  q8 (768d)   MRR .475 · @5 61 · paraphrase 51 [39,63] vs
+        //     [34,58] — every needle right, none CI-clearing, at 2.4× embed
+        //     cost (622s vs 255s full-brain) and ~3× download. NOT flipped.
+        //   exact-duplicate collapse at rank time: FLAT (61→61, para 46→46),
+        //     confirming the MMR-deferral result above by a second route.
+        //   1,500-char truncation: measurably NOT a failure mode — gold cards
+        //     >1,500 chars score BETTER (@5 71% vs 57%), and 0 of 34 paraphrase
+        //     misses attribute to it. "We truncate, therefore we miss" is
+        //     falsified; do not chunk on that rationale.
+        //   (gte-small collapsed to MRR .17 under this contract — it wants mean
+        //     pooling and no prefix, so that number is contract mismatch, not a
+        //     fair test of gte.)
+        // Failure signature stands: cosine COMPRESSION — on paraphrase misses
+        // the gold sits a median 0.040 cosine below the 5th hit, 21/34 at rank
+        // >50, 6/34 outside the 200 pool. Same-class drop-in models do not fix
+        // that on this corpus. The remaining live path is DOC-SIDE enrichment
+        // (capture-time question/intent text embedded alongside the card) or a
+        // genuinely larger embedder — both are product decisions with shipping
+        // costs, not tuning. Runner: scratchpad ab-runner.mjs pattern — embed
+        // through embedTexts with a swapped pipe, never a hand-copied contract.
         const semRank = new Map(scored
             .filter(hit => Number.isFinite(hit.sem))
             .sort((a, b) => b.sem - a.sem)