heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/capture-focus.mjs

@@ -9,10 +9,17 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, renameSync } from 'node:fs';
-import { join } from 'node:path';
-import { mintFileKey, mintFamilyKey, parseSpecId } from './spec-id-lib.mjs';
+import { join, isAbsolute, resolve, sep } from 'node:path';
+import { collectOccupiedKeysEitherKind, mintFileKey, mintFamilyKey, parseSpecId } from './spec-id-lib.mjs';
+import { consoleFetch as realConsoleFetch } from './console-transport.mjs';
+import { getConsoleUrl } from './mcp-config.mjs';
+import { resolveVaultWriteMode } from './read-path.mjs';
+import { cloudWriteFailure, createSpecViaConsole, updateSpecViaConsole } from './cloud-vault-writes.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
+import { ownerFrontmatterEntry, resolveSessionOwner } from './session-owner.mjs';
 import { scoreSufficiency, SUFFICIENCY_THRESHOLD } from '../../dev-factory/lib/sufficiency-score.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
 
 export const CAPTURE_CORE_SOFT_MAX = 200;
 export const CAPTURE_CORE_HARD_MAX = 500;
@@ -38,6 +45,68 @@ export const CAPTURE_SUMMARY_CHAR_HARD_MAX = 1500;
  */
 export const CAPTURE_PIN_FUSE_MS = 7 * 24 * 60 * 60 * 1000;
 
+/**
+ * Staleness limit for the OFFLINE pin file, checked against its own `pinned_at`.
+ * [[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]].
+ *
+ * On a console-backed vault the pin lives in Neon and `.heyspex/capture-focus.yaml`
+ * is only the fallback for when the console cannot be reached — so the file stops
+ * being written and quietly rots. This repo's file held a 25 June pin for over two
+ * months while three captures were created and promoted against Neon. The failure
+ * is NOT the staleness: it is that a stale read and a genuine "nothing is pinned"
+ * answer were the same answer, so an offline capture attached to a two-month-old
+ * wrong pin and reported success. `loadCaptureFocusOffline` refuses past this age
+ * and says so, instead of returning a wrong answer quietly.
+ *
+ * WHY 7 DAYS, and not shorter or longer:
+ *  - It is the number this codebase already ruled correct for "this capture pin is
+ *    abandoned" — `CAPTURE_PIN_FUSE_MS` above, which mirrors the epic-pin silent-fuse
+ *    convention. One concept, one number; a second, different threshold for the same
+ *    judgement would be the thing that drifts.
+ *  - It is ~28× the 6h `RECENT_PROMOTION_LINEAGE_MS` window that bounds "the same
+ *    working session". A capture is a fast brain-offload artifact, opened and promoted
+ *    within a session, so a genuinely live pin is hours old, never days — 7 days clears
+ *    a real pin by a wide margin and cannot false-positive on a weekend or a holiday.
+ *  - Shorter (say 24h) would start refusing legitimate free-tier pins, where this file
+ *    IS the system of record and a pin may legitimately sit over a long weekend.
+ * Tunable here; deliberately derived from the fuse so the two cannot diverge.
+ */
+export const CAPTURE_FOCUS_FILE_STALE_MS = CAPTURE_PIN_FUSE_MS;
+
+/**
+ * Age-check a loaded pin against its own `pinned_at`.
+ *
+ * A pin with a missing or unparsable `pinned_at` counts as STALE: we cannot prove
+ * it is current, and "cannot prove" must not read as "is fine" — that equivalence
+ * is the bug this whole guard exists to close.
+ *
+ * @returns {{ stale: boolean, ageMs: number|null, pinnedAt: string|null }}
+ */
+export function captureFocusStaleness(focus, { now = Date.now(), maxAgeMs = CAPTURE_FOCUS_FILE_STALE_MS } = {}) {
+  const pinnedAt = typeof focus?.pinned_at === 'string' ? focus.pinned_at.trim() : '';
+  if (!pinnedAt) return { stale: true, ageMs: null, pinnedAt: null };
+  const ts = Date.parse(pinnedAt);
+  if (!Number.isFinite(ts)) return { stale: true, ageMs: null, pinnedAt };
+  const ageMs = now - ts;
+  return { stale: ageMs > maxAgeMs, ageMs, pinnedAt };
+}
+
+/** One warning per distinct (path, pinned_at) per process — loud, not spam. */
+const warnedStalePins = new Set();
+
+function warnStalePin(path, pinnedAt, ageMs) {
+  const key = `${path} ${pinnedAt ?? '<none>'}`;
+  if (warnedStalePins.has(key)) return;
+  warnedStalePins.add(key);
+  const age = ageMs == null ? 'unknown age' : `${Math.floor(ageMs / 86400000)}d old`;
+  process.stderr.write?.(
+    `[heyspex-mcp] STALE capture pin REFUSED: ${path} pinned_at=${pinnedAt ?? '<missing>'} (${age}, ` +
+      `limit ${Math.floor(CAPTURE_FOCUS_FILE_STALE_MS / 86400000)}d). The console is the system of record for ` +
+      `this pin; the offline file has rotted. Nothing is being treated as on deck — re-pin with /hs-capture. ` +
+      `[[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]]\n`,
+  );
+}
+
 /** Frontmatter statuses that mean a capture is no longer on deck. */
 const RETIRED_CAPTURE_STATUSES = new Set(['closed', 'superseded', 'abandoned', 'done']);
 
