klypix-mcp 1.74.0 → 1.75.0

package/bin/klypix-worker.mjs

@@ -791,9 +791,14 @@ server.registerTool('brain_sync', {
       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(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, 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.'),
+    }).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.74.0",
+  "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-claim-join.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')}`),

package/src/mcp-presence.mjs

@@ -22,9 +22,14 @@ import {
   messageDecayInfo,
   peekMessages,
   pinLaneIdentity,
+  neutralizeMarkers,
   postPresenceMessage,
+  readReleaseClaims,
   readReleaseLease,
   receiveMessages,
+  retireFulfilledClaims,
+  stakeReleaseClaim,
+  withdrawReleaseClaim,
   refreshReleaseLease,
   rekeySessionIdentity,
   rotateEndedSessionIdentity,
@@ -40,7 +45,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, commitFiles, releaseAncestry, releaseAncestryWarnings, repoStateWarnings } from './repo-state.mjs';
+import { cmpSemver3, collectRepoState, commitFiles, releaseAncestry, releaseAncestryWarnings, repoStateWarnings, settleClaimsAgainstRef } from './repo-state.mjs';
 import { recordResultManifests } from './result-reconcile.mjs';
 
 export const MCP_HEARTBEAT_MS = 60_000;
@@ -273,6 +278,49 @@ export function validateReleaseIntent(value) {
   return { provided: true, ok: true, version: version.replace(/^v/i, ''), ref, acknowledge };
 }
 
+/**
+ * Validate the releaseClaim input — the durable "my commits ride the next
+ * build" promise. Fail-closed like releaseIntent: a malformed claim must
+ * never half-sync, and never silently stake less than the caller asked
+ * (the 1.74.0 acknowledge-slice lesson, applied at the door).
+ * Shapes: { shas: [...], note? } stakes/extends; { withdraw: [...] } trims
+ * ({ withdraw: [] } or { withdraw: true } clears the whole claim).
+ */
+export function validateReleaseClaim(value) {
+  if (value === undefined || value === null) return { provided: false, ok: true };
+  const errors = [];
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return { provided: true, ok: false, errors: ['releaseClaim must be an object: { shas: [...], note? } to stake, { withdraw: [...] } to withdraw'] };
+  }
+  const hasStake = value.shas !== undefined;
+  const hasWithdraw = value.withdraw !== undefined;
+  if (hasStake === hasWithdraw) {
+    errors.push('releaseClaim needs exactly one of `shas` (stake) or `withdraw`');
+  }
+  const parseShas = (raw, field) => {
+    if (!Array.isArray(raw)) { errors.push(`releaseClaim.${field} must be an array of commit shas`); return []; }
+    const clean = [...new Set(raw
+      .filter((x) => typeof x === 'string')
+      .map((x) => x.trim().toLowerCase())
+      .filter((x) => /^[0-9a-f]{4,40}$/.test(x)))];
+    if (raw.length && !clean.length) errors.push(`releaseClaim.${field} contained no valid shas (4-40 hex chars each)`);
+    if (clean.length > 20) errors.push(`releaseClaim.${field} carries ${clean.length} shas — the limit is 20; claim the branch-defining commits, not the whole history`);
+    return clean;
+  };
+  let shas = [];
+  let withdrawShas = [];
+  let withdrawAll = false;
+  if (hasStake) shas = parseShas(value.shas, 'shas');
+  if (hasWithdraw) {
+    if (value.withdraw === true || (Array.isArray(value.withdraw) && !value.withdraw.length)) withdrawAll = true;
+    else if (value.withdraw === false) errors.push('releaseClaim.withdraw: false does nothing — omit the field to keep the claim, or pass true / [] to withdraw it entirely');
+    else withdrawShas = parseShas(value.withdraw, 'withdraw');
+  }
+  const note = typeof value.note === 'string' ? value.note.replace(/\s+/g, ' ').trim().slice(0, 160) : null;
+  if (errors.length) return { provided: true, ok: false, errors };
+  return { provided: true, ok: true, stake: hasStake, shas, withdraw: hasWithdraw, withdrawShas, withdrawAll, note };
+}
+
 /**
  * Does this acknowledgement actually name what the release would drop?
  *
@@ -2074,6 +2122,7 @@ export function createMcpPresence({
     phase = 'checkpoint',
     results,
     releaseIntent,
+    releaseClaim,
     deliverMessages = true,
     include_context,
     actionId = '',
@@ -2103,6 +2152,23 @@ export function createMcpPresence({
       ].join('\n');
       return report;
     }
+    const releaseClaimChecked = validateReleaseClaim(releaseClaim);
+    if (releaseClaimChecked.provided && !releaseClaimChecked.ok) {
+      const report = syncPreflightFailure({
+        status: 'invalid-release-claim',
+        reason: 'release-claim-malformed',
+        requestedProject: typeof project === 'string' ? project.slice(0, 512) : null,
+      });
+      report.structured.phase = nextPhase;
+      report.structured.errors = releaseClaimChecked.errors.map((message) => ({ message }));
+      report.structured.timingMs.coordination = Math.max(0, Date.now() - syncStartedAt);
+      report.text = [
+        'KLYPIX release claim was rejected; no task, lease, claim, presence, or message state changed.',
+        ...releaseClaimChecked.errors.map((error) => `- ${error}`),
+        'Supply releaseClaim as { shas: ["<sha>", ...], note?: "why it matters" } to stake, or { withdraw: [...] } to withdraw.',
+      ].join('\n');
+      return report;
+    }
     const preflightInput = {
       project,
       projectProvided: project !== undefined,
@@ -2648,9 +2714,36 @@ export function createMcpPresence({
     let releaseAdvisoryText = '';
     let workAtRisk = null;
     let workAtRiskText = '';
+    let releaseClaimResult = null;
     {
       const leaseStamp = now();
       let outcome = null;
+      // ── Release CLAIM: the durable "my commits ride the next build" ──────
+      // Executed BEFORE any releaseIntent gating in the same call, so a
+      // stake+declare combination sees its own fresh claim — symmetric with
+      // every other session's, deliberately.
+      if (releaseClaimChecked.provided) {
+        const selfRow = (report.sessions || []).find((s) => s?.id === sessionId) || {};
+        releaseClaimResult = releaseClaimChecked.withdraw
+          ? withdrawReleaseClaim({
+            brainPath,
+            sessionId,
+            shas: releaseClaimChecked.withdrawAll ? [] : releaseClaimChecked.withdrawShas,
+            home,
+            now: leaseStamp,
+          })
+          : stakeReleaseClaim({
+            brainPath,
+            sessionId,
+            client: (preparedClientInfo || {}).client || selfRow.client || 'unknown',
+            logicalSessionId: selfRow.logicalSessionId || null,
+            branch: selfRow.branch || null,
+            shas: releaseClaimChecked.shas,
+            note: releaseClaimChecked.note,
+            home,
+            now: leaseStamp,
+          });
+      }
       // Set when the holder's own sync arrived with the lease already close to
       // lapsing; reported after the refresh so the holder learns the habit that
       // protects them, not merely that nothing broke this time.
@@ -2680,9 +2773,14 @@ export function createMcpPresence({
         // 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.
+        // Only a NEW declaration is ANCESTRY-gated. A holder refreshing the
+        // same ref is never re-blocked on ancestry — that would be an obstacle,
+        // not a gate — and a deliberate off-trunk hotfix is one acknowledged
+        // call away. CLAIMS are the one exception: they settle on every
+        // declaration, because a claim staked after the lease was taken is
+        // exactly the promise the window between lease and build would
+        // otherwise swallow; acknowledgements persist on the lease so the
+        // holder re-litigates only what is genuinely NEW.
         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.
@@ -2717,9 +2815,55 @@ export function createMcpPresence({
             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 };
+        // ── STAKED CLAIMS gate — settled on EVERY declaration, including a
+        // holder's same-ref refresh. Ancestry compares trunk and LIVE peer
+        // branches; a claim covers exactly the hole that leaves: a commit whose
+        // owner has closed their session and whose branch nobody is on any
+        // more. A claim staked AFTER the lease was taken must still gate the
+        // next sync, or the window between lease and build is where a promise
+        // goes to die. Per-sha probe failures inside the settlement BLOCK
+        // (missing), never pass; only a catastrophic throw degrades to empty,
+        // and ancestry still stands guard on that path.
+        let claimSettlement = [];
+        try {
+          const stakedClaims = readReleaseClaims({ brainPath, home, now: leaseStamp });
+          if (stakedClaims.length) {
+            claimSettlement = settleClaimsAgainstRef(path.dirname(brainPath), releaseIntentChecked.ref, stakedClaims);
+          }
+        } catch { claimSettlement = []; }
+        const unmetClaims = claimSettlement.filter((entry) => !entry.contained);
+        const claimShasRequired = [...new Set(unmetClaims
+          .flatMap((entry) => [...entry.missing, ...entry.unresolvable, ...entry.unverified])
+          .map((sha) => String(sha).toLowerCase()))];
+        // The holder's PERSISTED acknowledgements count too (review blocker B1):
+        // a refresh checkpoint re-attaching the same releaseIntent must not be
+        // refused over a claim the holder already acknowledged at grant time.
+        // A claim staked SINCE then still gates — its shas are in no lease
+        // record — which is exactly the window the settle-on-every-declaration
+        // rule exists for.
+        const leaseAcks = sameRefAsHeld && Array.isArray(existingLease?.acknowledgedShas)
+          ? existingLease.acknowledgedShas : [];
+        const ackGiven = [...new Set([
+          ...(releaseIntentChecked.acknowledge || []),
+          ...leaseAcks,
+        ].map((g) => String(g).toLowerCase()))];
+        const claimsAcknowledged = claimShasRequired
+          .every((sha) => ackGiven.some((g) => sha.startsWith(g) || g.startsWith(sha)));
+        const ancestryBlocks = gateAncestry && !gateAncestry.isDescendant
+          && !ancestryAcknowledged(gateAncestry, ackGiven);
+        const claimsRefuse = claimShasRequired.length > 0 && !claimsAcknowledged;
+        if (ancestryBlocks || claimsRefuse) {
+          outcome = {
+            ok: false,
+            status: ancestryBlocks ? 'ancestry-unacknowledged' : 'claims-unacknowledged',
+            ancestry: gateAncestry
+              || { status: 'ok', ref: releaseIntentChecked.ref, isDescendant: true, missingCount: 0, sources: [], missing: [] },
+            unmetClaims,
+            // The refusal headline must not lie to a HOLDER: their held lease
+            // was not revoked — it just was not refreshed by this sync, and it
+            // lapses at TTL unless the new claim is acknowledged.
+            holderRefusal: sameRefAsHeld,
+          };
         } else {
           outcome = declareReleaseLease({
             brainPath,
@@ -2729,8 +2873,11 @@ export function createMcpPresence({
             client: (preparedClientInfo || {}).client || 'unknown',
             home,
             now: leaseStamp,
+            acknowledgedShas: ackGiven,
           });
           if (gateAncestry && !gateAncestry.isDescendant) outcome = { ...outcome, acknowledgedAncestry: gateAncestry };
+          if (unmetClaims.length) outcome = { ...outcome, acknowledgedClaims: unmetClaims };
+          if (claimSettlement.length) outcome = { ...outcome, claimSettlement };
         }
       } else if (clearCompletionScope) {
         const freed = freeReleaseLease({ brainPath, sessionId, home, now: leaseStamp });
@@ -2766,8 +2913,23 @@ export function createMcpPresence({
         refreshedAt: active.refreshedAt,
         expiresAt: active.expiresAt,
       } : null;
-      if (outcome?.status === 'ancestry-unacknowledged') {
+      if (outcome?.status === 'ancestry-unacknowledged' || outcome?.status === 'claims-unacknowledged') {
         const anc = outcome.ancestry;
+        // Staked-claim requirement rides the SAME refusal and the SAME
+        // acknowledge array: one gate, one handshake, whichever half tripped.
+        const unmetClaims = Array.isArray(outcome.unmetClaims) ? outcome.unmetClaims : [];
+        const claimShas = [...new Set(unmetClaims
+          .flatMap((entry) => [...entry.missing, ...entry.unresolvable, ...entry.unverified])
+          .map((sha) => String(sha).toLowerCase()))];
+        const claimLines = unmetClaims.map((entry) => {
+          const c = entry.claim;
+          const ageDays = Math.max(0, Math.round((leaseStamp - (c.stakedAt || leaseStamp)) / 86_400_000));
+          const parts = [];
+          if (entry.missing.length) parts.push(`${entry.missing.length} NOT in ${releaseIntentChecked.ref}: ${entry.missing.slice(0, 4).map((x) => x.slice(0, 9)).join(', ')}${entry.missing.length > 4 ? ` +${entry.missing.length - 4}` : ''}`);
+          if (entry.unresolvable.length) parts.push(`${entry.unresolvable.length} unresolvable (history rewritten? owner must re-stake): ${entry.unresolvable.slice(0, 3).map((x) => x.slice(0, 9)).join(', ')}`);
+          if (entry.unverified.length) parts.push(`${entry.unverified.length} unverified (probe budget)`);
+          return neutralizeMarkers(`STAKED CLAIM UNMET — session ${String(c.ownerId).slice(0, 8)} (${c.ownerClient}${c.branch ? `, ${c.branch}` : ''}) staked ${ageDays}d ago${c.note ? `: "${c.note}"` : ''} — ${parts.join(' · ')}. The owner may no longer be live; this claim is their voice.`);
+        });
         // The COMPLETE set the gate will demand, not the subset the prose names.
         // These two used to be the same list, which is how a release dropping 71
         // commits was acknowledged by naming 10. The prose still shows 8 per
@@ -2807,20 +2969,41 @@ export function createMcpPresence({
           // (2026-08-17 review catch — the primary fix renders bare shas at the
           // source so 'unnameable' now truly means no shas at all; this guard is
           // the belt to that suspender).
-          acknowledgeRequired: anc.status === 'unnameable' ? [] : shas,
+          acknowledgeRequired: [...new Set([...(anc.status === 'unnameable' ? [] : shas), ...claimShas])],
+          ...(unmetClaims.length ? { stakedClaims: unmetClaims.map((entry) => ({
+            owner: String(entry.claim.ownerId).slice(0, 8),
+            ownerClient: entry.claim.ownerClient,
+            branch: entry.claim.branch,
+            note: entry.claim.note,
+            stakedAt: entry.claim.stakedAt,
+            missing: entry.missing,
+            unresolvable: entry.unresolvable,
+            unverified: entry.unverified,
+          })) } : {}),
         };
+        const claimsOnlyImperative = (!(anc && !anc.isDescendant) && unmetClaims.length)
+          ? [
+            '',
+            'WHAT THIS MEANS FOR THE USER: the branch history is clean, but a session STAKED A CLAIM that specific commits must ride this release, and they are not in it. That session may have already told the user this work would ship — the claim is the only voice it has left.',
+            'Say this to them in your own words, naming the claim(s) above, BEFORE going any further.',
+          ]
+          : [];
         releaseText = [
-          'KLYPIX release lease REFUSED — the lease was not taken. No release state changed.',
+          outcome.holderRefusal
+            ? 'KLYPIX release refresh REFUSED — a claim staked SINCE your lease was granted is unmet. Your held lease was NOT revoked, but this sync did NOT refresh it: acknowledge the claim below or the lease lapses at its ~2h TTL.'
+            : 'KLYPIX release lease REFUSED — the lease was not taken. No release state changed.',
           '',
           ...releaseAncestryWarnings(anc),
+          ...(claimLines.length ? ['', ...claimLines] : []),
+          ...claimsOnlyImperative,
           '',
           // 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.
-          (anc.status !== 'unnameable' && shas.length)
+          ((anc.status !== 'unnameable' && shas.length) || claimShas.length)
             ? [
-              `To proceed anyway, re-send releaseIntent with an "acknowledge" array naming each of the ${shas.length} sha(s) in acknowledgeRequired.`,
+              `To proceed anyway, re-send releaseIntent with an "acknowledge" array naming each of the ${new Set([...(anc.status === 'unnameable' ? [] : shas), ...claimShas]).size} sha(s) in acknowledgeRequired.`,
               unnamed
                 ? `NOTE: only ${shas.length - unnamed} of those ${shas.length} are spelled out above — ${unnamed} more are in acknowledgeRequired and are NOT shown in this text. Read them before you decide; the prose is a sample, the requirement is the whole set.`
                 : '',
@@ -2855,15 +3038,101 @@ export function createMcpPresence({
         releaseLease = { status: 'declare-failed', reason: outcome.status };
         releaseText = `KLYPIX release lease was not recorded (${outcome.status}); no lease state changed. Retry on the next sync.`;
       } else if (outcome?.status === 'taken' || outcome?.status === 'refreshed') {
+        // ── Claim settlement on a GRANTED lease ──────────────────────────
+        // Fulfilled claims retire (their shas are in the ref — the promise is
+        // kept, with a courtesy note to the owner). Acknowledged-away claims
+        // STAY STAKED — the work still is not shipping — and their owners are
+        // notified NOW, at declare time, not after the build exists: today the
+        // releaser sees the OWNED-BY warning but the owner learns only when
+        // the installer is missing their feature (founder-surfaced 2026-08-17).
+        const fulfilledClaims = (outcome.claimSettlement || []).filter((entry) => entry.contained);
+        const awayClaims = Array.isArray(outcome.acknowledgedClaims) ? outcome.acknowledgedClaims : [];
+        let claimsNotified = 0;
+        if (fulfilledClaims.length) {
+          try {
+            retireFulfilledClaims({
+              brainPath,
+              fulfilled: fulfilledClaims.map((entry) => ({ ownerId: entry.claim.ownerId, shas: entry.claim.shas })),
+              home,
+              now: leaseStamp,
+            });
+          } catch { /* retirement is best-effort; a live claim re-settles next declare */ }
+          for (const entry of fulfilledClaims) {
+            if (entry.claim.ownerId === sessionId) continue;
+            const posted = postPresenceMessage({
+              brainPath,
+              from: sessionId,
+              // Logical identity preferred: a revived session matches it directly,
+              // and a SINGLE candidate keeps the receipt denominator honest.
+              to: entry.claim.ownerLogicalId || entry.claim.ownerId,
+              text: `Your staked release claim is FULFILLED: v${releaseIntentChecked.version} declared from ${releaseIntentChecked.ref} CONTAINS your ${entry.claim.shas.length} claimed commit(s) (${entry.claim.shas.slice(0, 3).map((x) => x.slice(0, 9)).join(', ')}${entry.claim.shas.length > 3 ? '…' : ''}). The claim is retired.`,
+              allowOfflineTarget: true,
+              dedupeKey: `claim-fulfilled|${entry.claim.ownerId}|${releaseIntentChecked.version}`,
+              home,
+              now: leaseStamp,
+            });
+            if (posted.posted) claimsNotified++;
+          }
+        }
+        const notifiedOwners = new Set();
+        for (const entry of awayClaims) {
+          if (entry.claim.ownerId === sessionId) continue;
+          notifiedOwners.add(entry.claim.ownerId);
+          const gone = [...entry.missing, ...entry.unresolvable, ...entry.unverified];
+          const posted = postPresenceMessage({
+            brainPath,
+            from: sessionId,
+            to: entry.claim.ownerLogicalId || entry.claim.ownerId,
+            text: `Release v${releaseIntentChecked.version} from ${releaseIntentChecked.ref} was declared ACKNOWLEDGING AWAY your claimed commit(s) ${gone.slice(0, 4).map((x) => String(x).slice(0, 9)).join(', ')}${gone.length > 4 ? ` +${gone.length - 4}` : ''} — they will NOT be in this build. Your claim stays staked for the next release.`,
+            allowOfflineTarget: true,
+            dedupeKey: `claim-away|${entry.claim.ownerId}|${releaseIntentChecked.version}|${releaseIntentChecked.ref}`,
+            home,
+            now: leaseStamp,
+          });
+          if (posted.posted) claimsNotified++;
+        }
+        // LIVE owners named by the ancestry annotation get the same courtesy —
+        // their commits were acknowledged away too, they just never staked.
+        const ancOwners = new Map();
+        for (const src of (outcome.acknowledgedAncestry?.sources || [])) {
+          for (const c of (src.missing || [])) {
+            for (const o of (c.owners || [])) {
+              if (o.sharedScopeOnly || !o.sessionId || o.sessionId === sessionId) continue;
+              if (notifiedOwners.has(o.sessionId)) continue;
+              const cur = ancOwners.get(o.sessionId) || [];
+              if (cur.length < 4) cur.push(`${c.sha} ${String(c.subject || '').slice(0, 60)}`.trim());
+              ancOwners.set(o.sessionId, cur);
+            }
+          }
+        }
+        for (const [ownerId, commits] of ancOwners) {
+          const posted = postPresenceMessage({
+            brainPath,
+            from: sessionId,
+            to: ownerId,
+            text: `Release v${releaseIntentChecked.version} from ${releaseIntentChecked.ref} was declared ACKNOWLEDGING AWAY commit(s) of yours: ${commits.join(' · ')} — they will NOT be in this build. Stake a releaseClaim if they must ride the next one.`,
+            allowOfflineTarget: true,
+            dedupeKey: `anc-away|${ownerId}|${releaseIntentChecked.version}|${releaseIntentChecked.ref}`,
+            home,
+            now: leaseStamp,
+          });
+          if (posted.posted) claimsNotified++;
+        }
         releaseLease = {
           status: outcome.status,
           ...(outcome.reclaimed ? { reclaimed: outcome.reclaimed } : {}),
           ...(holderBlock ? { holder: holderBlock } : {}),
+          ...(fulfilledClaims.length ? { claimsFulfilled: fulfilledClaims.length } : {}),
+          ...(awayClaims.length ? { claimsAcknowledgedAway: awayClaims.length } : {}),
+          ...(claimsNotified ? { claimOwnersNotified: claimsNotified } : {}),
         };
         if (releaseIntentChecked.provided) {
           releaseText = outcome.status === 'taken'
             ? `KLYPIX release lease taken: this session now EXCLUSIVELY holds release preparation for v${releaseIntentChecked.version} from ${releaseIntentChecked.ref}${outcome.reclaimed ? ` (reclaimed: the previous lease was ${outcome.reclaimed === 'expired' ? 'expired' : 'held by a session that is no longer live'})` : ''}. Checkpoints refresh the ~2h lease; phase "complete" frees it.`
             : `KLYPIX release lease refreshed: v${releaseIntentChecked.version} from ${releaseIntentChecked.ref}.`;
+          if (fulfilledClaims.length || awayClaims.length) {
+            releaseText += ` Claims: ${fulfilledClaims.length} fulfilled${awayClaims.length ? `, ${awayClaims.length} ACKNOWLEDGED AWAY (their owners were queued a notification — the work is NOT in this build)` : ''}.`;
+          }
         }
       } else if (outcome?.status === 'lease-lost') {
         releaseLease = { status: 'lease-lost', reason: outcome.reason || null };
@@ -3042,6 +3311,8 @@ export function createMcpPresence({
       // refresh / conflict / release outcome plus the current holder — and the
       // zero-config checkout-ahead advisory when nothing is declared.
       ...(releaseLease ? { releaseLease } : {}),
+      // Additive: outcome of a releaseClaim stake/withdraw carried in THIS call.
+      ...(releaseClaimResult ? { releaseClaim: releaseClaimResult } : {}),
       ...(releaseAdvisory ? { releaseAdvisory } : {}),
       ...(workAtRisk ? { workAtRisk } : {}),
       ...(resultReconciliation ? { resultReconciliation: {
@@ -3091,6 +3362,11 @@ export function createMcpPresence({
       `KLYPIX Context Gateway: session ${sessionId} · phase ${nextPhase} · coordination ${durationMs}ms.`,
       deferralText,
       resultText,
+      releaseClaimResult
+        ? (releaseClaimResult.ok
+          ? `KLYPIX release claim ${releaseClaimResult.status}${releaseClaimResult.claim ? `: ${releaseClaimResult.claim.shas.length} sha(s) staked — every future releaseIntent must contain them or acknowledge them BY NAME, even after this session ends (expires ${Math.round((releaseClaimResult.claim.expiresAt - syncStartedAt) / 86_400_000)}d)` : ''}${releaseClaimResult.status === 'trimmed' || releaseClaimResult.status === 'withdrawn' ? ` (${releaseClaimResult.remaining ?? 0} sha(s) remain staked)` : ''}.`
+          : `KLYPIX release claim FAILED (${releaseClaimResult.status}${releaseClaimResult.limit ? `, limit ${releaseClaimResult.limit}` : ''}) — nothing was staked or withdrawn. ${releaseClaimResult.status === 'claims-full' ? 'The lane holds its maximum of staked claims; withdraw a stale one or raise it with the maintainers.' : ''}`)
+        : '',
       releaseText,
       formatTaskPresence(snapshot, stamp),
       messagesText,

package/src/repo-state.mjs

@@ -221,6 +221,71 @@ export function commitFiles(projectDir, shas, { execGit = defaultExecGit, timeou
   return out;
 }
 
+/**
+ * Settle staked release claims against the release ref.
+ *
+ * A claim is the durable half of "you'll see it in the next build": shas an
+ * owner promised would ride the next release, surviving the owner's session.
+ * Ancestry compares trunk and LIVE peer branches; a claim covers exactly the
+ * hole that leaves — a commit on a branch nobody is on any more.
+ *
+ * Per sha, three honest outcomes: contained in the ref, MISSING from it, or
+ * UNRESOLVABLE (the sha is gone — rebase/squash rewrote it, or the branch was
+ * deleted). Unresolvable is reported as its own state, never silently treated
+ * as contained (that would let history rewriting clear a claim) and never as
+ * missing (the remedy differs: the owner must re-stake the rewritten shas).
+ *
+ * Bounded: at most `maxChecks` unique shas are probed; anything beyond is
+ * marked unverified and SAID so — a capped check must never read as a full one.
+ */
+export function settleClaimsAgainstRef(projectDir, ref, claims, { execGit = defaultExecGit, maxChecks = 64 } = {}) {
+  const git = makeGit(execGit);
+  const dir = String(projectDir || '');
+  const target = String(ref || '').trim();
+  const list = Array.isArray(claims) ? claims : [];
+  if (!dir || !target || !list.length) return [];
+  const verdictCache = new Map();   // sha -> 'contained' | 'missing' | 'unresolvable' | 'unverified'
+  let checks = 0;
+  const verdictFor = (sha) => {
+    if (verdictCache.has(sha)) return verdictCache.get(sha);
+    let verdict;
+    if (checks >= maxChecks) {
+      verdict = 'unverified';
+    } else {
+      checks++;
+      if (git(dir, ['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]) === null) {
+        verdict = 'unresolvable';
+      } else {
+        // makeGit maps a non-zero exit to null, so "not an ancestor" and a
+        // failed spawn look identical here — both must BLOCK (missing), never
+        // pass: over-reporting is a conversation, under-reporting ships a
+        // build without the claimed work.
+        verdict = git(dir, ['merge-base', '--is-ancestor', sha, target]) === null ? 'missing' : 'contained';
+      }
+    }
+    verdictCache.set(sha, verdict);
+    return verdict;
+  };
+  return list.map((claim) => {
+    const missing = [];
+    const unresolvable = [];
+    const unverified = [];
+    for (const sha of claim.shas || []) {
+      const verdict = verdictFor(String(sha).toLowerCase());
+      if (verdict === 'missing') missing.push(sha);
+      else if (verdict === 'unresolvable') unresolvable.push(sha);
+      else if (verdict === 'unverified') unverified.push(sha);
+    }
+    return {
+      claim,
+      missing,
+      unresolvable,
+      unverified,
+      contained: !missing.length && !unresolvable.length && !unverified.length,
+    };
+  });
+}
+
 export function releaseAncestry(projectDir, ref, { execGit = defaultExecGit, peerBranches = [] } = {}) {
   const git = makeGit(execGit);
   const dir = String(projectDir || '');