heyspex 0.1.0 → 0.2.1

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

@@ -0,0 +1,1264 @@
+// The capture tools (heyspex_active_capture, update_capture, pin_capture,
+// promote_capture, promote_capture_to_diagnose) and the capture-session helpers
+// the prompts, recipes and filing tools share. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Console capture sessions API helpers — [[HS-TASK-MJJK]]
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { parseSpecId, shortLookupIdOf } from './spec-id-lib.mjs';
+import { consoleReadErrorFrom, readViaSelector, resolveReadTier, resolveVaultWriteMode } from './read-path.mjs';
+import { consoleFetch } from './console-transport.mjs';
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { findSpecFile, loadSpec, parseFrontmatter } from './vault-io.mjs';
+import { collectOccupiedIdsFromSpecs } from '../../scripts/vault-id-lib.mjs';
+import { RECENT_PROMOTION_LINEAGE_MS, buildCaptureBody, computeCaptureSufficiency, extractCaptureCoreFromBody, extractCaptureNotesFromBody, findCaptureSpecFile, loadCaptureFocusOffline, resolveActiveCapture, updateCaptureArgsVerdict, writeCaptureFocus } from './capture-focus.mjs';
+import { consoleErrorCode } from './console-fetch.mjs';
+import { executePromoteCapture, executePromoteCaptureToDiagnose } from './promote-capture.mjs';
+import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
+import { makeCaptureConsoleClient, respondToCaptureWriteFailure } from './capture-console-client.mjs';
+import { buildCaptureBufferPatches } from './capture-buffer-patches.mjs';
+import { normalizeCaptureSources } from './capture-sources.mjs';
+import { resolveActiveCaptureContent } from './capture-active-rehydrate.mjs';
+
+/**
+ * Query for pending capture sessions owned by the current user.
+ * GET /api/capture/sessions?status=pending
+ */
+export async function listPendingCaptureSessions() {
+  const result = await consoleFetch('/api/capture/sessions?status=pending');
+  if (!result.ok) {
+    return { ok: false, error: consoleErrorCode(result, 'LIST_FAILED'), result };
+  }
+  const sessions = result.body?.sessions || [];
+  return { ok: true, sessions, result };
+}
+
+/**
+ * Query for MATERIALIZED capture sessions owned by the current user, most
+ * recently active first (server-sorted — listCaptureSessions orders by
+ * lastActivityAt desc). Used only for the HS-KFB2 lineage check below — a
+ * `capture_sessions` row carries no promotion state of its own (that lives in
+ * the materialized FILE's `promoted_to:` frontmatter), so this is the list to
+ * scan for "was the idea we're about to fork FROM recently promoted".
+ * GET /api/capture/sessions?status=materialized
+ */
+export async function listMaterializedCaptureSessions() {
+  const result = await consoleFetch('/api/capture/sessions?status=materialized');
+  if (!result.ok) {
+    return { ok: false, error: consoleErrorCode(result, 'LIST_FAILED'), result };
+  }
+  const sessions = result.body?.sessions || [];
+  return { ok: true, sessions, result };
+}
+
+/**
+ * [[HS-KFB2-6RGF-DIAG-capture-continuation-mints-a-new-orphan]]: a same-session
+ * follow-on to an idea that was JUST promoted should surface as a continuation
+ * instead of silently forking a disconnected orphan capture. Given the
+ * caller's already-fetched materialized sessions (most-recent-first — the
+ * server sorts by lastActivityAt), scans them (bounded, first `limit`) for the
+ * first whose on-disk file shows a set `promoted_to:` updated within
+ * RECENT_PROMOTION_LINEAGE_MS, and returns that lineage or null.
+ *
+ * Deliberately advisory-only: never blocks, never attaches automatically —
+ * the caller surfaces `continuation_of` to the agent, which SUGGESTS the
+ * follow-on belongs on that lineage and gets the user's yes before acting
+ * ([[HS-5HYS]] elicitation), exactly like the capture-focus.mjs file-path
+ * fix this mirrors. Pure aside from the injected `loadSpecFn` — unit-testable
+ * without a live console.
+ *
+ * @param {Array<{specPath?: string|null}>} materializedSessions
+ * @param {(specPath: string) => {frontmatter?: Record<string, unknown>}|null} loadSpecFn
+ * @param {number} [limit] how many of the most-recent sessions to check (cheap local file reads; the list is already sorted, so 5 covers any plausible "which of my recent captures did I just promote" window without unbounded I/O).
+ * @returns {{ promotedTo: string, retiredCaptureId: string|null, retiredCaptureBasename: string } | null}
+ */
+export function findRecentlyPromotedLineage(materializedSessions, loadSpecFn, limit = 5) {
+  if (!Array.isArray(materializedSessions)) return null;
+  for (const session of materializedSessions.slice(0, limit)) {
+    const specPath = session?.specPath;
+    if (typeof specPath !== 'string' || !specPath) continue;
+    let spec;
+    try {
+      spec = loadSpecFn(specPath);
+    } catch {
+      continue;
+    }
+    if (!spec) continue;
+    const promotedTo = String(spec.frontmatter?.promoted_to ?? '').trim();
+    if (!promotedTo || promotedTo === 'null') continue;
+    const updatedAt = Date.parse(String(spec.frontmatter?.updated ?? ''));
+    if (!Number.isFinite(updatedAt) || Date.now() - updatedAt >= RECENT_PROMOTION_LINEAGE_MS) continue;
+    return {
+      promotedTo,
+      retiredCaptureId: spec.frontmatter?.id ?? null,
+      retiredCaptureBasename: specPath.replace(/^.*[\\/]/, '').replace(/\.md$/, ''),
+    };
+  }
+  return null;
+}
+
+/**
+ * Create a new capture session via POST /api/capture/sessions.
+ */
+export async function createCaptureSessionOnConsole(input) {
+  const result = await consoleFetch('/api/capture/sessions', {
+    method: 'POST',
+    body: input,
+  });
+  if (!result.ok) {
+    return { ok: false, error: consoleErrorCode(result, 'CREATE_FAILED'), result };
+  }
+  return { ok: true, session: result.body?.session, result };
+}
+
+/**
+ * Capture-session console client — error classification, PATCH wrapper, and
+ * outbox drain live in `capture-console-client.mjs` so they're testable
+ * without spawning the MCP stdin reader / capture-channel watcher. See
+ * [[HS-EPIC-CPMR]] for the error taxonomy and the multi-beat protocol
+ * substrate fix.
+ */
+export const captureConsoleClient = makeCaptureConsoleClient(consoleFetch);
+
+export const patchCaptureSessionOnConsole = (sessionId, patchBody) =>
+  captureConsoleClient.patchCaptureSession(sessionId, patchBody);
+
+/**
+ * GET a single capture session by id.
+ * GET /api/capture/sessions/:id
+ *
+ * Id tolerance (owner ruling 2026-08-21, the HS-XV4W promote failure): session
+ * rows store the SHORT era-3 id (`HS-<fileKey>`), but humans paste whatever
+ * form they last saw — the display id (`HS-XV4W-HV6H`) or the full basename.
+ * Try the id as given first (legacy `HS-CAP-*` rows resolve that way), then
+ * retry with the collapsed short id, so ANY recognizable form of the
+ * filename/id resolves — exactly like the local disk lookup does.
+ */
+export async function getCaptureSessionOnConsole(sessionId) {
+  const result = await consoleFetch(`/api/capture/sessions/${encodeURIComponent(sessionId)}`);
+  if (result.ok) {
+    return { ok: true, session: result.body?.session, result };
+  }
+  const short = shortLookupIdOf(sessionId);
+  if (short && short !== String(sessionId).trim()) {
+    const retry = await consoleFetch(`/api/capture/sessions/${encodeURIComponent(short)}`);
+    if (retry.ok) {
+      return { ok: true, session: retry.body?.session, result: retry };
+    }
+  }
+  return { ok: false, error: consoleErrorCode(result, 'GET_FAILED'), result };
+}
+
+/**
+ * Respond to a failed capture write ([[HS-K27H-DIAG-0G86]]).
+ *
+ * Capture is online-only ([[heyspex-is-online-only-no-offline]]); the offline
+ * buffer exists so nothing is lost across a GENUINE transport failure (status
+ * 0: ECONNREFUSED / DNS / timeout / abort) — and ONLY then. An HTTP 4xx/5xx
+ * means the server answered: the write failed and is surfaced verbatim, never
+ * stashed, and never described as a connectivity problem. The classification
+ * + payload building live in capture-console-client.mjs
+ * (`respondToCaptureWriteFailure`) so the stash-vs-surface rule is
+ * unit-testable; this alias keeps the call sites readable.
+ */
+export const captureWriteFailure = (vaultRoot, args, failure) =>
+  respondToCaptureWriteFailure(vaultRoot, args, failure);
+
+/**
+ * Drain offline-buffered captures into a now-reachable session.
+ * Thin wrapper around `captureConsoleClient.drainOutbox` — see that module
+ * for the transient-vs-structural classification contract. `currentBuffer`
+ * (the session's content_buffer) lets replayed append-shaped entries
+ * (userQuotes/chatTurns) merge instead of clobbering.
+ */
+export const drainCaptureOutbox = (vaultRoot, sessionId, identity, currentBuffer = {}) =>
+  captureConsoleClient.drainOutbox(vaultRoot, sessionId, identity, currentBuffer);
+
+/**
+ * /hs-promote-capture — promote 1+ captures into a research doc with AI-
+ * assisted outline. Implementation lives in `promote-capture.mjs`; two-phase
+ * flow when target_research === "NEW" (review then execute), single-phase for
+ * existing target_research. Mirrors handlePromoteResearch's injection shape.
+ *
+ * Cloud-tier reads ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]):
+ * `tier` is resolved ONCE per call here (`resolveReadTier()`) and threaded
+ * into `executePromoteCapture`'s deps — never re-resolved downstream. `overrides`
+ * lets a test inject `{ tier, consoleUrl, consoleFetch, resolveReadTier }`
+ * directly so it never opens a socket or depends on real dev-mode config;
+ * every production call site (tool-dispatch.mjs) passes none, so the real
+ * `resolveReadTier()` / `effectiveConsoleUrl()` / `consoleFetch` run unchanged.
+ *
+ * Cloud-tier WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * `writeMode` is resolved here the same way and on the same once-per-call rule
+ * — `resolveVaultWriteMode()` is the write-side twin of `resolveReadTier()`.
+ * This is the seam that makes the cloud write path reachable at all: the
+ * execute phase defaults to `deps.writeMode ?? 'local'`, so without this line
+ * a cloud-reliant session would still write markdown to a disk it may not have.
+ */
+export async function handlePromoteCapture(vaultRoot, args = {}, overrides = {}) {
+  try {
+    const doResolveReadTier = overrides.resolveReadTier ?? resolveReadTier;
+    const tier = overrides.tier ?? (await doResolveReadTier());
+    const doResolveWriteMode = overrides.resolveVaultWriteMode ?? resolveVaultWriteMode;
+    const writeMode = overrides.writeMode ?? (await doResolveWriteMode());
+    const consoleUrl = overrides.consoleUrl ?? effectiveConsoleUrl();
+    const doConsoleFetch = overrides.consoleFetch ?? consoleFetch;
+    const result = await executePromoteCapture(vaultRoot, args, {
+      consoleFetch: (path, options) => doConsoleFetch(path, options),
+      tier,
+      writeMode,
+      consoleUrl,
+    });
+    if (result?.error) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    }
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: 'PROMOTE_CAPTURE_EXCEPTION',
+              message: err?.message ?? String(err),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * heyspex_promote_capture_to_diagnose — one bug-report capture → one HS-DIAG-*
+ * diagnose spec ([[HS-MIL-BFIX]]). Single-phase; writes the diagnose + the
+ * capture's promoted_to/informs_diagnose linkage transactionally on disk, or
+ * POST-diagnose-then-PUT-capture through the console in cloud write mode.
+ *
+ * `tier` / `writeMode` follow the same once-per-call rule as
+ * {@link handlePromoteCapture} — resolved HERE, threaded down, never
+ * re-resolved in a helper. `overrides` keeps tests off the network.
+ */
+export async function handlePromoteCaptureToDiagnose(vaultRoot, args = {}, overrides = {}) {
+  try {
+    const doResolveReadTier = overrides.resolveReadTier ?? resolveReadTier;
+    const tier = overrides.tier ?? (await doResolveReadTier());
+    const doResolveWriteMode = overrides.resolveVaultWriteMode ?? resolveVaultWriteMode;
+    const writeMode = overrides.writeMode ?? (await doResolveWriteMode());
+    const consoleUrl = overrides.consoleUrl ?? effectiveConsoleUrl();
+    const doConsoleFetch = overrides.consoleFetch ?? consoleFetch;
+    const result = await executePromoteCaptureToDiagnose(vaultRoot, args, {
+      consoleFetch: (path, options) => doConsoleFetch(path, options),
+      tier,
+      writeMode,
+      consoleUrl,
+    });
+    if (result?.error) {
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { error: 'PROMOTE_CAPTURE_TO_DIAGNOSE_EXCEPTION', message: err?.message ?? String(err) },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Read capture-on-deck state from the Neon control plane, composed the same way
+ * the console's `readCaptureFocusState` does: layer-1 pin (`capture_focus_pin`)
+ * ⊕ layer-2 metadata (`capture_focus_selection`) ([[HS-TASK-CFL2]]). Layer-2 is
+ * attached only when its `spec_path` names the pinned spec, so a stale selection
+ * never paints onto a freshly-pinned spec. Falls back to the offline file read
+ * (`loadCaptureFocusOffline`) when the console is unreachable — the offline
+ * `/hs-capture` seam — which REFUSES a pin whose own `pinned_at` is older than
+ * `CAPTURE_FOCUS_FILE_STALE_MS` rather than serving a rotted answer quietly
+ * ([[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]]). Returns the same
+ * shape `loadCaptureFocus` does (or null when no pin, and null when one was refused
+ * — the loud stderr warning is what distinguishes those here).
+ */
+export async function readCaptureFocusVendor(vaultRoot) {
+  try {
+    const [pinRes, selRes] = await Promise.all([
+      consoleFetch('/api/control/capture-focus-pin'),
+      consoleFetch('/api/control/capture-focus-selection'),
+    ]);
+    if (pinRes?.ok) {
+      const pin = pinRes.body?.pin ?? null;
+      if (!pin) return null; // Neon authoritative — no pin means nothing on deck.
+      const sel = selRes?.ok ? (selRes.body?.selection ?? null) : null;
+      const base = (p) => String(p || '').replace(/^.*[/\\]/, '');
+      const selMatches = sel?.specPath ? base(sel.specPath).startsWith(pin.specId) : false;
+      const focus = {
+        spec_path: selMatches ? sel.specPath : `specs/captures/${pin.specId}.md`,
+        pinned_at: pin.pinnedAt,
+      };
+      if (pin.expiresAt) focus.expires = pin.expiresAt;
+      if (selMatches && sel) {
+        if (sel.kind) focus.kind = sel.kind;
+        if (sel.reason) focus.reason = sel.reason;
+        if (sel.claimedBy) focus.claimed_by = sel.claimedBy;
+        if (sel.claimSession) focus.claim_session = sel.claimSession;
+      }
+      if (!focus.kind) focus.kind = 'idea';
+      return focus;
+    }
+  } catch {
+    // Fall through to the offline file seam.
+  }
+  // Offline seam. The file is NOT the system of record on a console-backed vault,
+  // so a pin that has rotted there must be refused rather than served as if it were
+  // current — a capture silently attaching to a two-month-old pin is the failure
+  // ([[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]]). `loadCaptureFocusOffline`
+  // warns loudly and hands back null; null here already means "nothing on deck",
+  // and callers that need to tell the two apart call it directly for the reason.
+  return loadCaptureFocusOffline(vaultRoot).focus;
+}
+
+/**
+ * Resolve the capture genuinely on deck, from the LIVE pin.
+ *
+ * This is the read the capture-stage gate needs and the one the old hook could
+ * not do. `readCaptureFocusVendor` asks the console first and only falls back to
+ * `.heyspex/capture-focus.yaml` when it cannot be reached, so the answer tracks
+ * what `/hs-capture` actually pinned rather than whatever the last offline
+ * session left on disk.
+ *
+ * Returns the resolved capture, or null for every "nothing is open" case — no
+ * pin, a pin whose capture was promoted or closed, a pin with no file yet that
+ * the console cannot confirm, or any failure at all. Null means allow: this
+ * resolver never refuses on its own uncertainty.
+ */
+export async function resolveLiveActiveCapture(vaultRoot) {
+  let focus = null;
+  try {
+    focus = await readCaptureFocusVendor(vaultRoot);
+  } catch {
+    return null;
+  }
+  if (!focus?.spec_path) return null;
+
+  const resolved = resolveActiveCapture(vaultRoot, parseFrontmatter, loadSpec, focus);
+  if (resolved && !resolved.error && resolved.spec_id) return resolved;
+
+  // A capture session that has not materialized to a file yet has no markdown to
+  // read, so the disk resolve above returns CAPTURE_NOT_FOUND. Ask the console
+  // for the live session row before concluding nothing is open — that pending
+  // state is the common case during an active /hs-capture.
+  if (resolved?.error !== 'CAPTURE_NOT_FOUND') return null;
+  const pinnedId = captureSpecIdFromPath(focus.spec_path);
+  if (!pinnedId) return null;
+  try {
+    const got = await getCaptureSessionOnConsole(pinnedId);
+    const session = got.ok ? got.session : null;
+    if (!session) return null;
+    const status = String(session.status ?? '').trim().toLowerCase();
+    if (status && status !== 'pending' && status !== 'open') return null;
+    return { spec_id: session.id ?? pinnedId, spec_path: session.specPath ?? focus.spec_path, session };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the caller-facing refusal for a capture pin that did not land, so all six
+ * `writeCaptureFocusVendor` call sites report the same measured failure instead of
+ * each inventing a "pinned" message from its own request.
+ */
+export function captureFocusPinRefusal(pin, { specId, specPath } = {}) {
+  return {
+    error: 'CAPTURE_PIN_NOT_WRITTEN',
+    pinned: false,
+    spec_id: specId ?? pin?.spec_id ?? null,
+    spec_path: specPath ?? pin?.spec_path ?? null,
+    pin,
+    message:
+      `Capture ${specId ?? pin?.spec_id ?? '(unknown)'} was NOT pinned on deck (${pin?.reason ?? 'unknown'}). ` +
+      'Nothing readable persisted, so /hs-capture will resolve to whatever was pinned before — treat this ' +
+      'capture as NOT on deck. Check heyspex_dev_server_status, then re-pin with heyspex_pin_capture.',
+  };
+}
+
+/**
+ * Markdown form of the same measured verdict, for the `/hs-capture` PROMPT
+ * surfaces (prompts.mjs), which return markdown and have no `isError` channel.
+ * Empty string when the pin landed, so a healthy prompt is byte-identical to
+ * before; a loud banner ABOVE the capture body when it did not.
+ */
+export function capturePinWarningBanner(pin, specId) {
+  if (pin?.pinned) return '';
+  return (
+    `> ⚠️ **Capture-on-deck pin NOT written** (${pin?.reason ?? 'unknown'}). This capture ` +
+    `(\`${specId}\`) is open, but it is **not on deck**: a later \`/hs-capture\` with no id will ` +
+    `resolve to a DIFFERENT capture, and \`heyspex_active_capture\` without \`spec_id\` may attach ` +
+    `to the wrong one. Always pass \`spec_id: "${specId}"\` explicitly for the rest of this capture, ` +
+    `and re-pin with \`heyspex_pin_capture\` once the console is healthy.\n\n`
+  );
+}
+
+/**
+ * Pin capture-on-deck + layer-2 metadata to the Neon control plane the same way
+ * the console's `setCaptureFocus` does: PUT `capture_focus_pin` (layer-1) +
+ * `capture_focus_selection` (layer-2) ([[HS-TASK-CFL2]]).
+ *
+ * REPORTS THE RESULT, NEVER THE REQUEST ([[HS-IOJW-5YDH-DIAG]] sweep). This used
+ * to return a bare boolean that all six callers discarded while printing
+ * "pinned"; worse, the `false` branch was not even a uniform failure. There are
+ * three genuinely different outcomes and the old boolean collapsed them:
+ *
+ *   neon        — both PUTs ok. Pinned, and the read path reads it.
+ *   file        — the console could not be REACHED (status 0). The legacy file
+ *                 write is a real pin here, because `readCaptureFocusVendor`
+ *                 falls through to `loadCaptureFocusOffline` in exactly this
+ *                 case. Genuinely pinned.
+ *   none        — the console ANSWERED and refused the write (non-2xx), or the
+ *                 file write itself failed. The YAML fallback is DEAD in the
+ *                 answered case: `readCaptureFocusVendor` sees `pinRes.ok` and a
+ *                 null pin, and returns null without ever consulting the file.
+ *                 Nothing readable persisted → `pinned: false`.
+ *
+ * The file write is measured, not assumed (`measureDiskLanding` idiom): the pin
+ * is only claimed after the bytes are read back carrying this spec_path.
+ *
+ * @returns {Promise<{ pinned: boolean, tier: 'neon'|'file'|'none', reason: string,
+ *   reported_by: 'measured', spec_id: string|null, spec_path: string|null,
+ *   console_status?: object, landed?: object }>}
+ */
+export async function writeCaptureFocusVendor(
+  vaultRoot,
+  { specId, specPath, reason, claim } = {},
+  // Injection seam (idiom: fleet-queue-tools.mjs) so a test can drive each of the
+  // three outcomes without a console. Production callers pass two args.
+  { fetchImpl = consoleFetch } = {},
+) {
+  const id =
+    specId ||
+    captureSpecIdFromPath(specPath);
+  const resolvedPath = specPath || (id ? `specs/captures/${id}.md` : null);
+  const base = { reported_by: 'measured', spec_id: id ?? null, spec_path: resolvedPath };
+
+  // `consoleFetch` never throws — an unreachable console comes back as
+  // `{ ok: false, status: 0 }`. So "answered" is `status !== 0`, and that is the
+  // distinction that decides whether the file fallback can ever be read back.
+  let consoleAnswered = false;
+  let consoleStatus = null;
+  try {
+    if (id) {
+      const [pinRes, selRes] = await Promise.all([
+        fetchImpl('/api/control/capture-focus-pin', {
+          method: 'PUT',
+          body: { spec_id: id, pinned_by: claim?.claimed_by || 'agent' },
+        }),
+        fetchImpl('/api/control/capture-focus-selection', {
+          method: 'PUT',
+          body: {
+            spec_path: resolvedPath,
+            kind: 'idea',
+            reason: reason ?? null,
+            claimed_by: claim?.claimed_by ?? null,
+            claim_session: claim?.claim_session ?? null,
+          },
+        }),
+      ]);
+      if (pinRes?.ok && selRes?.ok) return { ...base, pinned: true, tier: 'neon', reason: 'neon_write_ok' };
+      consoleStatus = { pin: pinRes?.status ?? null, selection: selRes?.status ?? null };
+      // A non-zero status means the server ANSWERED and rejected the write.
+      consoleAnswered = Boolean(pinRes?.status) || Boolean(selRes?.status);
+      console.error(
+        `[hs-capture] capture focus not pinned to Neon — console returned pin=${pinRes?.status ?? 'no response'} ` +
+          `sel=${selRes?.status ?? 'no response'}. Falling back to the offline file.`,
+      );
+    }
+  } catch (err) {
+    console.error(
+      `[hs-capture] capture focus Neon write failed (${err?.message ?? err}); falling back to the offline file.`,
+    );
+  }
+
+  // Offline / failure fallback: keep the legacy file write (offline capture seam).
+  const landed = writeCaptureFocusMeasured(vaultRoot, specPath, reason, claim);
+  if (!landed.on_disk || landed.spec_path_readback !== true) {
+    return {
+      ...base,
+      pinned: false,
+      tier: 'none',
+      reason: 'file_write_failed',
+      ...(consoleStatus ? { console_status: consoleStatus } : {}),
+      landed,
+    };
+  }
+  if (consoleAnswered) {
+    // The console is UP and refused the write. Neon is what the read path
+    // consults while it is up, so the file just written will never be read back
+    // — a shadow, not a pin. Say so rather than reporting a successful fallback.
+    return {
+      ...base,
+      pinned: false,
+      tier: 'none',
+      reason: 'console_answered_but_rejected_write',
+      console_status: consoleStatus,
+      landed,
+    };
+  }
+  return { ...base, pinned: true, tier: 'file', reason: 'console_unreachable_offline_file_pin', landed };
+}
+
+/**
+ * `writeCaptureFocus` + a read-back, so the offline pin is measured rather than
+ * assumed. Mirrors `measureDiskLanding` (tool-helpers.mjs) for a file this module
+ * writes through a helper that returns nothing. Never throws.
+ */
+export function writeCaptureFocusMeasured(vaultRoot, specPath, reason, claim) {
+  const abs = join(vaultRoot, '.heyspex', 'capture-focus.yaml');
+  const out = { tier: 'disk', reported_by: 'measured', abs_path: abs, on_disk: false, bytes: null, spec_path_readback: false };
+  try {
+    writeCaptureFocus(vaultRoot, specPath, reason, claim);
+  } catch (err) {
+    out.error = String(err?.message ?? err);
+    return out;
+  }
+  try {
+    const raw = readFileSync(abs, 'utf8');
+    out.on_disk = true;
+    out.bytes = Buffer.byteLength(raw);
+    // An empty spec_path is not a pin — `spec_path:` with nothing after it names
+    // no capture, so it must never read back as a landed offline pin.
+    out.spec_path_readback =
+      typeof specPath === 'string' && specPath.trim().length > 0 && raw.includes(`spec_path: ${specPath}`);
+  } catch (err) {
+    out.error = String(err?.message ?? err);
+  }
+  return out;
+}
+
+/** Derive the capture spec id (`HS-CAP-XXXX`) from a capture spec_path basename. */
+export function captureSpecIdFromPath(specPath) {
+  const baseName = String(specPath || '').replace(/^.*[/\\]/, '').replace(/\.md$/i, '');
+  return baseName.match(/^(HS-[A-Z]+-[A-Z0-9]{3,})/)?.[1] || null;
+}
+
+/**
+ * Grounding-time sufficiency verdict for the database-backed capture path
+ * ([[HS-Q8O5-MG6A-DIAG-the-capture-sufficiency-verdict-never]],
+ * [[HS-58O9-X98Y-DIAG-cloud-capture-materializer-never]]): `computeCaptureSufficiency`
+ * is the same scorer `heyspex_promote_capture` runs, but it was only ever wired
+ * into the disk/file-backed `resolveActiveCapture` path — every database-tier
+ * `heyspex_active_capture` / `heyspex_update_capture` response (the normal case
+ * whenever the console is reachable) carried no `sufficiency` field at all, so
+ * an agent following the /hs-capture protocol had nothing to gate "offer
+ * promote" on. Scores the materialized file at `specPath` when one exists;
+ * reports `null` with a reason (not a fabricated fail) before materialization,
+ * since there is no body yet to score.
+ * @param {string} vaultRoot
+ * @param {string|null|undefined} specPath
+ * @returns {{ sufficiency: object|null, sufficiency_reason?: string }}
+ */
+export function sufficiencyForSpecPath(vaultRoot, specPath, session = null) {
+  // Cloud/database path ([[HS-WF23]]): the session row carries the content the console
+  // holds, but the spec file is not on this machine (cloud materialization) or does not exist
+  // yet. Score the body rebuilt from the session's content_buffer rather than report
+  // `spec_unreadable` for a capture that has real content.
+  const fromBuffer = () => {
+    const body = bodyFromContentBuffer(session?.contentBuffer);
+    if (body === null) return null;
+    try {
+      return { sufficiency: computeCaptureSufficiency({ kind: session?.contentBuffer?.kind }, body) };
+    } catch {
+      return { sufficiency: null, sufficiency_reason: 'scorer_error' };
+    }
+  };
+  if (!specPath) {
+    return fromBuffer() ?? { sufficiency: null, sufficiency_reason: 'not_yet_materialized' };
+  }
+  try {
+    const spec = loadSpec(vaultRoot, specPath);
+    if (!spec) return fromBuffer() ?? { sufficiency: null, sufficiency_reason: 'spec_unreadable' };
+    return { sufficiency: computeCaptureSufficiency(spec.frontmatter, spec.body) };
+  } catch {
+    return fromBuffer() ?? { sufficiency: null, sufficiency_reason: 'scorer_error' };
+  }
+}
+
+/**
+ * Rebuild the capture body from a session content_buffer (structured `{at,text}` or flat
+ * shapes), byte-compatible with what materialization writes. `null` when the buffer holds no
+ * authored content (nothing to score — keep the honest null verdict).
+ * @param {object|null|undefined} cb
+ * @returns {string|null}
+ */
+export function bodyFromContentBuffer(cb) {
+  if (!cb || typeof cb !== 'object') return null;
+  const { core, summary, notes } = normalizeCaptureBuffer(cb);
+  const example = bufferText(cb.example);
+  const userStories = bufferText(cb.userStories ?? cb.user_stories);
+  const doneWhen = bufferText(cb.doneWhen ?? cb.done_when);
+  const jtbd = bufferText(cb.jtbd);
+  const details = bufferText(cb.details ?? cb.agent_expansion);
+  if (![core, summary, notes, example, userStories, doneWhen, jtbd, details].some(Boolean)) return null;
+  return buildCaptureBody(core, notes, summary, details, '', example, userStories, doneWhen, jtbd);
+}
+
+/**
+ * [[HS-TASK-MJJK]] — rewired to query sessions API first.
+ * 1. If spec_id is provided, resolve that exact capture DB-first
+ *    (getCaptureSessionOnConsole), so a pending session resolves; fall back to
+ *    disk for materialized / legacy captures whose live row is gone.
+ * 2. Otherwise, query GET /api/capture/sessions?status=pending for active session.
+ * 3. If a pending session exists, return its data (database is source of truth).
+ * 4. If API unreachable or no pending session, fallback to file-based logic.
+ */
+export async function handleActiveCapture(vaultRoot, args) {
+  // If spec_id is provided, resolve THAT exact capture. The channel push carries
+  // the authoritative capture_id (capture-channel.mjs), so the agent is told to
+  // pass it here — resolving by id is how we avoid the "wrong capture" divergence.
+  if (args.spec_id) {
+    const wantedId = String(args.spec_id).trim();
+    // DB FIRST: a pending capture session has no markdown file yet, so the
+    // disk-only lookup below would 404 it. Resolve the live session row by id so
+    // a pending capture (the common channel-driven case) returns real state.
+    const got = await getCaptureSessionOnConsole(wantedId);
+    if (got.ok && got.session) {
+      const session = got.session;
+      // Same [[HS-U29N-DIAG-T2DR]] rehydration as the no-spec_id path below —
+      // an explicitly-named session can carry the same stale/empty buffer
+      // divergence from its materialized file.
+      const rehydrated = resolveActiveCaptureContent(session, {
+        normalizeBuffer: normalizeCaptureBuffer,
+        loadSpec: (specPath) => loadSpec(vaultRoot, specPath),
+        extractCore: extractCaptureCoreFromBody,
+        extractNotes: extractCaptureNotesFromBody,
+      });
+      const contentBuffer = rehydrated.contentBuffer;
+      const payload = {
+        spec_id: session.id,
+        spec_path: session.specPath || null,
+        name: contentBuffer.name || `Capture ${session.id}`,
+        core_idea: contentBuffer.core_idea || '',
+        notes: contentBuffer.notes || '',
+        status: session.status,
+        source: rehydrated.rehydrated_from_disk ? 'database+disk-rehydrated' : 'database',
+        is_new: rehydrated.is_new,
+        session,
+        ...sufficiencyForSpecPath(vaultRoot, session.specPath, session),
+      };
+      if (!rehydrated.is_new) {
+        payload.guidance =
+          'This capture already has content (is_new: false) — do NOT overwrite existing sections (core_idea/summary/notes/example/user_stories) without explicit user instruction. Append or ask before replacing.';
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    // DB miss (404 / GET_FAILED) or console unreachable → fall back to disk for
+    // materialized / legacy captures whose live session row is gone.
+    const specPath =
+      findCaptureSpecFile(vaultRoot, wantedId) || findSpecFile(vaultRoot, wantedId);
+    if (!specPath) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'SPEC_NOT_FOUND', message: wantedId }) }],
+      };
+    }
+    const spec = loadSpec(vaultRoot, specPath);
+    if (!spec) {
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'LOAD_FAILED' }) }] };
+    }
+    const diskCore = extractCaptureCoreFromBody(spec.body);
+    const diskNotes = extractCaptureNotesFromBody(spec.body);
+    const resolved = {
+      spec_id: spec.frontmatter?.id || wantedId,
+      spec_path: specPath,
+      name: spec.frontmatter?.name,
+      core_idea: diskCore,
+      notes: diskNotes,
+      // A disk file exists for this exact id — never a fresh/empty capture,
+      // regardless of whether its sections happen to be blank.
+      is_new: false,
+      focus: await readCaptureFocusVendor(vaultRoot),
+      sufficiency: computeCaptureSufficiency(spec.frontmatter, spec.body),
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(resolved, null, 2) }] };
+  }
+
+  // Capture is online-only — query the sessions API. [[HS-TASK-MJJK]]
+  const identity = detectAgentIdentity();
+  const forceNew = args.force_new === true;
+
+  // force_new: true ([[HS-1C4L-9VZV-DIAG-multi-agent-capture-focus-pin-collision]])
+  // — skip the pending-session list/attach path entirely and unconditionally mint
+  // a fresh session. `forceNew: true` also disables the console's empty-session
+  // reuse-fold (scoped by ownerUserId+openedBy, NOT openedBySession — so without
+  // this, two concurrent agent sessions could still silently fold onto the same
+  // empty pending row even when this caller never intended to attach to anything).
+  let session = null;
+  // HS-KFB2: true only when THIS call minted a brand-new session (never when
+  // attaching to an existing pending one) — that's the exact moment a
+  // same-session follow-on to a recently-promoted idea would otherwise become
+  // a silent orphan. force_new explicitly asks for a genuinely new, unlinked
+  // topic (its own doc comment above), so it deliberately skips this check.
+  let freshlyCreated = false;
+  if (forceNew) {
+    const createResult = await createCaptureSessionOnConsole({
+      opened_by: 'agent',
+      opened_by_session: identity.sessionId,
+      mode: 'attended',
+      status: 'pending',
+      force_new: true,
+    });
+    if (!createResult.ok) {
+      const refusal = captureWriteFailure(vaultRoot, {}, createResult);
+      return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+    }
+    session = createResult.session;
+  } else {
+    const sessionsResult = await listPendingCaptureSessions();
+
+    if (!sessionsResult.ok) {
+      // Transport failure → graceful refuse; never mint a local file scaffold
+      // ([[heyspex-is-online-only-no-offline]]). active_capture carries no user
+      // words, so nothing is stashed. An answered HTTP error is surfaced
+      // honestly instead of masquerading as unreachable (HS-K27H).
+      const refusal = captureWriteFailure(vaultRoot, {}, sessionsResult);
+      return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+    }
+
+    // Reachable: attach to THE pending session, or agent-first auto-create one — in
+    // the DB, not a file. This is where the three surfaces converge.
+    session = sessionsResult.sessions[0] || null;
+    if (!session) {
+      const createResult = await createCaptureSessionOnConsole({
+        opened_by: 'agent',
+        opened_by_session: identity.sessionId,
+        mode: 'attended',
+        status: 'pending',
+      });
+      if (!createResult.ok) {
+        const refusal = captureWriteFailure(vaultRoot, {}, createResult);
+        return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+      }
+      session = createResult.session;
+      freshlyCreated = true;
+    }
+  }
+
+  // Now that we're online, flush any offline-buffered captures into this session
+  // (append against the session's live buffer, not a blank one — HS-K27H).
+  const drain = await drainCaptureOutbox(
+    vaultRoot,
+    session.id,
+    identity,
+    session.contentBuffer && typeof session.contentBuffer === 'object'
+      ? session.contentBuffer
+      : {},
+  );
+  if (drain.drained > 0) {
+    const refetched = await getCaptureSessionOnConsole(session.id);
+    if (refetched.ok && refetched.session) session = refetched.session;
+  }
+
+  // [[HS-U29N-DIAG-T2DR]] fix: never trust an empty content_buffer at face
+  // value when the attached session's capture is already materialized — the
+  // buffer and the on-disk file can diverge, and reporting "empty" here is
+  // exactly what let an agent conclude a live capture was safe to overwrite.
+  // Rehydrate from disk when needed, and always tell the caller whether this
+  // is a genuinely new/empty capture via `is_new`.
+  const rehydrated = resolveActiveCaptureContent(session, {
+    normalizeBuffer: normalizeCaptureBuffer,
+    loadSpec: (specPath) => loadSpec(vaultRoot, specPath),
+    extractCore: extractCaptureCoreFromBody,
+    extractNotes: extractCaptureNotesFromBody,
+  });
+  const contentBuffer = rehydrated.contentBuffer;
+  const payload = {
+    spec_id: session.id,
+    spec_path: session.specPath || null,
+    name: contentBuffer.name || `Capture ${session.id}`,
+    core_idea: contentBuffer.core_idea || '',
+    notes: contentBuffer.notes || '',
+    status: session.status,
+    source: rehydrated.rehydrated_from_disk ? 'database+disk-rehydrated' : 'database',
+    is_new: rehydrated.is_new,
+    session,
+    synced_from_offline_buffer: drain.drained || undefined,
+    ...sufficiencyForSpecPath(vaultRoot, session.specPath, session),
+  };
+  if (!rehydrated.is_new) {
+    payload.guidance =
+      'This capture already has content (is_new: false) — do NOT overwrite existing sections (core_idea/summary/notes/example/user_stories) without explicit user instruction. Append or ask before replacing.';
+  }
+  // HS-KFB2: this call minted a brand-new session — check whether it's really
+  // a same-session follow-on to an idea that was JUST promoted, so the agent
+  // can suggest attaching to that lineage instead of treating this as
+  // unrelated. Advisory only (never blocks, never auto-attaches); a lookup
+  // failure degrades to silence, same as every other best-effort check here.
+  if (freshlyCreated) {
+    try {
+      const materialized = await listMaterializedCaptureSessions();
+      if (materialized.ok) {
+        const lineage = findRecentlyPromotedLineage(materialized.sessions, (specPath) =>
+          loadSpec(vaultRoot, specPath),
+        );
+        if (lineage) {
+          payload.continuation_of = lineage.promotedTo;
+          payload.continuation_note =
+            `This capture was just auto-created, and a recently-promoted idea (${lineage.promotedTo}` +
+            (lineage.retiredCaptureId ? `, from ${lineage.retiredCaptureId}` : '') +
+            `) is still fresh in this session. Before treating this as unrelated, consider telling the ` +
+            `user this looks like a follow-on to that idea and offering to add it to ${lineage.promotedTo} ` +
+            `instead of (or in addition to) this new capture ([[HS-KFB2-6RGF-DIAG-capture-continuation-mints-a-new-orphan]]).`;
+        }
+      }
+    } catch {
+      // best-effort — never block active_capture on this check
+    }
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * [[HS-TASK-MJJK]] + Defect 3 — capture is online-only ([[heyspex-is-online-only-no-offline]]).
+ * 1. If spec_id is provided, use that session.
+ * 2. Otherwise, attach to the pending session, or agent-first auto-create one in the DB.
+ * 3. Drain any offline-buffered captures, then PATCH the session's content_buffer.
+ * 4. If console is unreachable, stash the verbatim input to the offline buffer
+ *    ([[capture-outbox]]) and refuse gracefully — NEVER a divergent file scaffold.
+ *
+ * Materialization is triggered server-side per [[HS-TASK-U9E7]].
+ */
+export async function handleUpdateCapture(vaultRoot, args) {
+  // First hop: refuse an unrecognized/misspelled arg BY NAME instead of
+  // letting it silently vanish into buildCaptureBufferPatches's explicit
+  // allowlist — the declared `additionalProperties: false` inputSchema above
+  // is never validated at runtime by any layer
+  // [[additionalproperties-false-in-an-mcp]].
+  const argsVerdict = updateCaptureArgsVerdict(args);
+  if (!argsVerdict.ok) {
+    return { content: [{ type: 'text', text: JSON.stringify(argsVerdict.error, null, 2) }] };
+  }
+
+  // sources (links / original files): validate BEFORE anything is written so an
+  // oversize or malformed entry is refused by name with nothing half-saved.
+  // The normalized result is not reused: buildCaptureBufferPatches re-derives
+  // it with the same timestamp it stamps on every other field.
+  if (args.sources !== undefined) {
+    const srcVerdict = normalizeCaptureSources(args.sources, new Date().toISOString());
+    if (!srcVerdict.ok) {
+      return { content: [{ type: 'text', text: JSON.stringify(srcVerdict.error, null, 2) }] };
+    }
+  }
+
+  const identity = detectAgentIdentity();
+
+  // Resolve the session to update — online-only, no file-mode fallback.
+  let sessionId = args.spec_id?.trim();
+
+  if (!sessionId) {
+    const sessionsResult = await listPendingCaptureSessions();
+    if (!sessionsResult.ok) {
+      // Transport failure → stash the verbatim words + graceful refuse (no
+      // file write). An answered HTTP error is surfaced honestly instead —
+      // never stashed, never called "unreachable" (HS-K27H).
+      const refusal = captureWriteFailure(vaultRoot, args, sessionsResult);
+      return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+    }
+    if (sessionsResult.sessions.length > 0) {
+      sessionId = sessionsResult.sessions[0].id;
+    } else {
+      // Reachable but no pending session → agent-first auto-create in the DB.
+      const createResult = await createCaptureSessionOnConsole({
+        opened_by: 'agent',
+        opened_by_session: identity.sessionId,
+        mode: 'attended',
+        status: 'pending',
+      });
+      if (!createResult.ok) {
+        const refusal = captureWriteFailure(vaultRoot, args, createResult);
+        return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+      }
+      sessionId = createResult.session.id;
+    }
+  }
+
+  // Read the current buffer BEFORE draining so replayed append-shaped entries
+  // (userQuotes/chatTurns) merge with what is already on the session instead
+  // of clobbering it (HS-K27H) — and so this call's own multi-beat appends
+  // merge too. The console PATCH route stores top-level keys verbatim
+  // (last-write-wins); the buffer must carry the canonical STRUCTURED shapes
+  // (userQuotes: Array<{at,text}>, coreIdea/concept/details:
+  // {at,text,confirmed}); flat strings render an empty body ([[HS-EPIC-CPMR]]).
+  let currentBuffer = {};
+  const existing = await getCaptureSessionOnConsole(sessionId);
+  if (
+    existing.ok &&
+    existing.session &&
+    existing.session.contentBuffer &&
+    typeof existing.session.contentBuffer === 'object'
+  ) {
+    currentBuffer = existing.session.contentBuffer;
+  }
+
+  // Online with a session → flush any offline-buffered captures first (oldest
+  // first, chronological), then file this update. Re-read the buffer if the
+  // drain wrote anything, so this call's patches build on the drained state.
+  const drainResult = await drainCaptureOutbox(vaultRoot, sessionId, identity, currentBuffer);
+  if (drainResult.drained > 0) {
+    const refetched = await getCaptureSessionOnConsole(sessionId);
+    if (
+      refetched.ok &&
+      refetched.session &&
+      refetched.session.contentBuffer &&
+      typeof refetched.session.contentBuffer === 'object'
+    ) {
+      currentBuffer = refetched.session.contentBuffer;
+    }
+  }
+
+  const iso = new Date().toISOString();
+  const patches = buildCaptureBufferPatches(args, currentBuffer, iso);
+
+  const attach = { agent: identity.agent, sessionId: identity.sessionId };
+  const patchResult = await patchCaptureSessionOnConsole(sessionId, { patches, attach });
+
+  if (!patchResult.ok) {
+    // HS-K27H classification — one decision point:
+    //   transport (status 0) → stash to the offline buffer + honest sync
+    //     message (the next drain replays every stashed field).
+    //   4xx → status "refused": the server answered and rejected the write;
+    //     server error + message verbatim; NOT stashed (the pre-fix 409
+    //     dead-letters permanently head-of-line-blocked the queue).
+    //   5xx → status "failed": the server answered and errored; message
+    //     verbatim; NOT stashed (pre-fix this was disguised as
+    //     "can't reach the server" with a false sync promise).
+    const payload = captureWriteFailure(vaultRoot, args, patchResult);
+    if (payload.status !== 'deferred') payload.spec_id = sessionId;
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  }
+
+  const payload = {
+    success: true,
+    spec_id: sessionId,
+    spec_path: patchResult.session?.specPath || null,
+    source: 'database',
+    session: patchResult.session,
+    materialization: patchResult.materialization || null,
+    message: 'Capture session updated via API. Materialization handled server-side.',
+    ...sufficiencyForSpecPath(vaultRoot, patchResult.session?.specPath, patchResult.session),
+  };
+
+  // Agent-originated captures never auto-open a browser window (companion /
+  // chrome-extension only). On FIRST materialization, surface a one-shot
+  // "want to see it?" offer so the agent can ask and open on a plain yes.
+  const mat = patchResult.materialization;
+  const openedBy = patchResult.session?.openedBy;
+  if (mat && mat.materialized === true && mat.first === true && openedBy === 'agent') {
+    payload.offer_open_viewer = {
+      prompt:
+        `Capture \`${sessionId}\` is on disk. Want to see it? Say **yes** / **open** / **show** and I'll open the doc.`,
+      confirm_tokens: ['yes', 'open', 'show'],
+      on_confirm: {
+        shell: `node bin/hs.mjs view docs ${sessionId}`,
+        note:
+          'Opens the capture in a chromeless solo docs window. NEVER auto-open without an explicit confirm token from the user.',
+      },
+    };
+  }
+
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * [[HS-TASK-MJJK]], fixed per [[HS-1C4L-9VZV-DIAG-multi-agent-capture-focus-pin-collision]]
+ * AC3 — `spec_id` is REQUIRED by the tool's inputSchema, but the original
+ * implementation silently ignored it and always created/reused an unrelated
+ * session — a caller asking to pin an EXISTING capture got a different one
+ * back with no error. That made the tool non-functional for its documented
+ * purpose (the "escape hatch" heyspex_active_capture's own description
+ * points to), which is what led the diagnose to conclude it had no real
+ * callable surface.
+ *
+ * Now: `spec_id` given → resolve THAT capture (DB session, else on-disk
+ * materialized spec) and pin it — touching the DB row's activity/attachment
+ * so it becomes the most-recently-active pending session (the "on deck" one
+ * for the no-spec_id `heyspex_active_capture` resolution), never creating or
+ * attaching to a different capture. `spec_id` omitted → back-compat: mint a
+ * fresh session, same as before.
+ */
+export async function handlePinCapture(vaultRoot, args) {
+  const identity = detectAgentIdentity();
+  const wantedId = args.spec_id ? String(args.spec_id).trim() : '';
+
+  if (wantedId) {
+    const got = await getCaptureSessionOnConsole(wantedId);
+    if (got.ok && got.session) {
+      // Touch the row (empty patch + attach) so it becomes sessions[0] for
+      // subsequent no-spec_id lookups — the actual "pin" effect, without
+      // mutating any content. Refuses (409) only if the row is abandoned.
+      const patchResult = await patchCaptureSessionOnConsole(wantedId, {
+        patches: [],
+        attach: { agent: identity.agent, sessionId: identity.sessionId },
+      });
+      const session = patchResult.ok ? patchResult.session : got.session;
+      const pin = await writeCaptureFocusVendor(vaultRoot, {
+        specId: session.id,
+        specPath: session.specPath || '',
+        reason: args.reason || 'Pinned via MCP',
+        claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+      });
+      // Measured, not assumed: `pinned: false` means nothing readable persisted,
+      // so this cannot return `success: true, message: "... pinned ..."`.
+      if (!pin.pinned) {
+        return {
+          isError: true,
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              ...captureFocusPinRefusal(pin, { specId: session.id, specPath: session.specPath || null }),
+              source: 'database',
+              session,
+            }, null, 2),
+          }],
+        };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            success: true,
+            spec_id: session.id,
+            spec_path: session.specPath || null,
+            source: 'database',
+            session,
+            pin,
+            pinned: true,
+            message: `Capture ${session.id} pinned for /hs-capture (${pin.tier})`,
+          }, null, 2),
+        }],
+      };
+    }
+    // DB miss → fall back to a materialized on-disk capture (legacy / no live
+    // session row). Pin the file directly; no session to touch.
+    const specPath = findCaptureSpecFile(vaultRoot, wantedId) || findSpecFile(vaultRoot, wantedId);
+    if (!specPath) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'SPEC_NOT_FOUND', message: wantedId }) }],
+      };
+    }
+    const pin = await writeCaptureFocusVendor(vaultRoot, {
+      specId: wantedId,
+      specPath,
+      reason: args.reason || 'Pinned via MCP',
+      claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+    });
+    if (!pin.pinned) {
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify(
+            { ...captureFocusPinRefusal(pin, { specId: wantedId, specPath }), source: 'disk' },
+            null,
+            2,
+          ),
+        }],
+      };
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          success: true,
+          spec_id: wantedId,
+          spec_path: specPath,
+          source: 'disk',
+          pin,
+          pinned: true,
+          message: `Capture ${wantedId} pinned for /hs-capture (disk-only, no live session; ${pin.tier})`,
+        }, null, 2),
+      }],
+    };
+  }
+
+  // No spec_id → back-compat: create a session row first (pre-existing
+  // behavior, unchanged).
+  const createResult = await createCaptureSessionOnConsole({
+    opened_by: 'agent',
+    opened_by_session: identity.sessionId,
+    mode: 'attended',
+    status: 'pending',
+  });
+
+  if (createResult.ok && createResult.session) {
+    // Session created — pin capture-on-deck + layer-2 metadata to Neon
+    // ([[HS-TASK-CFL2]]; file is the offline fallback).
+    const session = createResult.session;
+    const pin = await writeCaptureFocusVendor(vaultRoot, {
+      specId: session.id,
+      specPath: session.specPath || '',
+      reason: args.reason || 'Pinned via MCP',
+      claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+    });
+
+    if (!pin.pinned) {
+      // The session row WAS created — say so, so the caller does not mint a second
+      // one — but never report it as pinned when nothing readable persisted.
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ...captureFocusPinRefusal(pin, { specId: session.id, specPath: session.specPath || null }),
+            source: 'database',
+            session_created: true,
+            session,
+          }, null, 2),
+        }],
+      };
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          success: true,
+          spec_id: session.id,
+          spec_path: session.specPath || null,
+          source: 'database',
+          session,
+          pin,
+          pinned: true,
+          message: `Capture session ${session.id} created and pinned for /hs-capture (${pin.tier})`,
+        }, null, 2),
+      }],
+    };
+  }
+
+  // Unreachable console → graceful refuse; no local file pin (online-only).
+  const refusal = captureWriteFailure(vaultRoot, args, createResult);
+  return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+}
+
+// Accept HS-CAP-* primarily; HS-IDEA-* still recognized for legacy pins until E2.
+// CAP is family-keyed (dual-read via parseSpecId — accepts HS-CAP-XXXX and
+// HS-XXXX-CAP); IDEA is not reordered, so it stays a type-first prefix check
+// ([[HS-EPIC-DLE3]]).
+export function isCaptureSpecId(id) {
+  const v = String(id ?? '').trim();
+  return parseSpecId(v)?.typeLabel === 'CAP' || /^HS-IDEA-[A-Z0-9]{3,}$/i.test(v);
+}
+
+export function collectOccupiedCaptureIds(vaultRoot) {
+  const scanSpecs = [];
+  for (const [dir, type] of [
+    ['captures', 'capture'],
+    ['ideas', 'capture'], // legacy bucket; still contributes to occupied set
+  ]) {
+    const root = join(vaultRoot, 'specs', dir);
+    if (!existsSync(root)) continue;
+    for (const file of readdirSync(root)) {
+      if (!file.endsWith('.md') || file.endsWith('.review.md')) continue;
+      try {
+        const content = readFileSync(join(root, file), 'utf-8');
+        const { frontmatter } = parseFrontmatter(content);
+        scanSpecs.push({
+          id: String(frontmatter.id ?? ''),
+          basename: file.replace(/\.md$/i, ''),
+          type,
+        });
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return collectOccupiedIdsFromSpecs(scanSpecs).captures;
+}
+
+/**
+ * Cloud-reliant sibling of `collectOccupiedCaptureIds` ([[HS-DJWP-MCPC-TASK]]
+ * "Occupied-id scans" family). `collectOccupiedCaptureIds` stays untouched
+ * (the `diskRead` branch); in `neon` tier this unions `GET
+ * /api/vault/occupied-ids?bucket=captures` and `?bucket=ideas` instead of
+ * `readdirSync`ing `specs/{captures,ideas}`.
+ *
+ * NOTE: as of this task, `collectOccupiedCaptureIds` itself has no caller in
+ * cli.mjs (confirmed by grep — pre-existing dead code, unrelated to this
+ * task). This wrapper is wired and tested so the capability exists the moment
+ * a caller needs it, without leaving a disk-only gap behind.
+ */
+export async function collectOccupiedCaptureIdsViaTier(vaultRoot, { tier, consoleUrl }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => collectOccupiedCaptureIds(vaultRoot),
+    neonRead: async () => {
+      const [capturesRes, ideasRes] = await Promise.all([
+        consoleFetch('/api/vault/occupied-ids?bucket=captures'),
+        consoleFetch('/api/vault/occupied-ids?bucket=ideas'),
+      ]);
+      if (!capturesRes.ok) {
+        throw consoleReadErrorFrom(capturesRes, `GET /api/vault/occupied-ids?bucket=captures returned ${capturesRes.status}: ${capturesRes.error || ''}`, null);
+      }
+      if (!ideasRes.ok) {
+        throw consoleReadErrorFrom(ideasRes, `GET /api/vault/occupied-ids?bucket=ideas returned ${ideasRes.status}: ${ideasRes.error || ''}`, null);
+      }
+      return new Set([
+        ...(Array.isArray(capturesRes.body?.ids) ? capturesRes.body.ids : []),
+        ...(Array.isArray(ideasRes.body?.ids) ? ideasRes.body.ids : []),
+      ]);
+    },
+    routeLabel: 'GET /api/vault/occupied-ids',
+    consoleUrl,
+  });
+}
+
+/**
+ * [[HS-PG9I-TASK]] — pull a text value out of a content_buffer field that may be
+ * either a flattened string OR the structured `{ at, text, confirmed }` object the
+ * PATCH route stores ([[capture-buffer-patches]]). The live console GET returns the
+ * STRUCTURED shape (`coreIdea`/`summary`/`userQuotes`), so resume detection must not
+ * assume the flat keys.
+ */
+export function bufferText(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'object' && value.text) return String(value.text).trim();
+  return '';
+}
+
+/**
+ * [[HS-PG9I-TASK]] — normalize a session content_buffer into { core, summary, notes }
+ * regardless of whether the console returned flat keys (core_idea/notes) or the
+ * structured shape (coreIdea/summary/userQuotes[]). This is what makes the resume
+ * branch fire for a DB-resident capture that already carries a Core Idea.
+ */
+export function normalizeCaptureBuffer(contentBuffer = {}) {
+  const core = bufferText(contentBuffer.core_idea ?? contentBuffer.coreIdea);
+  const summary = bufferText(contentBuffer.summary ?? contentBuffer.concept);
+  let notes = typeof contentBuffer.notes === 'string' ? contentBuffer.notes : '';
+  if (!notes && Array.isArray(contentBuffer.userQuotes)) {
+    notes = contentBuffer.userQuotes
+      .map((q) => `- **${q.at || ''} · you:** "${bufferText(q) || q.text || ''}"`)
+      .join('\n');
+  }
+  return { core, summary, notes };
+}