@@ -139,8 +208,17 @@ export function migrateLegacyIdeaFocus(vaultRoot) {
   if (state.claimed_by) lines.push(`claimed_by: ${JSON.stringify(state.claimed_by)}`);
   if (state.claim_session) lines.push(`claim_session: ${JSON.stringify(state.claim_session)}`);
 
-  mkdirSync(join(vaultRoot, '.heyspex'), { recursive: true });
-  writeFileSync(next, `${lines.join('\n')}\n`, 'utf8');
+  // Best-effort: this migration runs opportunistically (on boot, and at the
+  // top of every loadCaptureFocus) and must never abort the caller's real
+  // work over a bad vaultRoot — refuse and report rather than throw.
+  try {
+    const dir = join(vaultRoot, '.heyspex');
+    assertPathUnderRoot(vaultRoot, dir, 'capture-focus write');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(next, `${lines.join('\n')}\n`, 'utf8');
+  } catch (err) {
+    return { migrated: false, reason: 'write_failed', error: String(err?.message ?? err) };
+  }
 
   try {
     const stamped = `${legacy}.migrated-${new Date().toISOString().replace(/[:.]/g, '-')}`;
@@ -157,7 +235,21 @@ export function migrateLegacyIdeaFocus(vaultRoot) {
   return { migrated: true, from: legacy, to: next };
 }
 
-export function loadCaptureFocus(vaultRoot) {
+/**
+ * Read the offline pin file as-is.
+ *
+ * Unchanged contract (`focus | null`) — on the FREE tier this file is still the
+ * real system of record, so a pin is never dropped here on age alone. What is new
+ * (HS-O4U6-2ZRO): the returned object is ANNOTATED with `stale` / `stale_age_ms`
+ * so no caller has to guess whether it is holding a current answer. Callers for
+ * whom this file is only the offline fallback should use `loadCaptureFocusOffline`,
+ * which refuses a stale pin outright.
+ *
+ * The annotation is read-only metadata — every writer here (`writeCaptureFocus`,
+ * `updateCaptureFocusClaim`, `clearCaptureFocusExpiry`) enumerates the fields it
+ * persists, so `stale` can never be written back into the YAML.
+ */
+export function loadCaptureFocus(vaultRoot, { now = Date.now() } = {}) {
   migrateLegacyIdeaFocus(vaultRoot);
   const p = captureFocusPath(vaultRoot);
   if (!existsSync(p)) return null;
@@ -165,16 +257,48 @@ export function loadCaptureFocus(vaultRoot) {
     const focus = parseSimpleFocusYaml(readFileSync(p, 'utf-8'));
     if (focus.expires) {
       const expiry = new Date(focus.expires);
-      if (expiry < new Date()) return null;
+      if (expiry < new Date(now)) return null;
     }
+    const { stale, ageMs } = captureFocusStaleness(focus, { now });
+    focus.stale = stale;
+    focus.stale_age_ms = ageMs;
     return focus;
   } catch {
     return null;
   }
 }
 
+/**
+ * Read the pin file as an OFFLINE FALLBACK — the seam used when the console (the
+ * system of record on a console-backed vault) could not be reached.
+ *
+ * This is the read that must not lie. A pin older than `CAPTURE_FOCUS_FILE_STALE_MS`
+ * is REFUSED (`focus: null`) and a loud one-time warning goes to stderr, because the
+ * alternative — handing back a two-month-old pin — makes an offline capture attach to
+ * the wrong capture and report success. The result distinguishes the three outcomes
+ * the old `focus | null` could not:
+ *
+ *   { focus: {...}, stale: false }            → a fresh pin, safe to use
+ *   { focus: null,  stale: false, reason: 'no_pin' }      → genuinely nothing pinned
+ *   { focus: null,  stale: true,  reason: 'stale', ageMs } → a pin existed and was refused
+ *
+ * @returns {{ focus: object|null, stale: boolean, ageMs: number|null, pinnedAt: string|null, reason: string }}
+ */
+export function loadCaptureFocusOffline(
+  vaultRoot,
+  { now = Date.now(), maxAgeMs = CAPTURE_FOCUS_FILE_STALE_MS } = {},
+) {
+  const focus = loadCaptureFocus(vaultRoot, { now });
+  if (!focus) return { focus: null, stale: false, ageMs: null, pinnedAt: null, reason: 'no_pin' };
+  const { stale, ageMs, pinnedAt } = captureFocusStaleness(focus, { now, maxAgeMs });
+  if (!stale) return { focus, stale: false, ageMs, pinnedAt, reason: 'fresh' };
+  warnStalePin(captureFocusPath(vaultRoot), pinnedAt, ageMs);
+  return { focus: null, stale: true, ageMs, pinnedAt, reason: 'stale' };
+}
+
 export function writeCaptureFocus(vaultRoot, specPath, reason, claim, opts = {}) {
   const dir = join(vaultRoot, '.heyspex');
+  assertPathUnderRoot(vaultRoot, dir, 'capture-focus write');
   mkdirSync(dir, { recursive: true });
   // Mirror the pinned capture's frontmatter `kind:` into the pin so the on-deck
   // pin reflects the real kind (idea | bug-fix | clip | reference | question |
@@ -204,7 +328,6 @@ export function updateCaptureFocusClaim(vaultRoot, claim) {
   const focus = loadCaptureFocus(vaultRoot);
   if (!focus?.spec_path) return false;
   const dir = join(vaultRoot, '.heyspex');
-  mkdirSync(dir, { recursive: true });
   const lines = [
     '# HeySpex capture-on-deck — MCP /hs-capture ([[idea-capture-guardrails]])',
     `kind: ${focus.kind || 'idea'}`,
@@ -218,7 +341,19 @@ export function updateCaptureFocusClaim(vaultRoot, claim) {
   if (focus.expires) lines.push(`expires: ${focus.expires}`);
   if (claim?.claimed_by) lines.push(`claimed_by: ${JSON.stringify(claim.claimed_by)}`);
   if (claim?.claim_session) lines.push(`claim_session: ${JSON.stringify(claim.claim_session)}`);
-  writeFileSync(captureFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  // Best-effort: callers fire this as a claim-metadata refresh AFTER their
+  // primary work already succeeded, and none of them check the return value —
+  // a bad vaultRoot here must not blow up an otherwise-successful tool call.
+  try {
+    assertPathUnderRoot(vaultRoot, dir, 'capture-focus write');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(captureFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  } catch (err) {
+    process.stderr.write?.(
+      `[heyspex-mcp] updateCaptureFocusClaim refused/failed: ${err?.message ?? err}\n`,
+    );
+    return false;
+  }
   return true;
 }
 
@@ -324,8 +459,18 @@ export const EXPANDED_IDEA_DETAILS_RE = DETAILS_BLOCK_RE;
  */
 export function extractAgentExpansionFromBody(body) {
   const normalized = body.replace(/\r\n/g, '\n');
+  // Stop only at a KNOWN sibling section heading (or a top-level `#` / end of
+  // body) — not at any `##`. Agent grounding is normally structured prose
+  // that opens with its own level-2 heading (e.g. "## Grounding — …"), and
+  // the old any-`##` lookahead matched that as the section boundary,
+  // silently returning "" for a fully expanded capture. That, in turn,
+  // defeated the HS-55YM already-expanded promote bypass (which reads this
+  // extractor to decide whether to skip the sufficiency gate) for the normal
+  // shape of its own input. Mirrors capture-vault.ts's
+  // extractAgentExpansionFromBody byte-for-byte — no drift between the two
+  // implementations. [[HS-NHPA-3EFV-DIAG-already-expanded-promote-bypass-is]]
   const section = normalized.match(
-    /##[ \t]*Expanded[ \t]+Concept[ \t]*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i,
+    /##[ \t]*Expanded[ \t]+Concept[ \t]*\n([\s\S]*?)(?=\n##[ \t]*(?:Source Material|Notes|Example|User Stories|Done When)[ \t]*\n|\n#[ \t]|$)/i,
   );
   if (section) return stripLeadingHtmlComments(section[1]);
   const m = normalized.match(DETAILS_BLOCK_RE);
@@ -467,6 +612,127 @@ export function extractSourceMaterialFromBody(body) {
   return fence ? fence[1] : stripLeadingHtmlComments(section[1]);
 }
 
+/* ------------------------------------------------------------------------ *
+ * Source Material — list form (many sources per capture). Mirrors the
+ * console `spex-console/src/lib/capture-vault.ts` implementation byte-for-
+ * byte (hand-kept in sync, no shared import — see the "3 mirrored builders"
+ * lesson). [[HS-9GGC-U1DO-EPIC-source-list-schema-and-one-capture]]
+ * ------------------------------------------------------------------------ */
+
+export const SOURCE_MATERIAL_GRAINS = ['tab', 'window', 'column', 'folder'];
+
+const SOURCE_LIST_ITEM_RE = /^-\s*url:\s*(.+)$/;
+const SOURCE_LIST_FIELD_RE = /^\s+([a-zA-Z_]+):\s*(.*)$/;
+
+function parseBoardRefInline(value) {
+  const wrapped = value.match(/^\{\s*([\s\S]*?)\s*\}$/);
+  if (!wrapped) return undefined;
+  const fields = {};
+  for (const part of wrapped[1].split(',')) {
+    const kv = part.trim().match(/^([a-zA-Z_]+):\s*(.+)$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  if (!fields.board || !fields.column) return undefined;
+  return { board: fields.board, column: fields.column, ...(fields.folder ? { folder: fields.folder } : {}) };
+}
+
+function parseSourceMaterialListText(text) {
+  const entries = [];
+  let current = null;
+  const flush = () => {
+    if (current?.url && current.grain && current.added_at) entries.push(current);
+    current = null;
+  };
+  for (const line of text.split('\n')) {
+    const itemMatch = line.match(SOURCE_LIST_ITEM_RE);
+    if (itemMatch) {
+      flush();
+      current = { url: itemMatch[1].trim() };
+      continue;
+    }
+    if (!current) continue;
+    const fieldMatch = line.match(SOURCE_LIST_FIELD_RE);
+    if (!fieldMatch) continue;
+    const [, key, rawValue] = fieldMatch;
+    const value = rawValue.trim();
+    switch (key) {
+      case 'title':
+        current.title = value;
+        break;
+      case 'favicon':
+        current.favicon = value;
+        break;
+      case 'added_at':
+        current.added_at = value;
+        break;
+      case 'grain':
+        if (SOURCE_MATERIAL_GRAINS.includes(value)) current.grain = value;
+        break;
+      case 'board_ref': {
+        const ref = parseBoardRefInline(value);
+        if (ref) current.board_ref = ref;
+        break;
+      }
+      case 'tab_id':
+      case 'window_id': {
+        const n = Number(value);
+        if (Number.isFinite(n)) current[key] = n;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  flush();
+  return entries;
+}
+
+function parseSourceMaterialSection(sectionText) {
+  const fence = sectionText.match(SOURCE_FENCE_RE);
+  if (fence) return { sources: [], blob: fence[1] };
+  const trimmed = sectionText.trim();
+  if (!trimmed) return { sources: [], blob: '' };
+  if (!/^-\s*url:\s*/m.test(trimmed)) {
+    return { sources: [], blob: stripLeadingHtmlComments(sectionText) };
+  }
+  return { sources: parseSourceMaterialListText(trimmed), blob: '' };
+}
+
+/**
+ * Structured read of `## Source Material` — parses BOTH the legacy single-blob
+ * fence and the list form. Use this (not `extractSourceMaterialFromBody`) for
+ * any read-then-rebuild path so a list-form section survives an unrelated
+ * body rewrite (e.g. `heyspex_update_capture` touching Notes/Core Idea).
+ */
+export function extractSourceMaterialStructured(body) {
+  const withoutDetails = stripAgentExpansionFromBody(body);
+  const section = withoutDetails.match(
+    /##[ \t]*Source[ \t]+Material[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i,
+  );
+  if (!section) return { sources: [], blob: '' };
+  return parseSourceMaterialSection(section[1]);
+}
+
+export function formatSourceMaterialEntry(entry) {
+  const lines = [`- url: ${entry.url}`];
+  if (entry.title) lines.push(`  title: ${entry.title}`);
+  if (entry.favicon) lines.push(`  favicon: ${entry.favicon}`);
+  lines.push(`  added_at: ${entry.added_at}`);
+  lines.push(`  grain: ${entry.grain}`);
+  if (entry.board_ref) {
+    const parts = [`board: ${entry.board_ref.board}`, `column: ${entry.board_ref.column}`];
+    if (entry.board_ref.folder) parts.push(`folder: ${entry.board_ref.folder}`);
+    lines.push(`  board_ref: { ${parts.join(', ')} }`);
+  }
+  if (typeof entry.tab_id === 'number') lines.push(`  tab_id: ${entry.tab_id}`);
+  if (typeof entry.window_id === 'number') lines.push(`  window_id: ${entry.window_id}`);
+  return lines.join('\n');
+}
+
+export function buildSourceMaterialList(entries) {
+  return entries.map(formatSourceMaterialEntry).join('\n');
+}
+
 /**
  * Build the capture body in summaries-first order:
  * **Core Idea → Summary → Notes → Example → User Stories → JTBD → Done When →
@@ -488,6 +754,7 @@ export function buildCaptureBody(
   userStories = '',
   doneWhen = '',
   jtbd = '',
+  sources = [],
 ) {
   const looksLikeDetails =
     typeof summaryOrAgentExpansion === 'string' && /<details>/i.test(summaryOrAgentExpansion);
@@ -543,8 +810,11 @@ export function buildCaptureBody(
   const expandedBlock = buildAgentExpansionBlock(expandedContent);
   if (expandedBlock) out += expandedBlock.startsWith('\n') ? expandedBlock : `\n${expandedBlock}`;
 
-  // Source Material — conditional, LAST.
-  if (sourceTrim) {
+  // Source Material — conditional, LAST. List form wins when `sources` is
+  // populated (many-sources-per-capture); otherwise the legacy fenced blob.
+  if (Array.isArray(sources) && sources.length > 0) {
+    out += `\n## Source Material\n\n${buildSourceMaterialList(sources)}\n`;
+  } else if (sourceTrim) {
     out += `\n## Source Material\n\n\`\`\`source\n${sourceTrim}\n\`\`\`\n`;
   }
   return out;
@@ -1083,6 +1353,50 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
     return { error: 'CAPTURE_FILE_MISSING', message: specPath };
   }
 
+  const content = readFileSync(fullPath, 'utf-8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  const computed = computeCaptureUpdate(frontmatter, body, args);
+  if (computed.error) return computed;
+  const { fm, newBody, core, notes, summaryWarning, hasContent } = computed;
+
+  writeFileSync(fullPath, stringifyCaptureSpec(fm, newBody), 'utf8');
+
+  // Real content just landed → drop the empty-scaffold fuse so this capture is
+  // no longer treated as an abandonable zombie. Runs regardless of whether a
+  // claim refresh follows (a content write without a claim must still defuse).
+  if (hasContent) {
+    clearCaptureFocusExpiry(vaultRoot);
+  }
+
+  if (deps.claim) {
+    updateCaptureFocusClaim(vaultRoot, deps.claim);
+  }
+
+  return buildUpdateCaptureResult({
+    fm,
+    newBody,
+    specPath,
+    core,
+    notes,
+    args,
+    autoCreated,
+    continuationOf,
+    summaryWarning,
+  });
+}
+
+/**
+ * The PURE middle of `heyspex_update_capture`: given the capture's current
+ * `{ frontmatter, body }` and the tool args, produce the post-edit
+ * `{ fm, newBody }` pair plus everything the result needs. No I/O at all —
+ * which is what lets the local path `writeFileSync` it and the cloud path hand
+ * the very same pair to `PUT /api/specs/:id` ({@link updateSpecViaConsole})
+ * without two copies of this logic drifting apart.
+ *
+ * Returns a `{ error, message }` result (the shape the tool already returns)
+ * for every rejection.
+ */
+function computeCaptureUpdate(frontmatter, body, args = {}) {
   // `summary` is the canonical input; `concept` is the deprecated alias (HS-EPIC-OED2).
   const summaryArg = args.summary ?? args.concept;
 
@@ -1099,8 +1413,6 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
     if (blocked) return blocked;
   }
 
-  const content = readFileSync(fullPath, 'utf-8');
-  const { frontmatter, body } = parseFrontmatter(content);
   let core = extractCaptureCoreFromBody(body);
   let notes = extractCaptureNotesFromBody(body);
   let summary = extractCaptureSummaryFromBody(body);
@@ -1190,8 +1502,22 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
 
   // Preserve any existing `## Source Material` across the rebuild (MCP args don't
   // carry source material, but it must survive an update — it used to be dropped).
-  const sourceMaterial = extractSourceMaterialFromBody(body);
-  const newBody = buildCaptureBody(core, notes, summary, agentExpansion, sourceMaterial, example, userStories, doneWhen, jtbd);
+  // Structured read so a LIST-form section (many sources per capture,
+  // [[HS-9GGC-U1DO-EPIC-source-list-schema-and-one-capture]]) survives too —
+  // the plain-string reader would flatten it into a re-fenced blob.
+  const existingSourceMaterial = extractSourceMaterialStructured(body);
+  const newBody = buildCaptureBody(
+    core,
+    notes,
+    summary,
+    agentExpansion,
+    existingSourceMaterial.blob,
+    example,
+    userStories,
+    doneWhen,
+    jtbd,
+    existingSourceMaterial.sources,
+  );
   const updated = new Date().toISOString().slice(0, 10);
   const fm = { ...frontmatter, updated };
   // SV2K: assert type: capture going forward; legacy type: idea is tolerated until E2.
@@ -1211,11 +1537,9 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
     if (firstLine) fm.name = firstLine.replace(/^[-*>\s"]+|["]+$/g, '').slice(0, 80);
   }
 
-  writeFileSync(fullPath, stringifyCaptureSpec(fm, newBody), 'utf8');
-
-  // Real content just landed → drop the empty-scaffold fuse so this capture is
-  // no longer treated as an abandonable zombie. Runs regardless of whether a
-  // claim refresh follows (a content write without a claim must still defuse).
+  // Real content just landed → the caller drops the empty-scaffold fuse so this
+  // capture is no longer treated as an abandonable zombie. Computed here (pure)
+  // and acted on by whichever persistence path ran.
   const hasContent =
     core.trim() !== '' ||
     notes.trim() !== '' ||
@@ -1223,14 +1547,27 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
     example.trim() !== '' ||
     doneWhen.trim() !== '' ||
     String(agentExpansion ?? '').trim() !== '';
-  if (hasContent) {
-    clearCaptureFocusExpiry(vaultRoot);
-  }
 
-  if (deps.claim) {
-    updateCaptureFocusClaim(vaultRoot, deps.claim);
-  }
+  return { fm, newBody, core, notes, summaryWarning, hasContent };
+}
 
+/**
+ * Shape the `heyspex_update_capture` success payload. Shared verbatim by the
+ * local (disk) and cloud (console) persistence paths so the two can never
+ * report different shapes for the same write.
+ */
+function buildUpdateCaptureResult({
+  fm,
+  newBody,
+  specPath,
+  core,
+  notes,
+  args = {},
+  autoCreated,
+  continuationOf,
+  summaryWarning,
+  extra = null,
+}) {
   const result = {
     success: true,
     spec_id: fm.id,
@@ -1264,6 +1601,9 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
   // the agent elicits missing elements in this pass instead of bouncing at
   // promote time. Read-only — never blocks the update or triggers a promote.
   result.sufficiency = computeCaptureSufficiency(fm, newBody);
+  // Cloud-only additions (`write_mode` / `on_disk` / `console_url`). Null on the
+  // local path, so that payload stays byte-identical to what it always was.
+  if (extra) Object.assign(result, extra);
   return result;
 }
 
@@ -1280,7 +1620,13 @@ function unwrapWikilink(s) {
   return m ? m[1] : trimmed;
 }
 
-export function createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupiedCaptureIds, lineage = null) {
+export function createFreshCaptureSpec(
+  vaultRoot,
+  allocateRandomVaultId,
+  occupiedCaptureIds,
+  lineage = null,
+  deps = {},
+) {
   // Era-3 file-key-first ([[naming-v3-7-rulings-hs-namespace-kept]]): the
   // FAMILY token still comes from the legacy allocator's `HS-<family>-CAP`
   // draw (parentless capture — no family to inherit); `id:` keys onto the
@@ -1289,12 +1635,17 @@ export function createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupie
   const familyKey = parseSpecId(allocatedFamilyId)?.familyKey ?? mintFamilyKey(vaultRoot);
   // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
   // and (V3) the anchor for `id:` itself.
-  const fileKey = mintFileKey(vaultRoot);
+  // Disk occupancy ([[HS-FJWL]]): this is the LOCAL branch of
+  // `createFreshCaptureSpecViaMode` — cloud reliance routes to
+  // `createFreshCaptureSpecViaConsole`, where the console mints the id — so
+  // the vault walk is complete here by construction.
+  const fileKey = mintFileKey(collectOccupiedKeysEitherKind(vaultRoot));
   const newId = `HS-${fileKey}`;
   const today = new Date().toISOString().slice(0, 10);
   const slug = `idea-${today}`;
   const filename = `${newId}-${familyKey}-CAP-${slug}.md`;
   const dir = join(vaultRoot, 'specs', 'captures');
+  assertPathUnderRoot(vaultRoot, dir, 'capture-focus write');
   mkdirSync(dir, { recursive: true });
   const iso = new Date().toISOString();
   const frontmatter = {
@@ -1305,7 +1656,9 @@ export function createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupie
     type: 'capture',
     kind: 'idea',
     status: 'open',
-    owner: 'pwher',
+    // `owner:` is the paired session account, OMITTED when none resolves —
+    // never a literal handle ([[HS-WE87-WW9R-TASK-thread-the-gated-caller-through-every]]).
+    ...ownerFrontmatterEntry({ resolve: deps.resolveSessionOwner ?? resolveSessionOwner }),
     created: iso,
     updated: iso,
     tags: ['idea', 'capture'],
@@ -1364,3 +1717,656 @@ export function executePinCapture(vaultRoot, parseFrontmatter, loadSpec, args =
     message: `Capture ${specId} is now on deck for /hs-capture`,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Cloud vault-write mode
+// ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]])
+//
+// Everything above this line is the LOCAL write path and is untouched: the
+// markdown goes to `specs/captures/` and the pin goes to the YAML pin file,
+// exactly as before.
+//
+// When `resolveVaultWriteMode()` says `cloud`, neither may touch this machine:
+//
+//   1. The capture MARKDOWN (the document itself) is created with
+//      `POST /api/specs` (`type: 'capture'`, server-minted id — nothing here
+//      mints a file key, a family key or an allocator id in cloud mode) and
+//      edited with `PUT /api/specs/:id`.
+//   2. The PIN is the Neon control plane, not the YAML pin file. Layer-1
+//      (`spec_id` / `pinned_at` / `expires` — including the [[HS-CAP-SID6]]
+//      self-clear fuse) is `PUT /api/control/capture-focus-pin`; layer-2
+//      (`spec_path` / `kind` / `reason` / `claimed_by` / `claim_session`) is
+//      `PUT /api/control/capture-focus-selection`. That is the split
+//      [[HS-M0MK-CPFP-TASK-migrate-capture-focus-yaml-to-neon-capture-focus-pin]]
+//      and [[HS-IIP4-CFL2-TASK-migrate-capture-focus-layer-2-to-neon-capture-focus-selection]]
+//      already shipped behind those routes; IIP4 §Scope item 6 is exactly this
+//      vendor-side repoint, which CPFP deferred as a sync cascade.
+//
+// That sync cascade is why the functions below are SIBLINGS rather than an
+// async-ification of the originals: `writeCaptureFocus` / `executeUpdateCapture`
+// / `ensureActiveCapturePin` are called from sync paths in cli.mjs and
+// capture-tools.mjs, and every one of those callers must keep working
+// unchanged. Each `*ViaMode` entry point resolves the write mode ONCE and
+// either delegates to its sync twin (`local`) or runs the console path
+// (`cloud`); the mode can also be passed in, so a caller that already resolved
+// it does not resolve it twice.
+//
+// Every console call takes an injected `consoleFetch`, so tests drive each
+// branch with a recorder and never open a socket.
+// ---------------------------------------------------------------------------
+
+export const CAPTURE_FOCUS_PIN_ROUTE = '/api/control/capture-focus-pin';
+export const CAPTURE_FOCUS_SELECTION_ROUTE = '/api/control/capture-focus-selection';
+
+/**
+ * The capture spec id a `spec_path` names.
+ *
+ * A local twin of capture-tools.mjs's `captureSpecIdFromPath` on purpose: that
+ * module imports THIS one, so importing it back would be a cycle — and its
+ * regex only reads era-1/2 `HS-CAP-XXXX` names, while a capture filed today is
+ * era-3 (`HS-<fileKey>-<familyKey>-CAP-<slug>`, keyed on the file key alone).
+ * Both eras are read here through the shared `parseSpecId`.
+ */
+export function captureSpecIdFromSpecPath(specPath) {
+  const base = String(specPath || '')
+    .replace(/^.*[/\\]/, '')
+    .replace(/\.md$/i, '');
+  if (!base) return null;
+  const parsed = parseSpecId(base);
+  if (parsed?.fileKey) return `HS-${parsed.fileKey}`;
+  if (parsed?.typeLabel && parsed?.familyKey) return `HS-${parsed.typeLabel}-${parsed.familyKey}`;
+  return base;
+}
+
+/**
+ * Default cloud-tier spec read. Dynamically imported so this module keeps no
+ * static edge to vault-io.mjs, and injectable because `loadSpecByIdViaTier`'s
+ * neon branch closes over the real `consoleFetch` (a test must be able to
+ * replace the whole read, not just the transport).
+ */
+async function defaultLoadSpecViaTier(vaultRoot, ref, consoleUrl) {
+  const { loadSpecByIdViaTier } = await import('./vault-io.mjs');
+  return loadSpecByIdViaTier(vaultRoot, ref, { tier: 'neon', consoleUrl });
+}
+
+/** Normalize the cloud dependency bundle every `*ViaConsole` function takes. */
+export function captureCloudDeps(deps = {}) {
+  return {
+    consoleFetch: deps.consoleFetch ?? realConsoleFetch,
+    consoleUrl: deps.consoleUrl ?? getConsoleUrl(),
+    loadSpecViaTier: deps.loadSpecViaTier ?? defaultLoadSpecViaTier,
+  };
+}
+
+/** Resolve the write mode ONCE for a handler entry; `?? 'local'` keeps callers unchanged. */
+async function resolveWriteModeOnce(explicit, deps = {}) {
+  return explicit ?? (await (deps.resolveWriteMode ?? resolveVaultWriteMode)()) ?? 'local';
+}
+
+/**
+ * Read the live capture pin from the Neon control plane: layer-1 ⊕ layer-2,
+ * composed the same way the console's `readCaptureFocusState` does — layer-2 is
+ * attached only when its `spec_path` names the pinned spec, so a stale
+ * selection never paints onto a freshly-pinned one.
+ *
+ * Deliberately NOT `readCaptureFocusVendor` (capture-tools.mjs): that reader
+ * falls back to the offline YAML pin file, and its `loadCaptureFocus` call runs
+ * `migrateLegacyIdeaFocus`, which WRITES that file. Both are exactly what cloud
+ * mode forbids, so this path is strict — it throws
+ * `CONSOLE_UNREACHABLE_CLOUD_MODE` rather than reading (or writing) the disk.
+ *
+ * @returns the same `focus` shape `loadCaptureFocus` returns, or `null` when
+ *   Neon says nothing is pinned (an authoritative answer, not a failure).
+ */
+export async function readCaptureFocusViaConsole(deps = {}) {
+  const { consoleFetch, consoleUrl } = captureCloudDeps(deps);
+  const [pinRes, selRes] = await Promise.all([
+    consoleFetch(CAPTURE_FOCUS_PIN_ROUTE),
+    consoleFetch(CAPTURE_FOCUS_SELECTION_ROUTE),
+  ]);
+  if (!pinRes?.ok) {
+    throw cloudWriteFailure(
+      `GET ${CAPTURE_FOCUS_PIN_ROUTE}`,
+      consoleUrl,
+      `answered ${pinRes?.status ?? 'no response'}`,
+      { status: pinRes?.status ?? null, console_response: pinRes?.body ?? null },
+    );
+  }
+  const pin = pinRes.body?.pin ?? null;
+  if (!pin) return null;
+  const sel = selRes?.ok ? (selRes.body?.selection ?? null) : null;
+  const basenameOf = (p) => String(p || '').replace(/^.*[/\\]/, '');
+  const selMatches = sel?.specPath ? basenameOf(sel.specPath).startsWith(pin.specId) : false;
+  const focus = {
+    spec_id: pin.specId,
+    spec_path: selMatches ? sel.specPath : `specs/captures/${pin.specId}.md`,
+    pinned_at: pin.pinnedAt ?? null,
+  };
+  if (pin.expiresAt) focus.expires = pin.expiresAt;
+  if (selMatches && sel) {
+    if (sel.reason) focus.reason = sel.reason;
+    if (sel.claimedBy) focus.claimed_by = sel.claimedBy;
+    if (sel.claimSession) focus.claim_session = sel.claimSession;
+    if (sel.kind) focus.kind = sel.kind;
+  }
+  if (!focus.kind) focus.kind = 'idea';
+  return focus;
+}
+
+/**
+ * Cloud twin of {@link writeCaptureFocus}: pin layer-1 + layer-2 in one call.
+ * The YAML pin file is never touched.
+ *
+ * `expires` (the empty-scaffold silent fuse) is carried as the pin route's
+ * `ttl_ms`, which is how `capture_focus_pin` stores it — `getCaptureFocusPin`'s
+ * SQL already excludes rows past `expires_at`, so the [[HS-CAP-SID6]] self-retire
+ * behaves identically on this tier (CPFP AC#2).
+ */
+export async function writeCaptureFocusViaConsole(
+  { specId = null, specPath, reason = null, claim = null, kind = 'idea', expires = null } = {},
+  deps = {},
+) {
+  const { consoleFetch, consoleUrl } = captureCloudDeps(deps);
+  const id = specId || captureSpecIdFromSpecPath(specPath);
+  if (!id) {
+    throw cloudWriteFailure(
+      `PUT ${CAPTURE_FOCUS_PIN_ROUTE}`,
+      consoleUrl,
+      `no capture spec id could be resolved from spec_path ${JSON.stringify(specPath ?? null)} — the pin route requires one`,
+    );
+  }
+  const ttlMs = expires ? Date.parse(expires) - Date.now() : null;
+  const [pinRes, selRes] = await Promise.all([
+    consoleFetch(CAPTURE_FOCUS_PIN_ROUTE, {
+      method: 'PUT',
+      body: {
+        spec_id: id,
+        pinned_by: claim?.claimed_by || 'agent',
+        ...(Number.isFinite(ttlMs) ? { ttl_ms: ttlMs } : {}),
+      },
+    }),
+    consoleFetch(CAPTURE_FOCUS_SELECTION_ROUTE, {
+      method: 'PUT',
+      body: {
+        spec_path: specPath ?? null,
+        kind: typeof kind === 'string' && kind.trim() ? kind.trim() : 'idea',
+        reason: reason ?? null,
+        claimed_by: claim?.claimed_by ?? null,
+        claim_session: claim?.claim_session ?? null,
+      },
+    }),
+  ]);
+  if (!pinRes?.ok || !selRes?.ok) {
+    throw cloudWriteFailure(
+      `PUT ${CAPTURE_FOCUS_PIN_ROUTE} + ${CAPTURE_FOCUS_SELECTION_ROUTE}`,
+      consoleUrl,
+      `pin answered ${pinRes?.status ?? 'no response'}, selection answered ${selRes?.status ?? 'no response'} — the capture is NOT on deck`,
+      {
+        pin_status: pinRes?.status ?? null,
+        selection_status: selRes?.status ?? null,
+        spec_id: id,
+        spec_path: specPath ?? null,
+      },
+    );
+  }
+  return {
+    pinned: true,
+    tier: 'neon',
+    on_disk: false,
+    spec_id: id,
+    spec_path: specPath ?? null,
+    pin: pinRes.body?.pin ?? null,
+    selection: selRes.body?.selection ?? null,
+  };
+}
+
+/**
+ * Cloud twin of {@link updateCaptureFocusClaim} — refresh the claim metadata on
+ * the LIVE pin. Layer-2 only: the claim lives in `capture_focus_selection`, so
+ * the layer-1 row (and with it `pinned_at` and the fuse) is left alone.
+ *
+ * `setCaptureFocusSelection` replaces the whole row, so the fields this refresh
+ * is not changing (`spec_path` / `kind` / `reason`) are re-sent from the row as
+ * read. Best-effort like its sync twin: callers fire it after their real work
+ * succeeded and none check the return value, so a failure reports `false` and a
+ * stderr line rather than throwing.
+ */
+export async function updateCaptureFocusClaimViaConsole(claim, deps = {}) {
+  const { consoleFetch, consoleUrl } = captureCloudDeps(deps);
+  try {
+    const focus = await readCaptureFocusViaConsole({ consoleFetch, consoleUrl });
+    if (!focus?.spec_path) return false;
+    const res = await consoleFetch(CAPTURE_FOCUS_SELECTION_ROUTE, {
+      method: 'PUT',
+      body: {
+        spec_path: focus.spec_path,
+        kind: focus.kind || 'idea',
+        reason: focus.reason ?? null,
+        claimed_by: claim?.claimed_by ?? null,
+        claim_session: claim?.claim_session ?? null,
+      },
+    });
+    if (!res?.ok) {
+      process.stderr.write?.(
+        `[heyspex-mcp] updateCaptureFocusClaimViaConsole refused: ${CAPTURE_FOCUS_SELECTION_ROUTE} answered ${res?.status ?? 'no response'}\n`,
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    process.stderr.write?.(
+      `[heyspex-mcp] updateCaptureFocusClaimViaConsole failed: ${err?.message ?? err}\n`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Cloud twin of {@link clearCaptureFocusExpiry}: drop the empty-scaffold fuse
+ * once a capture has real content, by re-pinning layer-1 with `ttl_ms: null`.
+ * Same no-op contract as the sync twin — `false` when nothing is pinned or the
+ * pin carries no fuse.
+ */
+export async function clearCaptureFocusExpiryViaConsole(deps = {}) {
+  const { consoleFetch, consoleUrl } = captureCloudDeps(deps);
+  const pinRes = await consoleFetch(CAPTURE_FOCUS_PIN_ROUTE);
+  if (!pinRes?.ok) {
+    throw cloudWriteFailure(
+      `GET ${CAPTURE_FOCUS_PIN_ROUTE}`,
+      consoleUrl,
+      `answered ${pinRes?.status ?? 'no response'}`,
+      { status: pinRes?.status ?? null },
+    );
+  }
+  const pin = pinRes.body?.pin ?? null;
+  if (!pin?.specId || !pin.expiresAt) return false;
+  const res = await consoleFetch(CAPTURE_FOCUS_PIN_ROUTE, {
+    method: 'PUT',
+    body: { spec_id: pin.specId, pinned_by: pin.pinnedBy || 'agent', ttl_ms: null },
+  });
+  if (!res?.ok) {
+    throw cloudWriteFailure(
+      `PUT ${CAPTURE_FOCUS_PIN_ROUTE}`,
+      consoleUrl,
+      `answered ${res?.status ?? 'no response'} clearing the capture-pin fuse`,
+      { status: res?.status ?? null, spec_id: pin.specId },
+    );
+  }
+  return true;
+}
+
+/**
+ * Cloud twin of {@link createFreshCaptureSpec}.
+ *
+ * NOTHING is minted client-side here — no `allocateRandomVaultId`, no
+ * `mintFamilyKey`, no `mintFileKey`. The console mints the id, the family and
+ * the filename (`createSpec`: `capture` → `specs/captures/`, `CAP`), which is
+ * the whole point: a key minted on a machine whose vault the console has never
+ * indexed collides with a cloud-side one ([[HS-2FQY]]).
+ */
+export async function createFreshCaptureSpecViaConsole(vaultRoot, lineage = null, deps = {}) {
+  const { consoleFetch, consoleUrl } = captureCloudDeps(deps);
+  const today = new Date().toISOString().slice(0, 10);
+  // No `status:` — the console seeds `open` and refuses an out-of-band status
+  // on create ([[HS-ISZP]]); the disk twin above keeps it because it writes
+  // the frontmatter itself.
+  const frontmatter = {
+    kind: 'idea',
+    // Same owner rule as the disk twin: the paired account or no key at all.
+    ...ownerFrontmatterEntry({ resolve: deps.resolveSessionOwner ?? resolveSessionOwner }),
+    tags: ['idea', 'capture'],
+    promoted_to: null,
+    capture_status: 'raw',
+    // HS-KFB2 lineage carry-over — identical to the local path.
+    ...(lineage?.promotedTo ? { continues: `[[${unwrapWikilink(lineage.promotedTo)}]]` } : {}),
+  };
+  const body = lineage?.promotedTo
+    ? CAPTURE_BODY_TEMPLATE.replace(
+        /^# Core Idea\n/,
+        `# Core Idea\n\n> Continuation of a recently-promoted idea — see [[${unwrapWikilink(lineage.promotedTo)}]]` +
+          (lineage.retiredCaptureBasename
+            ? ` (originally [[${unwrapWikilink(lineage.retiredCaptureBasename)}]]).`
+            : '.') +
+          '\n',
+      )
+    : CAPTURE_BODY_TEMPLATE;
+  const created = await createSpecViaConsole({
+    consoleFetch,
+    consoleUrl,
+    type: 'capture',
+    name: `Capture ${today}`,
+    frontmatter,
+    body,
+  });
+  return {
+    spec_id: created.specId,
+    spec_path: created.relPath ?? `specs/captures/${created.basename}.md`,
+    on_disk: false,
+    ...(lineage?.promotedTo ? { continuation_of: unwrapWikilink(lineage.promotedTo) } : {}),
+  };
+}
+
+/**
+ * Mode-aware {@link createFreshCaptureSpec}. `local` delegates verbatim.
+ * In `cloud` the allocator arguments are IGNORED (the server mints) — they stay
+ * in the signature only so this is a drop-in for the sync call sites.
+ */
+export async function createFreshCaptureSpecViaMode(
+  vaultRoot,
+  allocateRandomVaultId,
+  occupiedCaptureIds,
+  lineage = null,
+  deps = {},
+) {
+  const writeMode = await resolveWriteModeOnce(deps.writeMode, deps);
+  if (writeMode !== 'cloud') {
+    return createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupiedCaptureIds, lineage, deps);
+  }
+  return createFreshCaptureSpecViaConsole(vaultRoot, lineage, deps);
+}
+
+/** Mode-aware {@link writeCaptureFocus}. */
+export async function writeCaptureFocusViaMode(vaultRoot, specPath, reason, claim, opts = {}, deps = {}) {
+  const writeMode = await resolveWriteModeOnce(deps.writeMode, deps);
+  if (writeMode !== 'cloud') {
+    writeCaptureFocus(vaultRoot, specPath, reason, claim, opts);
+    return { pinned: true, tier: 'file', on_disk: true, spec_path: specPath };
+  }
+  return writeCaptureFocusViaConsole(
+    {
+      specId: opts.specId ?? null,
+      specPath,
+      reason,
+      claim,
+      kind: opts.kind,
+      expires: opts.expires ?? null,
+    },
+    deps,
+  );
+}
+
+/** Mode-aware {@link updateCaptureFocusClaim}. */
+export async function updateCaptureFocusClaimViaMode(vaultRoot, claim, deps = {}) {
+  const writeMode = await resolveWriteModeOnce(deps.writeMode, deps);
+  if (writeMode !== 'cloud') return updateCaptureFocusClaim(vaultRoot, claim);
+  return updateCaptureFocusClaimViaConsole(claim, deps);
+}
+
+/** Mode-aware {@link clearCaptureFocusExpiry}. */
+export async function clearCaptureFocusExpiryViaMode(vaultRoot, deps = {}) {
+  const writeMode = await resolveWriteModeOnce(deps.writeMode, deps);
+  if (writeMode !== 'cloud') return clearCaptureFocusExpiry(vaultRoot);
+  return clearCaptureFocusExpiryViaConsole(deps);
+}
+
+/**
+ * Mode-aware {@link ensureActiveCapturePin}.
+ *
+ * The cloud branch reuses {@link resolveActiveCapture} rather than restating its
+ * retirement / recently-promoted-lineage rules: that function already takes both
+ * a `focusOverride` and an injected `loadSpec`, so the console-sourced pin and a
+ * pre-fetched spec are handed straight to it and the SID6 / HS-KFB2 behavior is
+ * the same code on both tiers.
+ *
+ * The `AUTO_CREATE_UNAVAILABLE` guard is local-only by construction: cloud mode
+ * needs no id allocator because the console mints the id.
+ */
+export async function ensureActiveCapturePinViaMode(
+  vaultRoot,
+  parseFrontmatter,
+  loadSpec,
+  deps = {},
+  cloudDeps = {},
+) {
+  const writeMode = await resolveWriteModeOnce(cloudDeps.writeMode, cloudDeps);
+  if (writeMode !== 'cloud') {
+    return ensureActiveCapturePin(vaultRoot, parseFrontmatter, loadSpec, deps);
+  }
+  const ctx = captureCloudDeps(cloudDeps);
+  const { pinReason = 'Auto-created via MCP', claim = null } = deps;
+
+  const focus = await readCaptureFocusViaConsole(ctx);
+  let pinnedSpec = null;
+  if (focus?.spec_path) {
+    pinnedSpec = await ctx.loadSpecViaTier(
+      vaultRoot,
+      focus.spec_id ?? captureSpecIdFromSpecPath(focus.spec_path),
+      ctx.consoleUrl,
+    );
+  }
+  let resolved = resolveActiveCapture(vaultRoot, parseFrontmatter, () => pinnedSpec, focus ?? null);
+  if (!resolved.error) {
+    if (claim) await updateCaptureFocusClaimViaConsole(claim, ctx);
+    return { resolved, fresh: false, auto_created: false };
+  }
+
+  const previousError = resolved.error;
+  const recoverable =
+    resolved.error === 'NO_CAPTURE_PINNED' ||
+    resolved.error === 'CAPTURE_NOT_FOUND' ||
+    resolved.error === 'CAPTURE_RETIRED';
+  if (!recoverable) {
+    return { error: resolved.error, message: resolved.message };
+  }
+
+  const lineage =
+    resolved.recentlyPromoted && resolved.promotedTo
+      ? { promotedTo: resolved.promotedTo, retiredCaptureBasename: resolved.retiredCaptureBasename }
+      : null;
+
+  const created = await createFreshCaptureSpecViaConsole(vaultRoot, lineage, ctx);
+  const expires = new Date(Date.now() + CAPTURE_PIN_FUSE_MS).toISOString();
+  await writeCaptureFocusViaConsole(
+    { specId: created.spec_id, specPath: created.spec_path, reason: pinReason, claim, expires },
+    ctx,
+  );
+
+  const freshSpec = await ctx.loadSpecViaTier(vaultRoot, created.spec_id, ctx.consoleUrl);
+  resolved = resolveActiveCapture(vaultRoot, parseFrontmatter, () => freshSpec, {
+    spec_id: created.spec_id,
+    spec_path: created.spec_path,
+    pinned_at: new Date().toISOString(),
+    expires,
+    kind: 'idea',
+    reason: pinReason,
+  });
+  if (resolved.error) {
+    return {
+      error: resolved.error,
+      message: resolved.message || 'Auto-create failed after pin write.',
+    };
+  }
+  return {
+    resolved,
+    fresh: true,
+    auto_created: true,
+    replaced_stale_pin: previousError === 'CAPTURE_NOT_FOUND',
+    ...(created.continuation_of ? { continuation_of: created.continuation_of } : {}),
+  };
+}
+
+/**
+ * Mode-aware {@link executeUpdateCapture}.
+ *
+ * Cloud branch: the capture is sourced through the cloud read tier
+ * (`loadSpecByIdViaTier`, the read half this repo already shipped — nothing new
+ * is written here to fetch a spec), mutated by the SAME pure
+ * `computeCaptureUpdate` the local path runs, and persisted with
+ * `PUT /api/specs/:id`. The fuse-clear and claim-refresh follow-ups go to the
+ * console pin routes instead of the YAML pin file.
+ */
+export async function executeUpdateCaptureViaMode(
+  vaultRoot,
+  parseFrontmatter,
+  args = {},
+  deps = {},
+  cloudDeps = {},
+) {
+  const writeMode = await resolveWriteModeOnce(cloudDeps.writeMode, cloudDeps);
+  if (writeMode !== 'cloud') {
+    return executeUpdateCapture(vaultRoot, parseFrontmatter, args, deps);
+  }
+  const ctx = captureCloudDeps(cloudDeps);
+
+  let specPath = null;
+  let specId = null;
+  let loaded = null;
+  let autoCreated = false;
+  let continuationOf = null;
+
+  if (args.spec_id) {
+    loaded = await ctx.loadSpecViaTier(vaultRoot, args.spec_id, ctx.consoleUrl);
+    if (!loaded) {
+      return { error: 'SPEC_NOT_FOUND', message: `Capture ${args.spec_id} not found` };
+    }
+    specPath = loaded.specPath ?? null;
+    specId = loaded.frontmatter?.id ?? args.spec_id;
+  } else {
+    const ensured = await ensureActiveCapturePinViaMode(
+      vaultRoot,
+      parseFrontmatter,
+      deps.loadSpec,
+      {
+        pinReason: 'Auto-created via heyspex_update_capture',
+        claim: deps.claim ?? null,
+      },
+      { ...cloudDeps, writeMode: 'cloud' },
+    );
+    if (ensured.error) {
+      return { error: ensured.error, message: ensured.message };
+    }
+    autoCreated = ensured.auto_created === true;
+    continuationOf = ensured.continuation_of ?? null;
+    specPath = ensured.resolved.spec_path;
+    specId = ensured.resolved.spec_id;
+    loaded = { frontmatter: ensured.resolved.frontmatter, body: ensured.resolved.body, specPath };
+  }
+
+  const computed = computeCaptureUpdate(loaded.frontmatter ?? {}, loaded.body ?? '', args);
+  if (computed.error) return computed;
+  const { fm, newBody, core, notes, summaryWarning, hasContent } = computed;
+
+  const targetId = fm.id ?? specId;
+  if (!targetId) {
+    return {
+      error: 'CLOUD_MODE_UNSUPPORTED_WRITE',
+      message:
+        `Capture ${specPath ?? '(unknown path)'} carries no \`id:\` frontmatter, and PUT /api/specs/:id needs one. `
+        + 'NOTHING WAS WRITTEN — the local disk write is deliberately NOT used as a fallback in cloud vault-write mode.',
+      spec_path: specPath,
+      write_mode: 'cloud',
+      on_disk: false,
+    };
+  }
+
+  let written;
+  try {
+    written = await updateSpecViaConsole({
+      consoleFetch: ctx.consoleFetch,
+      consoleUrl: ctx.consoleUrl,
+      specId: targetId,
+      frontmatter: fm,
+      body: newBody,
+    });
+  } catch (err) {
+    return {
+      error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+      message: String(err?.message ?? err),
+      spec_id: targetId,
+      spec_path: specPath,
+      write_mode: 'cloud',
+      on_disk: false,
+      ...(err?.notFound ? { not_found: true } : {}),
+    };
+  }
+
+  if (hasContent) {
+    // Best-effort, exactly like the local fuse-clear: a fuse that cannot be
+    // dropped must not fail an update whose content already landed.
+    try {
+      await clearCaptureFocusExpiryViaConsole(ctx);
+    } catch (err) {
+      process.stderr.write?.(
+        `[heyspex-mcp] capture fuse not cleared through the console: ${err?.message ?? err}\n`,
+      );
+    }
+  }
+  if (deps.claim) {
+    await updateCaptureFocusClaimViaConsole(deps.claim, ctx);
+  }
+
+  return buildUpdateCaptureResult({
+    fm,
+    newBody,
+    specPath: written.relPath ?? specPath,
+    core,
+    notes,
+    args,
+    autoCreated,
+    continuationOf,
+    summaryWarning,
+    extra: { write_mode: 'cloud', on_disk: false, console_url: written.consoleUrl ?? ctx.consoleUrl },
+  });
+}
+
+/**
+ * Mode-aware {@link executePinCapture}. Cloud resolves the capture through the
+ * cloud read tier and pins it on the Neon control plane; the YAML pin file is
+ * never written.
+ */
+export async function executePinCaptureViaMode(
+  vaultRoot,
+  parseFrontmatter,
+  loadSpec,
+  args = {},
+  cloudDeps = {},
+) {
+  const writeMode = await resolveWriteModeOnce(cloudDeps.writeMode, cloudDeps);
+  if (writeMode !== 'cloud') {
+    return executePinCapture(vaultRoot, parseFrontmatter, loadSpec, args);
+  }
+  const ctx = captureCloudDeps(cloudDeps);
+  const specId = args.spec_id;
+  if (!specId) {
+    return { error: 'MISSING_SPEC_ID', message: 'spec_id is required' };
+  }
+  const spec = await ctx.loadSpecViaTier(vaultRoot, specId, ctx.consoleUrl);
+  if (!spec) {
+    return { error: 'SPEC_NOT_FOUND', message: `Capture ${specId} not found` };
+  }
+  const fmType = spec.frontmatter?.type;
+  if (fmType !== 'capture' && fmType !== 'idea') {
+    return { error: 'NOT_A_CAPTURE', message: `${specId} is not type: capture` };
+  }
+  const specPath = spec.specPath ?? null;
+  const pinnedKind = spec.frontmatter?.kind;
+  try {
+    await writeCaptureFocusViaConsole(
+      {
+        specId: spec.frontmatter?.id ?? specId,
+        specPath,
+        reason: args.reason || 'Pinned via MCP',
+        claim: null,
+        kind: typeof pinnedKind === 'string' ? pinnedKind : 'idea',
+      },
+      ctx,
+    );
+  } catch (err) {
+    return {
+      error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+      message: String(err?.message ?? err),
+      spec_id: specId,
+      spec_path: specPath,
+      write_mode: 'cloud',
+      on_disk: false,
+    };
+  }
+  return {
+    success: true,
+    spec_id: specId,
+    spec_path: specPath,
+    write_mode: 'cloud',
+    on_disk: false,
+    message: `Capture ${specId} is now on deck for /hs-capture`,
+  };
+}