heyspex 0.2.0 → 0.2.1

package/spexharness/src/rule-table.mjs

@@ -120,7 +120,15 @@ export const BUILT_IN_RULES = Object.freeze(
         "\\b(?:please\\s+)?(?:also\\s+)?(?:add|build|create|implement)\\s+(?:this|that|it)\\s+(?:to|in|into|for)\\b",
         "\\bshould\\s+we\\s+(?:create|build|make|add|have|offer|support|implement|write)\\b",
         "\\bshould\\s+(?:be|become)\\s+(?:a|an)\\s+(?:\\w+[\\s-]+){0,3}?(?:command|feature|setting|option|tool|button|verb|surface|skill|hook|gate)\\b",
-        "\\bfor\\s+all\\s+future\\s+users\\b"
+        "\\bfor\\s+all\\s+future\\s+users\\b",
+        "\\bshould(?:n'?t|\\s+not)?\\s+(?:we|it|this|that|there|they|you)\\s+(?:be|have|also|always|never|just|only)?\\s*(?:\\w+\\s+){0,2}?(?:write|writing|sync|syncing|default|defaulting|use|using|store|storing|read|reading|run|running|do|doing|go|going|work|working|happen|happening|fire|firing|capture|capturing|land|landing|show|showing|open|opening|load|loading|live|living)\\b",
+        "\\bshould\\s+have\\s+(?:\\w+\\s+){0,2}?(?:immediately|automatically|already|just|also)?\\s*\\w+ed\\b",
+        "\\bwhy\\s+(?:did|does|do|is|isn'?t|didn'?t|doesn'?t|wasn'?t|aren'?t|can'?t|won'?t|hasn'?t|haven'?t)\\s+(?:it|this|that|the|we|there|they|these|those)\\b",
+        "\\b(?:it|this|that|there|the\\s+\\w+(?:\\s+\\w+)?)\\s+(?:needs?|ought)\\s+to\\s+(?:be|have|get|also|always)\\b",
+        "\\bfix\\s+all\\s+(?:of\\s+)?(?:this|that|these|those|it|them)\\b",
+        "\\b(?:significant|major|serious|real|big|total|complete|repeated|constant|ongoing)\\s+(?:breakdowns?|failures?|gaps?|problems?|regressions?|holes?)\\s+(?:with|in|around|across)\\b",
+        "\\b\\w+s?\\s+(?:aren'?t|isn'?t|are\\s+not|is\\s+not|never|don'?t\\s+get|doesn'?t\\s+get|stopped)\\s+(?:being\\s+|getting\\s+)?\\w+(?:ed|ing)\\b",
+        "\\bthere\\s+should\\s+be\\s+(?:a|an|some)\\b"
       ],
       "inject": "This message contains a RAW IDEA / suggestion worth capturing — capture it even if it is ALSO a work order, question, or bug report (both can be true). Per the owner's standing wish, the system CAPTURES ideas autonomously — the owner built the skills and cannot remember them all, so do NOT wait to be told to run /hs-capture.\n\n{{CONFIRM_MODE}}\n\nFIRST, pick the TRACK — never whether to capture. Skipping capture is the USER's call alone (they say \"discard\", \"skip\", or \"no, just do it\"); you never self-exempt, and \"this is actually a command / work order / bug report\" is NOT a reason to skip (owner ruling 2026-07-12):\n  - CAPTURE CONTINUATION (check this FIRST — owner ruling 2026-07-12): a capture from THIS conversation is sitting at the promote/iterate choice, and this prose follows on from that idea (more detail, a refinement, a related want — even when phrased as a work order like \"please add …\", and even though the user never says \"iterate\"). That prose IS the iterate move on the SAME capture: call `heyspex_update_capture` with `spec_id` = that capture's exact id (NEVER `heyspex_active_capture({})`, which can mint a fresh capture), append the verbatim `user_quote`, re-ground into `agent_expansion`, and re-present promote/iterate. Do NOT create a new capture; do NOT implement anything.\n  - ACTIONABLE (also a command, work order, or bug report to fix now, where the work is something OTHER than building the captured idea itself): announce in ONE line — Capturing this as an idea per your standing capture flow — say \"discard\" if you'd rather I skip it. — run capture steps 1-3 below, then IMMEDIATELY proceed with the requested work. The capture never blocks, replaces, or delays the task; skip step 4's promote/iterate ask and just do the work (the capture stays parked for later). HARD LIMIT (owner ruling 2026-07-12; bypass retired 2026-08-11): when the requested work IS the captured idea (build/add/implement the thing you just captured), this track does NOT apply — a captured idea is never implemented straight from a capture. Its only road to code is promote-to-research, then `/hs-promote <research-id>` + `/hs-next <resulting-id> [front]` — milestone/epic/task filing is never skipped; front mode (handheld/assisted/autonomous) controls supervision, not whether that filing happens (research-capture-protocol §\"From research to code — always through milestone/epic/task (no bypass)\").\n  - PURE IDEA (nothing to execute right now): run the full capture flow, steps 1-4.\n  Sole exception (no capture): a bare continuation carrying NO new idea content — \"yes\", \"proceed\", a direct answer to a question you just asked.\nDEFER OPTION (owner ruling 2026-07-12): when filing the capture in-line would get in the way of operations — the capture endpoint is failing/buffering, the message is a time-critical work order, or the user is mid-operation — you may DEFER the capture write to session close-out instead of doing it now. Announce it in the same one line (\"deferring capture to close-out\"), keep the user's VERBATIM words safe in session state, and at closing procedures append those exact quotes to the related capture doc that already exists (explicit spec_id) — or file the deferred new capture — alongside memory filing (session-close-protocol step 7). Defer ≠ skip: the words MUST land in the vault at close; skipping capture remains the USER's call alone.\nCapture flow:\n  1. OPEN — call `heyspex_active_capture({})` (call `heyspex_load_tools` first if the capture tools aren't loaded). It attaches to the on-deck capture or auto-creates a fresh HS-CAP-*.\n  2. CAPTURE (beat 1) — call `heyspex_update_capture` with `user_quote` = the user's VERBATIM words; if Core Idea is empty, also pass `core_idea` + `summary` in the same call. Never alter the user's words.\n  3. GROUND = EXPAND (beat 2) — do peer-level grounding as a technical co-founder and write it to `agent_expansion` in the same pass, automatically (no confirm).\n  4. Then present exactly two moves: promote to research (the only real exit) or iterate. Follow the /hs-capture beats exactly; promote is always confirm-required.\n\nIf the user declines / says discard: STOP the flow and leave the capture as an unpromoted raw note (they can delete it later). Do not promote, do not file epics/tasks/plans.\n\nHard rules (capture-guardrails): user words stay verbatim; promote-to-research (or promote-to-diagnose for `kind: bug-fix`) is the ONLY exit — never offer to file epics/tasks/plans; never commit or push.\n(Mute: HEYSPEX_CAPTURE_TRIGGER_OFF=1, or set agent_behaviors.capture_on_idea.enabled: false in .heyspex/config.yaml.)\n",
       "naming": null
