klypix-mcp 1.69.0 → 1.70.0

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'diff', 'pr-brief', 'uninstall', 'bench']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'orphans', 'diff', 'pr-brief', 'uninstall', 'bench']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -38,6 +38,7 @@ const USAGE = [
   '  git-hook [install|remove|status]    wire the agent-neutral commit-capture hook (any agent/branch/worktree → brain cards)',
   '  brain-history [list|restore <id>]   restore points for this brain — undo an accidental delete, edit, or overwrite',
   '  brain-deleted [list|restore|purge]  recycle bin for this brain — cards you deleted, kept recoverable',
+  '  orphans [brain] [--apply|--areas]   orphan gardener backfill: report unconnected cards, link the confident subset (dry-run default)',
   '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
   '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',
   '',

package/bin/klypix-orphans.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// klypix-orphans — `npx klypix-mcp orphans`. The orphan gardener's backfill pass:
+// report how many live decision/milestone cards have NO connections, and link the
+// CONFIDENT subset in one pass using the same selector capture uses
+// (proposeOrphanAnchorLinks): at most ONE lexical-anchor edge per card — exact
+// [[wikilink]], exact file-slug tag, or an unambiguous ≥0.6 title overlap —
+// never a fan-out, never a guess among multiple candidates.
+//
+//   npx klypix-mcp orphans [brain]        # DRY RUN (default) — report, write nothing
+//   npx klypix-mcp orphans --apply        # draw the confident edges (restore point first)
+//   npx klypix-mcp orphans --areas        # ALSO include each orphan's area-container edge
+//   npx klypix-mcp orphans --json         # machine-readable report
+//
+// Contract: additive + lossless — no card is archived, rewritten, or moved; every
+// arrow remains individually removable in KLYPIX. `--apply` takes a FORCED restore
+// point via the brain-history machinery before writing, so the whole pass is one
+// `brain-history restore` away from undone. Dry-run is the default because a
+// backfill touches history, not just this session's capture.
+//
+// `--areas` is opt-in for backfill (unlike capture, where the area edge is part
+// of the no-new-orphans contract): mass-adding hundreds of containment edges to
+// an old brain is a layout decision the human should make deliberately.
+//
+// Synchronous top-level by design: the dispatcher does `await import(this);
+// process.exit(0)`, so all work must complete during module evaluation. ARGV is
+// the standalone shape — the dispatcher splices its verb out first (runVerb).
+import fs from 'fs';
+import path from 'path';
+import { parseKlypix, brainInsights, proposeOrphanAnchorLinks, addBrainConnections, atomicWrite } from '../src/klypix-format.mjs';
+import { snapshotBrain } from '../src/brain-history.mjs';
+import { withAdvisoryWriteLock, brainCaptureLockPath } from '../src/brain-write-lock.mjs';
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+try {
+  const raw = process.argv.slice(2);
+  const argv = (raw[0] === 'orphans' && !isDir(path.resolve(raw[0]))) ? raw.slice(1) : raw;
+  const apply = argv.includes('--apply');
+  const withAreas = argv.includes('--areas');
+  const json = argv.includes('--json');
+  const pathArg = argv.find(a => !a.startsWith('-'));
+  const file = path.resolve(process.cwd(), pathArg || 'brain.klypix');
+  if (!fs.existsSync(file)) {
+    console.error(`No brain at ${file} — run from the project folder (or pass a path).`);
+    process.exit(1);
+  }
+
+  const { struct } = await parseKlypix(fs.readFileSync(file));
+  const before = brainInsights(struct).orphans;
+  const byId = new Map(struct.cards.map(c => [c.id, c]));
+  const flat = (id) => {
+    const c = byId.get(id);
+    if (!c) return id;
+    const s = c.type === 'container' ? `[area] ${c.title || ''}` : String(c.text || '').replace(/\s+/g, ' ').trim();
+    return s.slice(0, 70);
+  };
+
+  const proposals = proposeOrphanAnchorLinks(struct);
+  const anchored = proposals.filter(p => p.anchor);
+  // The confident subset: anchor edges always; area edges only with --areas.
+  // Reversed twins (A anchors B, B anchors A) collapse to ONE edge here so the
+  // dry-run list, the drawn count, and the apply receipt all agree exactly.
+  const seenPair = new Set();
+  const edges = [];
+  for (const p of proposals) {
+    if (p.anchor) {
+      const key = [p.cardId, p.anchor.toId].sort().join('|');
+      if (!seenPair.has(key)) {
+        seenPair.add(key);
+        edges.push({ fromId: p.cardId, toId: p.anchor.toId, relationship: 'relates_to', label: 'auto', why: p.anchor.why });
+      }
+    }
+    if (withAreas && p.areaId) edges.push({ fromId: p.cardId, toId: p.areaId, relationship: 'relates_to', label: 'in area', color: 'rgba(120,120,135,0.45)', width: 1, style: 'dashed', why: 'area container' });
+  }
+  // An anchor edge between two orphans repairs BOTH endpoints — project on the
+  // orphan set, not just the source card.
+  const orphanIdSet = new Set(before.map(o => o.id));
+  const repairable = new Set();
+  for (const e of edges) {
+    if (orphanIdSet.has(e.fromId)) repairable.add(e.fromId);
+    if (orphanIdSet.has(e.toId)) repairable.add(e.toId);
+  }
+  const projected = Math.max(0, before.length - repairable.size);
+
+  if (json && !apply) {
+    console.log(JSON.stringify({
+      brain: file, dryRun: true, orphans: before.length, confident: anchored.length,
+      projectedOrphans: projected,
+      edges: edges.map(e => ({ fromId: e.fromId, toId: e.toId, label: e.label, why: e.why })),
+    }, null, 2));
+    process.exit(0);
+  }
+
+  if (!apply) {
+    console.log(`# orphan gardener — ${path.basename(file)} (DRY RUN, nothing written)`);
+    console.log('');
+    console.log(`Orphans now: ${before.length} live decision/milestone card(s) with no connections.`);
+    console.log(`Confident subset: ${anchored.length} card(s) have exactly one unambiguous lexical anchor${withAreas ? `; --areas adds ${proposals.filter(p => p.areaId).length} area-container edge(s)` : ''}.`);
+    console.log(`Projected after --apply: ${projected} orphan(s) remain (the rest need brain_connect review or a human).`);
+    if (edges.length) {
+      console.log('');
+      for (const e of edges) console.log(`  - ${flat(e.fromId)}  →  ${flat(e.toId)}  (${e.why})`);
+      console.log('');
+      console.log('Re-run with --apply to draw these. Additive only: no card is archived or rewritten;');
+      console.log('a forced restore point is taken first (undo: npx klypix-mcp brain-history).');
+    } else {
+      console.log('');
+      console.log(before.length
+        ? 'No edge clears the confidence bar — review the rest with brain_connect (dry-run receipts).'
+        : 'Nothing to do — this brain has no orphaned decision/milestone cards.');
+    }
+    process.exit(0);
+  }
+
+  if (!edges.length) {
+    console.log(before.length
+      ? `No edge clears the confidence bar — ${before.length} orphan(s) remain for brain_connect review. Nothing written.`
+      : 'Nothing to do — this brain has no orphaned decision/milestone cards. Nothing written.');
+    process.exit(0);
+  }
+
+  // APPLY — one locked snapshot + read-modify-write. The restore point is taken
+  // INSIDE the advisory lock (forced: an additive pass never trips the shrink
+  // rule, and the throttle must not skip the one snapshot that makes a whole
+  // backfill reversible): taken outside it, a concurrent capture landing between
+  // snapshot and write would be silently rolled back by a later restore.
+  let snap = null;
+  const result = await withAdvisoryWriteLock(brainCaptureLockPath(file), async (locked) => {
+    if (!locked) return { ok: false, error: 'brain is busy (another writer holds the capture lock) — retry in a moment; nothing written' };
+    snap = snapshotBrain(file, { reason: 'orphan-backfill', force: true });
+    const { buffer, added } = await addBrainConnections(fs.readFileSync(file), edges);
+    if (!added) return { ok: true, added: 0, after: before.length };
+    await atomicWrite(file, buffer, { snapshot: false });   // the forced pre-apply snapshot above is the restore point
+    let after = projected;
+    try { after = brainInsights((await parseKlypix(buffer)).struct).orphans.length; } catch { /* projected stays the honest fallback */ }
+    return { ok: true, added, after };
+  });
+  if (!result.ok) { console.error(`✗ ${result.error}`); process.exit(1); }
+
+  // A drawn count below the planned count means the brain changed between the
+  // dry-run read and the locked write (a pair already present, an endpoint
+  // gone) — slicing the planned list by count would then name the WRONG edges,
+  // so the per-edge list is only printed when it is exact.
+  const exact = result.added === edges.length;
+  // An 'unchanged' skip means the newest restore point already holds these
+  // exact bytes — the pass is just as reversible as a fresh snapshot.
+  const covered = snap && (snap.saved || snap.skipped === 'unchanged');
+  if (json) {
+    console.log(JSON.stringify({
+      brain: file, dryRun: false, added: result.added,
+      orphansBefore: before.length, orphansAfter: result.after,
+      restorePoint: covered ? (snap.id || true) : null,
+      edges: exact ? edges.map(e => ({ fromId: e.fromId, toId: e.toId, label: e.label, why: e.why })) : null,
+      ...(exact ? {} : { edgesNote: `${edges.length - result.added} planned edge(s) were skipped (already present or endpoint missing) — re-run the dry run for the current pair list` }),
+    }, null, 2));
+    process.exit(0);
+  }
+  console.log(`✓ Drew ${result.added} additive connection(s). Orphan receipt: ${before.length} → ${result.after} (${Math.max(0, before.length - result.after)} repaired).`);
+  console.log(covered
+    ? 'Restore point taken first — undo the whole pass: npx klypix-mcp brain-history'
+    : 'Restore point: not saved (best-effort) — arrows remain individually removable in KLYPIX.');
+  if (exact) for (const e of edges) console.log(`  - ${flat(e.fromId)}  →  ${flat(e.toId)}  (${e.why})`);
+  else console.log(`  (${edges.length - result.added} planned edge(s) were already present or lost an endpoint — re-run the dry run for the current pair list)`);
+  process.exit(0);
+} catch (e) {
+  console.error(`✗ orphans failed (brain unchanged): ${e?.message || e}`);
+  process.exit(1);
+}

package/bin/klypix-worker.mjs

@@ -131,6 +131,11 @@ await runVerb('brain-history', './klypix-brain-history.mjs');
 // the card's bytes to graveyard/ instead of destroying them; this lists, restores
 // and (permanently) purges them.
 await runVerb('brain-deleted', './klypix-brain-deleted.mjs');
+// `npx klypix-mcp orphans` — the orphan gardener's backfill: report how many live
+// cards sit outside the graph, link the CONFIDENT subset (one unambiguous lexical
+// anchor each — never a fan-out). Dry-run by default; --apply takes a forced
+// restore point first, so the whole pass is one brain-history restore from undone.
+await runVerb('orphans', './klypix-orphans.mjs');
 await runVerb('diff', './klypix-diff.mjs');
 await runVerb('pr-brief', './klypix-pr-brief.mjs');
 
@@ -868,8 +873,12 @@ server.registerTool('brain_sync', {
     // marker before rejecting them. A strict transport schema rejected first,
     // allowing a later result-less completion to bypass that state entirely.
     results: z.unknown().optional().describe('On phase complete, 1-8 result manifests for stable claim keys. The in-handler versioned validator rejects malformed, empty, unknown-field, or incomparable evidence and retains task scope.'),
+    releaseIntent: z.object({
+      version: z.string().max(64).describe('The version this session intends to release (e.g. "1.70.0").'),
+      ref: z.string().max(200).describe('The git ref (branch or tag) the release will be cut from.'),
+    }).optional().describe('Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer\'s sync gains a "release in preparation" footer line.'),
   },
-}, async ({ project, intent, files, phase, include_context, results }, extra) => {
+}, async ({ project, intent, files, phase, include_context, results, releaseIntent }, extra) => {
   const totalStartedAt = Date.now();
   const report = mcpPresence.sync({
     project,
@@ -877,6 +886,7 @@ server.registerTool('brain_sync', {
     files,
     phase,
     results,
+    releaseIntent,
     deliverMessages: include_context !== false,
     actionId: extra?.klypixRequestIdentity?.actionId || '',
     preflight: extra?.klypixBrainSyncPreflight,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.69.0",
+  "version": "1.70.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -44,7 +44,8 @@
     "klypix-append": "bin/klypix-append.mjs",
     "klypix-install": "bin/klypix-install.mjs",
     "klypix-uninstall": "bin/klypix-uninstall.mjs",
-    "klypix-project-map": "bin/klypix-project-map.mjs"
+    "klypix-project-map": "bin/klypix-project-map.mjs",
+    "klypix-orphans": "bin/klypix-orphans.mjs"
   },
   "main": "index.mjs",
   "exports": {
@@ -83,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.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/presence-liveness.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/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/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/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/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

@@ -718,6 +718,16 @@ function normalizeFiles(files) {
   return out.slice(-20);
 }
 
+// Comparison fold for scope coverage checks — mirrors mcp-presence.mjs
+// normalizeFileKey's slash/./-prefix/case fold (duplicated because THAT module
+// imports THIS one). Coverage must match across spellings: a hook observes
+// `src\App.tsx` while brain_sync declared `src/app.tsx`.
+const scopeKey = (file) => String(file || '').replace(/\\/g, '/').replace(/^\.\//, '').trim().toLowerCase();
+
+// Cap for the observed-scope lane (automatic scope adoption, 1.70.0). Kept as
+// its own constant so writers and tests agree on the LRU bound.
+export const OBSERVED_FILES_CAP = 20;
+
 export function listActiveSessions({ brainPath, home, now = Date.now() }) {
   if (!brainPath) return [];
   const lane = readLane(laneFileFor(brainPath, home));
@@ -736,6 +746,16 @@ export function upsertSession({
   intentSource = null,
   files,
   replaceFiles = false,
+  // Automatic scope adoption (1.70.0): paths the HOST reported this session
+  // editing (hook PostToolUse / codex tool events) — observations, never
+  // declarations. A path already covered by the row's DECLARED scope is
+  // ignored (the declaration is the higher-confidence claim); anything else
+  // joins `observedFiles` (LRU, cap OBSERVED_FILES_CAP) AND the legacy
+  // `files` union so pre-1.70 readers keep their overlap coverage. The
+  // `observedFiles` marker is what lets every 1.70+ reader state the
+  // observed/declared distinction instead of mistaking a live edit for a
+  // declared scope.
+  observedFiles,
   event = null,
   channel = null,
   transportStatus = null,
@@ -779,9 +799,51 @@ export function upsertSession({
       transport[String(channel)] = { status: String(status).slice(0, 40), at: now };
       channelOwners[String(channel)] = process.pid;
     }
-    const mergedFiles = files === undefined
+    let mergedFiles = files === undefined
       ? normalizeFiles(previous.files)
       : normalizeFiles(replaceFiles ? files : [...(previous.files || []), ...(files || [])]);
+    // ── Observed-scope maintenance (automatic scope adoption, 1.70.0) ────────
+    // `files` arrivals are DECLARATIONS (brain_sync). A path the declaration
+    // now names sheds its observed marker — the claim was upgraded, never
+    // duplicated. A declaration NOT covering an observed path leaves the
+    // marker alone (replaceFiles/completion clears declared scope only:
+    // the 1.69.0 completion guard must never erase what a session was
+    // OBSERVED editing — those edits are still real in the worktree).
+    const prevObserved = normalizeFiles(previous.observedFiles);
+    const declarationKeys = files !== undefined
+      ? new Set(normalizeFiles(files).map(scopeKey))
+      : null;
+    let nextObserved = declarationKeys
+      ? prevObserved.filter((file) => !declarationKeys.has(scopeKey(file)))
+      : prevObserved;
+    if (observedFiles !== undefined) {
+      // Declared coverage = files minus observed markers (observed paths ride
+      // in `files` too, for pre-1.70 readers — they are not declarations).
+      const observedKeys = new Set(nextObserved.map(scopeKey));
+      const declaredCovered = new Set(mergedFiles.map(scopeKey).filter((key) => !observedKeys.has(key)));
+      for (const file of normalizeFiles(observedFiles)) {
+        const key = scopeKey(file);
+        if (declaredCovered.has(key)) continue;   // declared scope covers it — nothing to adopt
+        nextObserved = nextObserved.filter((existing) => scopeKey(existing) !== key);
+        nextObserved.push(file);                  // LRU: a re-observation moves to the tail
+        if (!mergedFiles.some((existing) => scopeKey(existing) === key)) mergedFiles.push(file);
+      }
+      // Cap pressure evicts OBSERVATIONS, never declarations (review-caught,
+      // 1.70.0): normalizeFiles' plain slice(-20) let an observation flood push
+      // a session's DECLARED files out of files[] — peers silently lost
+      // blocking coverage on declared work, and a later re-edit of the evicted
+      // path re-entered it as observed, rendering an owned scope as
+      // `*`-unconfirmed. Declarations keep the tail (slice keeps newest); the
+      // observations fill whatever room remains, oldest evicted first.
+      if (mergedFiles.length > 20) {
+        const observedKeySet = new Set(nextObserved.map(scopeKey));
+        const declared = mergedFiles.filter((file) => !observedKeySet.has(scopeKey(file)));
+        const observed = mergedFiles.filter((file) => observedKeySet.has(scopeKey(file)));
+        mergedFiles = [...observed.slice(-Math.max(0, 20 - declared.length)), ...declared];
+      }
+      mergedFiles = normalizeFiles(mergedFiles);
+    }
+    nextObserved = nextObserved.slice(-OBSERVED_FILES_CAP);
     // Intent freshness is its OWN timestamp: lastSeen is refreshed by heartbeats
     // that never touch intent, so without intentAt a 100-minute-old intent renders
     // under "active just now" (2026-07-29 audit). Stamped only when the intent
@@ -816,6 +878,11 @@ export function upsertSession({
       ...(intentChanged ? { intentAt: now, intentSource: intentSource || 'declared' }
         : (previous.intentAt ? { intentAt: previous.intentAt, intentSource: previous.intentSource || null } : {})),
       files: mergedFiles,
+      // ADDITIVE observed lane: written only for rows that ever carried it, so
+      // pre-1.70 rows stay byte-stable through a touch that changes nothing.
+      ...(nextObserved.length || previous.observedFiles !== undefined
+        ? { observedFiles: nextObserved }
+        : {}),
       event: event ?? previous.event ?? null,
       ...(activityEvent
         ? { activityAt: now, activityKind: activityEvent }
@@ -903,6 +970,13 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
       const existingIdx = sessions.findIndex((session) => session.id === row.id);
       if (existingIdx >= 0 && sessions[existingIdx].via !== 'cloud') continue;   // local row wins
       const previous = existingIdx >= 0 ? sessions[existingIdx] : {};
+      // REPLACE semantics, like `files` below: the frame is a full snapshot of
+      // the sender's row, so an empty/absent observed lane must CLEAR the
+      // mirror. The `...previous` spread otherwise pinned a completed remote
+      // task's stale markers to the local mirror forever (review-caught
+      // 1.70.0) — remote rows carry no completedAt, so no local gate could
+      // ever retire them.
+      const remoteObserved = normalizeFiles(row.observedFiles).slice(-OBSERVED_FILES_CAP);
       const next = {
         ...previous,
         id: String(row.id),
@@ -914,6 +988,10 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
         // pre-guard build can relay junk intent — never mirror it verbatim.
         intent: looksMachineTurn(row.intent) ? String(previous.intent || '') : String(row.intent || '').slice(0, 160),
         files: normalizeFiles(row.files),
+        // Observed/declared distinction crosses machines too (additive — an old
+        // sender simply never populates it; see remoteObserved above for the
+        // replace-not-merge rule).
+        ...(remoteObserved.length ? { observedFiles: remoteObserved } : {}),
         machine: String(row.machine),
         host: row.host ?? previous.host ?? null,
         via: 'cloud',
@@ -924,6 +1002,9 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
         startedAt: previous.startedAt || now,
         lastSeen: now,
       };
+      // The `...previous` spread carried any stale marker into `next`; an empty
+      // snapshot clears it (see the replace-not-merge rule above).
+      if (!remoteObserved.length) delete next.observedFiles;
       if (existingIdx >= 0) sessions[existingIdx] = next;
       else sessions.push(next);
     }
@@ -1126,6 +1207,229 @@ export function endSession({ brainPath, id, home, now = Date.now(), expectedPid
   }
 }
 
+// ── Release lease (1.70.0 measured wave) ────────────────────────────────────
+// One EXCLUSIVE per-project release-preparation record in the same lane file
+// every presence reader already parses. First declarer takes it; a second
+// declarer gets a hard conflict naming the holder+version+ref. The lease is
+// bounded three ways, all reusing the lane's existing liveness machinery:
+//   • TTL (~2h) refreshed by the holder's checkpoints — a stalled release
+//     cannot squat on the project forever;
+//   • freed explicitly when the holder's task truly completes;
+//   • freed implicitly when the holder stops being a live lane session
+//     (TTL pruning + dead-host sweep, via pruneSessions) — a crashed holder
+//     never blocks the next release engineer.
+// The stored record is additive lane state: every existing mutator spreads
+// `...data` on write, so the key survives session/message maintenance, and
+// old readers simply ignore it.
+export const RELEASE_LEASE_TTL_MS = 2 * 60 * 60 * 1000;
+
+const releaseLeaseVersionKey = (value) => String(value || '').trim().replace(/^v/i, '').slice(0, 64);
+const releaseLeaseRefKey = (value) => String(value || '').trim().slice(0, 200);
+
+function normalizeReleaseLease(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const holderId = recipientKey(raw.holderId);
+  const version = releaseLeaseVersionKey(raw.version);
+  const ref = releaseLeaseRefKey(raw.ref);
+  const takenAt = Number(raw.takenAt || 0);
+  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);
+  return {
+    holderId,
+    holderClient: String(raw.holderClient || 'unknown').slice(0, 40),
+    version,
+    ref,
+    takenAt,
+    refreshedAt,
+    ttlMs,
+    expiresAt: refreshedAt + ttlMs,
+  };
+}
+
+// The holder may have rotated ids since taking the lease — match against the
+// same identity set message routing uses (id, logical id, aliases).
+const sessionOwnsLease = (session, holderId) => {
+  const key = recipientKey(holderId);
+  return Boolean(key && session && (recipientKey(session.id) === key
+    || recipientKey(session.logicalSessionId) === key
+    || normalizeAliases(session.aliases).includes(key)));
+};
+
+// Verdict for a stored lease against pre-PRUNED sessions (the caller must pass
+// pruneSessions output so TTL pruning and the dead-host sweep both apply):
+// { status: 'active' | 'expired' | 'dead-holder', lease } or null (no/invalid
+// record). Only 'active' binds anyone; the other verdicts are reclaimable.
+export function releaseLeaseVerdict(rawLease, sessions, now = Date.now()) {
+  const lease = normalizeReleaseLease(rawLease);
+  if (!lease) return null;
+  if (now >= lease.expiresAt) return { status: 'expired', lease };
+  const alive = (Array.isArray(sessions) ? sessions : [])
+    .some((session) => sessionOwnsLease(session, lease.holderId));
+  return { status: alive ? 'active' : 'dead-holder', lease };
+}
+
+// Read-only: the ACTIVE lease or null. Lock-free like every other read surface
+// (atomic lane writes guarantee a parseable snapshot).
+export function readReleaseLease({ brainPath, home, now = Date.now() } = {}) {
+  if (!brainPath) return null;
+  const lane = readLane(laneFileFor(brainPath, home));
+  const verdict = releaseLeaseVerdict(lane.releaseLease, pruneSessions(lane.sessions, now), now);
+  return verdict?.status === 'active' ? verdict.lease : null;
+}
+
+// Shared lock/read/verdict/write skeleton for the three mutators. `mutate`
+// returns { write, lease, outcome }: lease === null deletes the record,
+// undefined leaves it untouched. Sessions/messages bytes are preserved as-is —
+// a lease mutation must never race presence maintenance into data loss.
+function mutateReleaseLease({ 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 verdict = releaseLeaseVerdict(data.releaseLease, sessions, now);
+    const result = mutate({ data, sessions, verdict });
+    if (result.write) {
+      const next = { ...data };
+      if (result.lease === null) delete next.releaseLease;
+      else if (result.lease !== undefined) next.releaseLease = result.lease;
+      fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+      writeLaneFileAtomic(laneFile, JSON.stringify(next));
+    }
+    return result.outcome;
+  } finally {
+    releaseLock(lockFile);
+  }
+}
+
+const leaseHeldBy = (verdict, sessions, callerId) => {
+  if (!verdict) return false;
+  const me = sessions.find((session) => recipientKey(session.id) === callerId) || null;
+  return recipientKey(verdict.lease.holderId) === callerId
+    || sessionOwnsLease(me, verdict.lease.holderId);
+};
+
+// First-declarer-wins exclusive take. Same holder re-declaring refreshes (and
+// may retarget version/ref); an expired or dead-holder record is reclaimed with
+// the reason surfaced; a live foreign holder is a hard conflict carrying the
+// full holder record so the caller can name it.
+export function declareReleaseLease({
+  brainPath,
+  sessionId,
+  version,
+  ref,
+  client = 'unknown',
+  home,
+  now = Date.now(),
+  ttlMs = RELEASE_LEASE_TTL_MS,
+}) {
+  const holderId = recipientKey(sessionId);
+  const nextVersion = releaseLeaseVersionKey(version);
+  const nextRef = releaseLeaseRefKey(ref);
+  if (!holderId || !nextVersion || !nextRef) return { ok: false, status: 'invalid-release-intent' };
+  return mutateReleaseLease({ brainPath, home, now, mutate: ({ sessions, verdict }) => {
+    const mine = leaseHeldBy(verdict, sessions, holderId);
+    if (verdict?.status === 'active' && !mine) {
+      return { write: false, outcome: { ok: false, status: 'conflict', holder: verdict.lease } };
+    }
+    const stillMine = mine && verdict?.status === 'active';
+    const stored = {
+      schemaVersion: 1,
+      holderId,
+      holderClient: String(client || 'unknown').slice(0, 40),
+      version: nextVersion,
+      ref: nextRef,
+      takenAt: stillMine ? verdict.lease.takenAt : now,
+      refreshedAt: now,
+      ttlMs: Math.max(60_000, Number(ttlMs) || RELEASE_LEASE_TTL_MS),
+    };
+    const reclaimed = !stillMine && verdict ? verdict.status : null;
+    return {
+      write: true,
+      lease: stored,
+      outcome: {
+        ok: true,
+        status: stillMine ? 'refreshed' : 'taken',
+        ...(reclaimed && reclaimed !== 'active' ? { reclaimed } : {}),
+        lease: normalizeReleaseLease(stored),
+      },
+    };
+  } });
+}
+
+// Checkpoint refresh: only the live holder advances refreshedAt. A stale
+// record (expired / dead holder) found by ANY caller is pruned so readers stop
+// parsing it — the lane's dead-session sweep analogue for this key.
+export function refreshReleaseLease({ brainPath, sessionId, home, now = Date.now() }) {
+  const callerId = recipientKey(sessionId);
+  if (!callerId) return { ok: false, status: 'no-session' };
+  // Lock-free fast path: this runs on EVERY non-completing sync of every
+  // session, and almost always there is no lease at all. Skipping the lane
+  // lock then keeps lease bookkeeping from doubling lock traffic project-wide.
+  // Race-safe: a lease declared concurrently is simply refreshed on the
+  // caller's NEXT sync, and a just-declared lease is by definition fresh.
+  if (brainPath && readLane(laneFileFor(brainPath, home)).releaseLease === undefined) {
+    return { ok: true, status: 'no-lease' };
+  }
+  return mutateReleaseLease({ brainPath, home, now, mutate: ({ sessions, verdict }) => {
+    if (!verdict) return { write: false, outcome: { ok: true, status: 'no-lease' } };
+    const mine = leaseHeldBy(verdict, sessions, callerId);
+    if (verdict.status !== 'active') {
+      return {
+        write: true,
+        lease: null,
+        outcome: { ok: true, status: mine ? 'lease-lost' : 'stale-pruned', reason: verdict.status },
+      };
+    }
+    if (!mine) return { write: false, outcome: { ok: true, status: 'not-holder' } };
+    const stored = {
+      schemaVersion: 1,
+      holderId: verdict.lease.holderId,
+      holderClient: verdict.lease.holderClient,
+      version: verdict.lease.version,
+      ref: verdict.lease.ref,
+      takenAt: verdict.lease.takenAt,
+      refreshedAt: now,
+      ttlMs: verdict.lease.ttlMs,
+    };
+    return {
+      write: true,
+      lease: stored,
+      outcome: { ok: true, status: 'refreshed', lease: normalizeReleaseLease(stored) },
+    };
+  } });
+}
+
+// Explicit free — the holder's real task completion. A non-holder can never
+// free a LIVE peer's lease, but anyone may clear a stale record.
+export function freeReleaseLease({ brainPath, sessionId, home, now = Date.now() }) {
+  const callerId = recipientKey(sessionId);
+  if (!callerId) return { ok: false, status: 'no-session' };
+  // Same lock-free fast path as refreshReleaseLease: every real completion
+  // calls this, and almost none of them hold a lease. Race-safe for the same
+  // reason — a record this snapshot cannot see is one this caller cannot own.
+  if (brainPath && readLane(laneFileFor(brainPath, home)).releaseLease === undefined) {
+    return { ok: true, status: 'no-lease' };
+  }
+  return mutateReleaseLease({ brainPath, home, now, mutate: ({ sessions, verdict }) => {
+    if (!verdict) return { write: false, outcome: { ok: true, status: 'no-lease' } };
+    const mine = leaseHeldBy(verdict, sessions, callerId);
+    if (!mine && verdict.status === 'active') {
+      return { write: false, outcome: { ok: true, status: 'not-holder' } };
+    }
+    return {
+      write: true,
+      lease: null,
+      outcome: { ok: true, status: mine ? 'released' : 'stale-pruned', lease: verdict.lease },
+    };
+  } });
+}
+
 // 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