@@ -250,6 +258,28 @@ export const BUILT_IN_RULES = Object.freeze(
       "inject": "Destructive git activity on this working tree is WITNESSED independently of every\nother gate (protected-shared-actions-gate): git state is snapshotted at session start\nto a session-scoped file under `.heyspex/git-reflog-audit/`, and diffed at session\nclose. Any growth in `git stash list`, and any HEAD reflog entry newer than the\nsnapshot whose action is reset / checkout / rebase, is named in one warn row in\n`.heyspex/guardrail-history.jsonl`. Ordinary commits are not flagged. This never\nblocks anything — it exists so an action that slipped past every other control still\nleaves a record that does not depend on the acting agent's honesty. If the witness\nfires, say so in the hand-off rather than letting it go unmentioned.\n",
       "naming": null
     },
+    {
+      "rule": "handoff-intent",
+      "sourceProtocol": "handoff-intent-protocol",
+      "severity": "prime",
+      "surfaces": [
+        "userpromptsubmit"
+      ],
+      "configKey": "agent_behaviors.handoff_intent.enabled",
+      "ignoreInjectedContent": true,
+      "patterns": [
+        "\\bhand[\\s-]?off\\s+(?:prompt|doc|document|notes?|message|brief|context|summary|instructions?)\\b",
+        "\\bhand[\\s-]?off\\b[^.?!]{0,40}\\b(?:next|new|another)\\s+(?:agent|session|window|claude)\\b",
+        "\\bhand\\s+(?:this|it|things?|the\\s+work)\\s+off\\b",
+        "\\b(?:for|to)\\s+(?:the\\s+)?next\\s+(?:agent|session)\\b",
+        "\\bresume\\s+(?:prompt|context|instructions?)\\b",
+        "\\bnext[\\s-]session\\s+(?:prompt|notes?|handoff|hand-off)\\b",
+        "\\bwhat\\s+(?:should|does|do)\\s+the\\s+next\\s+(?:agent|session)\\b",
+        "\\bpick\\s+(?:this|it)\\s+up\\s+(?:in|with)\\s+a\\s+(?:new|fresh|another)\\s+(?:session|window|agent)\\b"
+      ],
+      "inject": "HANDOFF REQUEST - HeySpex has an owner-locked hand-off contract; never write a freehand hand-off prompt or doc. Run the /hs-handoff CREATE flow now (.claude/commands/hs-handoff.md): 1) close out first - heyspex_record_wip per worked epic, change-log rows / HS-REV at the review grain, heyspex_release_spec on open claims, hs export-events (skip what is already current); 2) `hs handoff record --new-code --spec <next-target> --phase \"<label>\" --link <worked ids> --blocker \"<open items, one line>\"` - the code is MINTED, never invented; 3) hand the human BOTH `/hs-handoff <CODE>` and `cd C:\\dev-projects\\heyspex-specs && claude \"/hs-next <next-spec-id>\"`; 4) the session is not over - the human decides. (Mute: HEYSPEX_HANDOFF_INTENT_OFF=1 or agent_behaviors.handoff_intent.enabled: false.)\n",
+      "naming": null
+    },
     {
       "rule": "id-display-shape-gate",
       "sourceProtocol": "communication-style-protocol",

package/vendor/heyspex-mcp/account-switch.mjs

@@ -20,6 +20,7 @@
 //
 // Plain Node ESM, zero dependencies. Never logs token material.
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -27,7 +28,7 @@ import { dirname, join } from 'node:path';
 import { assertNotRealHomeUnderTest, removeAccount, setCurrentAccount } from './credentials.mjs';
 
 /** `~/.heyspex/registry.json` for `homeDir`. */
-export function registryFilePath(homeDir = homedir()) {
+export function registryFilePath(homeDir = heyspexHome()) {
   return join(homeDir, '.heyspex', 'registry.json');
 }
 
@@ -36,7 +37,7 @@ export function registryFilePath(homeDir = homedir()) {
  * @param {{ homeDir?: string, accountId: string | null }} input
  * @returns {{ status: 'updated' | 'unchanged' | 'absent' | 'v1' | 'unreadable', path: string }}
  */
-export function setRegistryCurrentAccount({ homeDir = homedir(), accountId }) {
+export function setRegistryCurrentAccount({ homeDir = heyspexHome(), accountId }) {
   const path = registryFilePath(homeDir);
   if (!existsSync(path)) return { status: 'absent', path };
   let json;
@@ -64,7 +65,7 @@ export function setRegistryCurrentAccount({ homeDir = homedir(), accountId }) {
  * the registry is touched only after the credentials half succeeded.
  * @param {{ homeDir?: string, accountId: string }} input
  */
-export function switchCurrentAccount({ homeDir = homedir(), accountId }) {
+export function switchCurrentAccount({ homeDir = heyspexHome(), accountId }) {
   const credentialsPath = setCurrentAccount({ homeDir, accountId });
   const registry = setRegistryCurrentAccount({ homeDir, accountId });
   return { accountId, credentialsPath, registry };
@@ -76,7 +77,7 @@ export function switchCurrentAccount({ homeDir = homedir(), accountId }) {
  * account leaves the registry alone.
  * @param {{ homeDir?: string, accountId?: string | null }} [input]
  */
-export function signOutAccount({ homeDir = homedir(), accountId = null } = {}) {
+export function signOutAccount({ homeDir = heyspexHome(), accountId = null } = {}) {
   const result = removeAccount({ homeDir, accountId });
   const registry =
     result.removed && result.wasCurrent
@@ -90,6 +91,6 @@ export function signOutAccount({ homeDir = homedir(), accountId = null } = {}) {
  * store, carry the registry's pointer along with it.
  * @param {{ homeDir?: string, accountId: string }} input
  */
-export function followCurrentAccountInRegistry({ homeDir = homedir(), accountId }) {
+export function followCurrentAccountInRegistry({ homeDir = heyspexHome(), accountId }) {
   return setRegistryCurrentAccount({ homeDir, accountId });
 }

package/vendor/heyspex-mcp/capture-buffer-patches.mjs

@@ -36,6 +36,8 @@
  * confirm in the /hs-capture four-beat protocol.
  */
 
+import { buildSourcesPatches, normalizeCaptureSources } from './capture-sources.mjs';
+
 /** Keep only well-formed `{ at, text }` quote entries from a prior buffer. */
 function priorUserQuotes(currentBuffer) {
   const raw = currentBuffer?.userQuotes ?? currentBuffer?.user_quotes;
@@ -86,6 +88,17 @@ function collapse(value) {
   return String(value).trim().replace(/\n+/g, ' ');
 }
 
+/**
+ * A user's quote is stored STRICTLY VERBATIM ([[HS-TGHU-ST07-TASK-store-and-render-capture-quotes]],
+ * owner 2026-10-10: "always verbatim words in notes"): no trim, no newline
+ * flattening, no whitespace collapsing. Only CRLF/CR are normalized to LF.
+ * A whitespace-only quote is dropped (nothing was said).
+ */
+function verbatimQuote(value) {
+  const raw = String(value).replace(/\r\n?/g, '\n');
+  return raw.trim() ? raw : '';
+}
+
 /**
  * @param {object} args - { user_quote, agent_note, core_idea, summary (alias: concept), agent_expansion, example, user_stories, kind, done_when, jtbd }
  * @param {object} currentBuffer - the session's existing content_buffer (may be {})
@@ -95,9 +108,17 @@ function collapse(value) {
 export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
   const patches = [];
 
-  if (args.user_quote !== undefined && collapse(args.user_quote)) {
-    const next = [...priorUserQuotes(currentBuffer), { at: iso, text: collapse(args.user_quote) }];
-    patches.push({ path: 'userQuotes', value: next });
+  if (args.user_quote !== undefined && verbatimQuote(args.user_quote)) {
+    const entry = { at: iso, text: verbatimQuote(args.user_quote) };
+    // op 'append' + items: a current console appends under its row lock (no
+    // stale read-modify-write); an older console ignores both and stores the
+    // full prior-plus-new value.
+    patches.push({
+      path: 'userQuotes',
+      value: [...priorUserQuotes(currentBuffer), entry],
+      op: 'append',
+      items: [entry],
+    });
   }
 
   if (args.agent_note !== undefined && collapse(args.agent_note)) {
@@ -184,5 +205,12 @@ export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
     });
   }
 
+  // sources: links + original files saved with the capture (HS-9K12). The
+  // handler pre-validates via normalizeCaptureSources; an invalid bag emits nothing.
+  if (args.sources !== undefined) {
+    const normalized = normalizeCaptureSources(args.sources, iso);
+    if (normalized.ok) patches.push(...buildSourcesPatches(normalized, currentBuffer));
+  }
+
   return patches;
 }

package/vendor/heyspex-mcp/capture-console-client.mjs

@@ -173,9 +173,14 @@ export function describeCaptureWriteFailure(failure) {
         `The console answered — it is not down. This write was NOT saved and will NOT retry automatically; fix the request and send it again.`,
     };
   }
+  // [[HS-K27H]] decided a 5xx was NOT stashed because the OLD code reported
+  // server errors as "can't reach the server". The sin was that false
+  // connectivity claim, not the buffering: degrade-don't-die buffers the user's
+  // words on a 5xx too, but the message says truthfully that the console
+  // ANSWERED with an error (see respondToCaptureWriteFailure).
   return {
     kind: "server",
-    shouldStash: false,
+    shouldStash: true,
     error: CAPTURE_ERROR_FAILED,
     http_status: status,
     server_error_code: serverCode,
@@ -198,7 +203,7 @@ export function describeCaptureWriteFailure(failure) {
  *   (AC4) — the drain path replays every OUTBOX_KINDS field in canonical
  *   structured shape.
  * - 4xx → `status: "refused"` + the server's error/message verbatim (AC2/AC5).
- * - 5xx → `status: "failed"` + the server's message verbatim (AC3/AC5).
+ * - 5xx → stash too, `status: "failed_buffered"`, `buffered: true`, truthful "console answered <status>" message (not "unreachable"); `status: "failed"` only when there was nothing to stash.
  * - sign-in (`authProblem` on a status-0 result, or an answered 401) →
  *   `status: "blocked"`, `buffered: false`, `action` = the sign-in command in
  *   the form this machine can run (`hs login`, or `node "<abs>/bin/hs.mjs" login`),
@@ -206,6 +211,17 @@ export function describeCaptureWriteFailure(failure) {
  *   that says plainly the words were NOT saved ([[HS-9R6S-N8VP-DIAG]]).
  */
 export function respondToCaptureWriteFailure(vaultRoot, args, failure) {
+  const payload = respondToCaptureWriteFailureInner(vaultRoot, args, failure);
+  // sources (original files / links) are NOT stashed offline: say so honestly
+  // instead of letting the "your words are saved" message imply they were.
+  if (Array.isArray(args?.sources) && args.sources.length > 0) {
+    payload.sources_not_saved = true;
+    payload.message = `${payload.message} NOTE: the sources you attached were NOT saved offline. Re-send them with heyspex_update_capture once the console is reachable.`;
+  }
+  return payload;
+}
+
+function respondToCaptureWriteFailureInner(vaultRoot, args, failure) {
   const d = describeCaptureWriteFailure(failure);
   if (d.kind === "transport") {
     const stashed = stashCaptureArgs(vaultRoot, args || {});
@@ -240,6 +256,25 @@ export function respondToCaptureWriteFailure(vaultRoot, args, failure) {
       message: `This capture was not filed, and your words were not buffered. ${d.message}`,
     };
   }
+  if (d.kind === "server") {
+    const stashed = stashCaptureArgs(vaultRoot, args || {});
+    if (stashed.length > 0) {
+      return {
+        ok: false,
+        status: "failed_buffered",
+        error: d.error,
+        http_status: d.http_status,
+        server_error: d.server_error_code,
+        console_error: d.server_message ?? d.server_error_code,
+        buffered: true,
+        source: "offline-buffer",
+        message:
+          `The console answered ${d.http_status} applying the write; your words are buffered locally in .heyspex/capture-outbox and will be replayed on the next successful capture call.`,
+        stashed: stashed.map((s) => ({ kind: s.kind })),
+        pending_sync: outboxCount(vaultRoot),
+      };
+    }
+  }
   return {
     ok: false,
     status: d.kind === "client" ? "refused" : "failed",

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

@@ -851,10 +851,23 @@ export function validateSummaryLength(summary) {
 /** @deprecated renamed to validateSummaryLength (HS-EPIC-OED2). */
 export const validateConceptLength = validateSummaryLength;
 
+/**
+ * Strictly verbatim note entry (HS-TGHU). MUST match the console's
+ * formatUserNoteEntry (capture-vault.ts): a plain one-line quote keeps the
+ * legacy one-line form; anything with newlines or edge whitespace renders as a
+ * per-line "  > " blockquote. Only CRLF/CR become LF.
+ */
 export function formatUserNoteEntry(iso, role, text) {
-  const clean = text.trim().replace(/\n+/g, ' ');
+  const raw = String(text).replace(/\r\n?/g, '\n');
   const label = role === 'user' ? 'you' : role;
-  return `- **${iso} · ${label}:** "${clean}"`;
+  if (!raw.includes('\n') && raw === raw.trim()) {
+    return `- **${iso} · ${label}:** "${raw}"`;
+  }
+  const quoted = raw
+    .split('\n')
+    .map((line) => (line === '' ? '  >' : `  > ${line}`))
+    .join('\n');
+  return `- **${iso} · ${label}:**\n${quoted}`;
 }
 
 export function appendCaptureNote(existingNotes, entry) {
@@ -1295,6 +1308,7 @@ export const UPDATE_CAPTURE_ACCEPTED_ARGS = [
   'kind',
   'done_when',
   'jtbd',
+  'sources',
 ];
 
 /**
@@ -1397,6 +1411,16 @@ export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, dep
  * for every rejection.
  */
 function computeCaptureUpdate(frontmatter, body, args = {}) {
+  // sources (links / original files) live in the capture session's content_buffer
+  // (console API path). This spec-file path has nowhere to put them, so refuse BY
+  // NAME rather than silently dropping them (additionalproperties-false-in-an-mcp).
+  if (Array.isArray(args.sources) && args.sources.length > 0) {
+    return {
+      error: 'SOURCES_UNSUPPORTED_ON_SPEC_FILE_PATH',
+      message:
+        'heyspex_update_capture `sources` is only supported through the console capture-session path. NOTHING WAS WRITTEN. Retry against a reachable console.',
+    };
+  }
   // `summary` is the canonical input; `concept` is the deprecated alias (HS-EPIC-OED2).
   const summaryArg = args.summary ?? args.concept;
 

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

@@ -89,7 +89,9 @@ export function stashCaptureArgs(vaultRoot, args = {}) {
   for (const kind of OUTBOX_KINDS) {
     const raw = args[kind];
     if (raw !== undefined && String(raw).trim()) {
-      entries.push({ kind, text: String(raw).trim() });
+      // user_quote is stashed verbatim (no trim) so an offline replay keeps the
+      // exact words (HS-TGHU).
+      entries.push({ kind, text: kind === 'user_quote' ? String(raw) : String(raw).trim() });
     }
   }
   if (entries.length === 0) return [];
@@ -122,7 +124,10 @@ export function listOutbox(vaultRoot) {
       const kind = m ? m[1] : 'user_quote';
       let text = '';
       try {
-        text = readFileSync(join(dir, f), 'utf8').replace(/\n+$/, '');
+        // stash writes text + one newline: strip exactly that one so a verbatim
+        // quote's own trailing whitespace survives the round trip.
+        text = readFileSync(join(dir, f), 'utf8').replace(/\n$/, '');
+        if (kind !== 'user_quote') text = text.replace(/\n+$/, '');
       } catch {
         /* skip unreadable */
       }
@@ -235,8 +240,9 @@ export function quarantineCount(vaultRoot) {
  * @returns {{path: string, value: unknown} | null}
  */
 export function outboxEntryToPatch(entry, iso, currentBuffer = {}) {
-  const text = String(entry.text ?? '').trim();
-  if (!text) return null;
+  const text =
+    entry.kind === 'user_quote' ? String(entry.text ?? '') : String(entry.text ?? '').trim();
+  if (!text.trim()) return null;
   if (!OUTBOX_KINDS.includes(entry.kind)) return null;
   const patches = buildCaptureBufferPatches({ [entry.kind]: text }, currentBuffer, iso);
   return patches[0] ?? null;

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

@@ -0,0 +1,195 @@
+/**
+ * `sources` argument of `heyspex_update_capture`: links, original text
+ * documents and binary files saved WITH a capture
+ * ([[HS-9K12-ST07-TASK-heyspex-update-capture-sources-argument]], epic
+ * [[HS-WF23-ST07-EPIC-verbatim-words-and-source-files]]; owner 2026-10-10:
+ * "files/original docs etc saved as source").
+ *
+ * Entry forms (exactly one content key per entry):
+ *   { url, title? }                              -> link source (`## Source Material`, grain link)
+ *   { name, text, mime?, origin? }               -> original TEXT document, stored byte-for-byte
+ *   { name, content_base64, mime?, origin? }     -> binary file
+ *   { path, name?, mime? }                       -> the MCP reads the file at `path` itself (so the
+ *                                                  agent never has to pass the content through its context)
+ *
+ * Caps mirror the console (`spex-console/src/lib/capture-source-files.ts`),
+ * which re-validates server-side: 256 KiB per file, 1 MiB total, 20 files.
+ * Oversize / malformed entries are REFUSED by name; nothing is truncated.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+
+export const SOURCE_FILE_MAX_BYTES = 256 * 1024;
+export const SOURCE_FILES_MAX_TOTAL_BYTES = 1024 * 1024;
+export const SOURCE_FILES_MAX_COUNT = 20;
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/** Reduce a name to one safe path segment (mirrors the console). */
+export function sanitizeSourceFileName(raw) {
+  const segs = String(raw).split(/[\\/]/);
+  // eslint-disable-next-line no-control-regex
+  return (segs[segs.length - 1] ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 200);
+}
+
+function defaultMime(name, encoding) {
+  if (encoding === 'base64') return 'application/octet-stream';
+  return /\.(md|markdown)$/i.test(name) ? 'text/markdown' : 'text/plain';
+}
+
+function fileFromBuffer(buf, { name, mime, origin, iso, encoding, content }) {
+  if (buf.length === 0) return { error: `source "${name}" is empty` };
+  if (buf.length > SOURCE_FILE_MAX_BYTES) {
+    return {
+      error: `source "${name}" is ${buf.length} bytes; the inline source-file cap is ${SOURCE_FILE_MAX_BYTES} bytes. Attach a smaller file or link it by url.`,
+    };
+  }
+  return {
+    file: {
+      name,
+      mime: mime || defaultMime(name, encoding),
+      bytes: buf.length,
+      sha256: createHash('sha256').update(buf).digest('hex'),
+      at: iso,
+      encoding,
+      content,
+      ...(origin ? { origin } : {}),
+    },
+  };
+}
+
+/** Decode bytes as UTF-8 text only when that is lossless; otherwise treat as binary. */
+function bufferToStored(buf) {
+  if (!buf.includes(0)) {
+    const text = buf.toString('utf8');
+    if (Buffer.from(text, 'utf8').equals(buf)) return { encoding: 'utf8', content: text };
+  }
+  return { encoding: 'base64', content: buf.toString('base64') };
+}
+
+/**
+ * Validate + normalize the `sources` argument.
+ * @returns {{ ok: true, links: object[], files: object[] } | { ok: false, error: object }}
+ */
+export function normalizeCaptureSources(sources, iso, deps = {}) {
+  const read = deps.readFile ?? ((p) => readFileSync(p));
+  const size = deps.fileSize ?? ((p) => statSync(p).size);
+  const refuse = (message, index) => ({
+    ok: false,
+    error: {
+      error: 'INVALID_SOURCES',
+      message: `${message} NOTHING WAS WRITTEN.`,
+      field: `sources[${index}]`,
+    },
+  });
+  if (!Array.isArray(sources)) return refuse('sources must be an array.', 0);
+  if (sources.length > SOURCE_FILES_MAX_COUNT) {
+    return refuse(`sources cannot exceed ${SOURCE_FILES_MAX_COUNT} entries.`, 0);
+  }
+  const links = [];
+  const files = [];
+  let total = 0;
+  for (let i = 0; i < sources.length; i += 1) {
+    const s = sources[i];
+    if (!s || typeof s !== 'object') return refuse(`sources[${i}] must be an object.`, i);
+    if (typeof s.url === 'string' && s.url.trim()) {
+      if (!/^https?:\/\//i.test(s.url.trim())) {
+        return refuse(`sources[${i}].url must be an http(s) URL.`, i);
+      }
+      links.push({
+        url: s.url.trim(),
+        ...(typeof s.title === 'string' && s.title.trim() ? { title: s.title.trim() } : {}),
+        added_at: iso,
+        grain: 'link',
+      });
+      continue;
+    }
+    let name = typeof s.name === 'string' ? sanitizeSourceFileName(s.name) : '';
+    const mime = typeof s.mime === 'string' && s.mime.trim() ? s.mime.trim().slice(0, 100) : '';
+    const origin =
+      typeof s.origin === 'string' && s.origin.trim() ? s.origin.trim().slice(0, 500) : '';
+    let r;
+    if (typeof s.path === 'string' && s.path.trim()) {
+      const p = s.path.trim();
+      let sz;
+      try {
+        sz = size(p);
+      } catch (e) {
+        return refuse(`sources[${i}].path could not be read (${e.code || e.message}).`, i);
+      }
+      if (sz > SOURCE_FILE_MAX_BYTES) {
+        return refuse(
+          `sources[${i}] (${basename(p)}) is ${sz} bytes; the inline source-file cap is ${SOURCE_FILE_MAX_BYTES} bytes.`,
+          i,
+        );
+      }
+      let buf;
+      try {
+        buf = read(p);
+      } catch (e) {
+        return refuse(`sources[${i}].path could not be read (${e.code || e.message}).`, i);
+      }
+      name = name || sanitizeSourceFileName(basename(p));
+      if (!name) return refuse(`sources[${i}] needs a name.`, i);
+      r = fileFromBuffer(buf, { name, mime, origin: origin || p, iso, ...bufferToStored(buf) });
+    } else if (typeof s.text === 'string') {
+      if (!name) return refuse(`sources[${i}].name is required for a text document.`, i);
+      r = fileFromBuffer(Buffer.from(s.text, 'utf8'), {
+        name,
+        mime,
+        origin,
+        iso,
+        encoding: 'utf8',
+        content: s.text,
+      });
+    } else if (typeof s.content_base64 === 'string') {
+      if (!name) return refuse(`sources[${i}].name is required for a binary file.`, i);
+      const b64 = s.content_base64.replace(/\s+/g, '');
+      if (b64.length % 4 !== 0 || !BASE64_RE.test(b64)) {
+        return refuse(`sources[${i}].content_base64 is not valid base64.`, i);
+      }
+      r = fileFromBuffer(Buffer.from(b64, 'base64'), {
+        name,
+        mime,
+        origin,
+        iso,
+        encoding: 'base64',
+        content: b64,
+      });
+    } else {
+      return refuse(`sources[${i}] needs one of url, path, text (+name) or content_base64 (+name).`, i);
+    }
+    if (r.error) return refuse(r.error, i);
+    total += r.file.bytes;
+    files.push(r.file);
+  }
+  if (total > SOURCE_FILES_MAX_TOTAL_BYTES) {
+    return refuse(
+      `sources total ${total} bytes exceeds the ${SOURCE_FILES_MAX_TOTAL_BYTES} byte per-capture cap.`,
+      0,
+    );
+  }
+  return { ok: true, links, files };
+}
+
+/** Patches for validated sources: prior-plus-new full array (old consoles) + append hint (new consoles). */
+export function buildSourcesPatches(normalized, currentBuffer = {}) {
+  const patches = [];
+  if (normalized.files.length > 0) {
+    const prior = Array.isArray(currentBuffer?.sourceFiles) ? currentBuffer.sourceFiles : [];
+    const fresh = normalized.files.filter(
+      (f) => !prior.some((p) => p && p.name === f.name && p.sha256 === f.sha256),
+    );
+    if (fresh.length > 0) {
+      patches.push({ path: 'sourceFiles', value: [...prior, ...fresh], op: 'append', items: fresh });
+    }
+  }
+  if (normalized.links.length > 0) {
+    const prior = Array.isArray(currentBuffer?.sources) ? currentBuffer.sources : [];
+    const fresh = normalized.links.filter((l) => !prior.some((p) => p && p.url === l.url));
+    if (fresh.length > 0) {
+      patches.push({ path: 'sources', value: [...prior, ...fresh], op: 'append', items: fresh });
+    }
+  }
+  return patches;
+}

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

@@ -8,18 +8,19 @@
 // ─────────────────────────────────────────────────────────────────────────────
 
 import { parseSpecId, shortLookupIdOf } from './spec-id-lib.mjs';
-import { readViaSelector, resolveReadTier, resolveVaultWriteMode } from './read-path.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, computeCaptureSufficiency, extractCaptureCoreFromBody, extractCaptureNotesFromBody, findCaptureSpecFile, loadCaptureFocusOffline, resolveActiveCapture, updateCaptureArgsVerdict, writeCaptureFocus } from './capture-focus.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';
 
 /**
@@ -574,19 +575,51 @@ export function captureSpecIdFromPath(specPath) {
  * @param {string|null|undefined} specPath
  * @returns {{ sufficiency: object|null, sufficiency_reason?: string }}
  */
-function sufficiencyForSpecPath(vaultRoot, specPath) {
+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 { sufficiency: null, sufficiency_reason: 'not_yet_materialized' };
+    return fromBuffer() ?? { sufficiency: null, sufficiency_reason: 'not_yet_materialized' };
   }
   try {
     const spec = loadSpec(vaultRoot, specPath);
-    if (!spec) return { sufficiency: null, sufficiency_reason: 'spec_unreadable' };
+    if (!spec) return fromBuffer() ?? { sufficiency: null, sufficiency_reason: 'spec_unreadable' };
     return { sufficiency: computeCaptureSufficiency(spec.frontmatter, spec.body) };
   } catch {
-    return { sufficiency: null, sufficiency_reason: 'scorer_error' };
+    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
@@ -628,7 +661,7 @@ export async function handleActiveCapture(vaultRoot, args) {
         source: rehydrated.rehydrated_from_disk ? 'database+disk-rehydrated' : 'database',
         is_new: rehydrated.is_new,
         session,
-        ...sufficiencyForSpecPath(vaultRoot, session.specPath),
+        ...sufficiencyForSpecPath(vaultRoot, session.specPath, session),
       };
       if (!rehydrated.is_new) {
         payload.guidance =
@@ -767,7 +800,7 @@ export async function handleActiveCapture(vaultRoot, args) {
     is_new: rehydrated.is_new,
     session,
     synced_from_offline_buffer: drain.drained || undefined,
-    ...sufficiencyForSpecPath(vaultRoot, session.specPath),
+    ...sufficiencyForSpecPath(vaultRoot, session.specPath, session),
   };
   if (!rehydrated.is_new) {
     payload.guidance =
@@ -823,6 +856,17 @@ export async function handleUpdateCapture(vaultRoot, args) {
     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.
@@ -918,7 +962,7 @@ export async function handleUpdateCapture(vaultRoot, args) {
     session: patchResult.session,
     materialization: patchResult.materialization || null,
     message: 'Capture session updated via API. Materialization handled server-side.',
-    ...sufficiencyForSpecPath(vaultRoot, patchResult.session?.specPath),
+    ...sufficiencyForSpecPath(vaultRoot, patchResult.session?.specPath, patchResult.session),
   };
 
   // Agent-originated captures never auto-open a browser window (companion /
@@ -1163,6 +1207,7 @@ export function collectOccupiedCaptureIds(vaultRoot) {
  */
 export async function collectOccupiedCaptureIdsViaTier(vaultRoot, { tier, consoleUrl }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => collectOccupiedCaptureIds(vaultRoot),
     neonRead: async () => {
@@ -1171,10 +1216,10 @@ export async function collectOccupiedCaptureIdsViaTier(vaultRoot, { tier, consol
         consoleFetch('/api/vault/occupied-ids?bucket=ideas'),
       ]);
       if (!capturesRes.ok) {
-        throw new Error(`GET /api/vault/occupied-ids?bucket=captures returned ${capturesRes.status}: ${capturesRes.error || ''}`);
+        throw consoleReadErrorFrom(capturesRes, `GET /api/vault/occupied-ids?bucket=captures returned ${capturesRes.status}: ${capturesRes.error || ''}`, null);
       }
       if (!ideasRes.ok) {
-        throw new Error(`GET /api/vault/occupied-ids?bucket=ideas returned ${ideasRes.status}: ${ideasRes.error || ''}`);
+        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 : []),