heyspex 0.1.0 → 0.2.1

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

@@ -24,12 +24,20 @@
  *  2. **Append, not overwrite.** The console PATCH route stores top-level keys
  *     verbatim (last-write-wins), so multi-beat `user_quote` calls would clobber
  *     each other. We read the prior buffer and append, sending the full array.
+ *     The same rule applies to the five single-object timestamped sections
+ *     (`details`/`example`/`userStories`/`doneWhen`/`jtbd`): a second call on
+ *     the same field combines onto the prior call's text (blank-line joined)
+ *     instead of replacing it — [[HS-OSCT-77P9-DIAG-heyspex-update-capture-overwrites-agent]].
+ *     `coreIdea`/`summary` are deliberately NOT combined — a capture's core
+ *     idea/summary is its current best statement, not an accumulating log.
  *
  * `confirmed: true` is set on every agent-authored section because the MCP write
  * is an explicit commit — the agent only calls this after the conversational
  * 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;
@@ -48,10 +56,49 @@ function priorChatTurns(currentBuffer) {
   );
 }
 
+/**
+ * Read the prior confirmed text for a single-object timestamped section
+ * (`details`/`example`/`userStories`/`doneWhen`/`jtbd`) so a second
+ * `heyspex_update_capture` call can accumulate onto it instead of
+ * overwriting it ([[HS-OSCT-77P9-DIAG-heyspex-update-capture-overwrites-agent]]).
+ * The console PATCH route stores whatever this module sends verbatim
+ * (last-write-wins on the whole key), so accumulation has to happen here,
+ * on the read-before-write side — the same reason userQuotes/chatTurns
+ * already read the prior buffer before building their new array value.
+ */
+function priorTimestampedText(currentBuffer, key) {
+  const raw = currentBuffer?.[key];
+  if (raw && typeof raw === 'object' && !Array.isArray(raw) && typeof raw.text === 'string') {
+    return raw.text.trim();
+  }
+  return '';
+}
+
+/**
+ * Combine a prior section's text with a new call's text so neither call's
+ * content is lost — joined with a blank line so the materialized section
+ * reads as separate paragraphs, not run together.
+ */
+function combineTimestampedText(currentBuffer, key, nextText) {
+  const prior = priorTimestampedText(currentBuffer, key);
+  return prior ? `${prior}\n\n${nextText}` : nextText;
+}
+
 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 {})
@@ -61,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)) {
@@ -85,13 +140,17 @@ export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
   }
 
   // agent_expansion is the `## Expanded Concept` deep-dive section → buffer.details.
+  // Accumulates onto the prior call's text (HS-OSCT) instead of replacing it.
   if (args.agent_expansion !== undefined && String(args.agent_expansion).trim()) {
-    patches.push({ path: 'details', value: { at: iso, text: String(args.agent_expansion).trim(), confirmed: true } });
+    const text = combineTimestampedText(currentBuffer, 'details', String(args.agent_expansion).trim());
+    patches.push({ path: 'details', value: { at: iso, text, confirmed: true } });
   }
 
   // example is the `## Example` section (real or AI-illustrative) → buffer.example.
+  // Accumulates onto the prior call's text (HS-OSCT) instead of replacing it.
   if (args.example !== undefined && String(args.example).trim()) {
-    patches.push({ path: 'example', value: { at: iso, text: String(args.example).trim(), confirmed: true } });
+    const text = combineTimestampedText(currentBuffer, 'example', String(args.example).trim());
+    patches.push({ path: 'example', value: { at: iso, text, confirmed: true } });
   }
 
   // user_stories is the `## User Stories` section → buffer.userStories. Root cause
@@ -100,9 +159,10 @@ export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
   // console content_buffer (and therefore the materialized file) never saw it —
   // silent data loss, unlike example which has always had this push.
   if (args.user_stories !== undefined && String(args.user_stories).trim()) {
+    const text = combineTimestampedText(currentBuffer, 'userStories', String(args.user_stories).trim());
     patches.push({
       path: 'userStories',
-      value: { at: iso, text: String(args.user_stories).trim(), confirmed: true },
+      value: { at: iso, text, confirmed: true },
     });
   }
 
@@ -122,9 +182,10 @@ export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
   // {at,text,confirmed} shape as the other agent-authored sections (example,
   // user_stories, details) — sibling half of the HS-NR43 fix above.
   if (args.done_when !== undefined && String(args.done_when).trim()) {
+    const text = combineTimestampedText(currentBuffer, 'doneWhen', String(args.done_when).trim());
     patches.push({
       path: 'doneWhen',
-      value: { at: iso, text: String(args.done_when).trim(), confirmed: true },
+      value: { at: iso, text, confirmed: true },
     });
   }
 
@@ -137,11 +198,19 @@ export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
   // is refused by name at the handler's first hop, never silently dropped here
   // — [[additionalproperties-false-in-an-mcp]].
   if (args.jtbd !== undefined && String(args.jtbd).trim()) {
+    const text = combineTimestampedText(currentBuffer, 'jtbd', String(args.jtbd).trim());
     patches.push({
       path: 'jtbd',
-      value: { at: iso, text: String(args.jtbd).trim(), confirmed: true },
+      value: { at: iso, text, confirmed: true },
     });
   }
 
+  // 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-channel.mjs

@@ -12,7 +12,7 @@
 
 import { existsSync, watch as fsWatch } from 'node:fs';
 import { basename as pathBasename, dirname, join } from 'node:path';
-import { loadCaptureFocus, captureFocusPath } from './capture-focus.mjs';
+import { loadCaptureFocusOffline, captureFocusPath } from './capture-focus.mjs';
 import { parseSpecId } from './spec-id-lib.mjs';
 
 // Exponential reconnect backoff (ms). Capped at 30s; jittered ±50% on use.
@@ -205,6 +205,54 @@ export function createCaptureChannelWatcher({
     return body?.session ?? null;
   }
 
+  /**
+   * Resolve the LIVE capture-on-deck pin, the same way `readCaptureFocusVendor`
+   * does elsewhere in the vendor MCP (`capture-tools.mjs`): GET the Neon
+   * control-plane pin + selection, falling back to the offline file
+   * (`loadCaptureFocusOffline`) only when the console can't be reached, and only
+   * when that file pin is not itself stale. Kept local
+   * (own `fetchImpl`/`getConsoleUrl`, mirroring `fetchSessionSnapshot` above)
+   * rather than importing capture-tools.mjs, so this watcher's boot-time pin
+   * read stays on the SAME injectable transport its tests already stub.
+   *
+   * Fixes [[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]]: on a
+   * console-backed vault the pin lives in Neon, not the offline file — every
+   * MCP server start used to `loadCaptureFocus(vaultRoot)` (the file) here,
+   * so on this repo it printed "pin → HS-CAP-VDPB is already materialized"
+   * for a capture promoted two months earlier, on every single boot.
+   */
+  async function fetchLiveCaptureFocus() {
+    try {
+      const consoleUrl = getConsoleUrl().replace(/\/$/, '');
+      const [pinRes, selRes] = await Promise.all([
+        fetchImpl(`${consoleUrl}/api/control/capture-focus-pin`, { headers: { accept: 'application/json' } }),
+        fetchImpl(`${consoleUrl}/api/control/capture-focus-selection`, { headers: { accept: 'application/json' } }),
+      ]);
+      if (pinRes.ok) {
+        const pinBody = await pinRes.json();
+        const pin = pinBody?.pin ?? null;
+        if (!pin) return null; // Neon authoritative — no pin means nothing on deck.
+        const selBody = selRes.ok ? await selRes.json() : null;
+        const sel = selBody?.selection ?? 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;
+        focus.kind = 'idea';
+        return focus;
+      }
+    } catch {
+      // Fall through to the offline file seam.
+    }
+    // Offline seam — refuse a rotted file pin instead of starting a watcher on it.
+    // This watcher spent two months announcing a June capture read off this file
+    // ([[HS-O4U6-2ZRO-DIAG-the-offline-capture-pin-file-is-months]]).
+    return loadCaptureFocusOffline(vaultRoot).focus;
+  }
+
   async function openAndConsumeStream(sessionId, controller) {
     const consoleUrl = getConsoleUrl();
     const url = `${consoleUrl.replace(/\/$/, '')}/api/capture/sessions/${encodeURIComponent(sessionId)}/events`;
@@ -447,13 +495,14 @@ export function createCaptureChannelWatcher({
     if (pinDebounceTimer) clearTimeout(pinDebounceTimer);
     pinDebounceTimer = setTimeout(() => {
       pinDebounceTimer = null;
-      reevaluatePin();
+      reevaluatePin().catch((err) => log(`reevaluatePin failed: ${err?.message ?? err}`));
     }, PIN_WATCH_DEBOUNCE_MS);
   }
 
-  function reevaluatePin() {
+  async function reevaluatePin() {
     if (stopped) return;
-    const focus = loadCaptureFocus(vaultRoot);
+    const focus = await fetchLiveCaptureFocus();
+    if (stopped) return; // may have been stopped while the pin fetch was in flight
     const nextSessionId = focus ? deriveSessionIdFromFocus(focus) : null;
 
     if (nextSessionId === activeSessionId) {
@@ -533,7 +582,8 @@ export function createCaptureChannelWatcher({
       return;
     }
     startPinWatcher();
-    reevaluatePin(); // initial open if pin already exists
+    // Initial open if pin already exists — fire-and-forget (async network read).
+    reevaluatePin().catch((err) => log(`reevaluatePin failed: ${err?.message ?? err}`));
   }
 
   function stop() {

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

@@ -19,6 +19,17 @@ import {
   removeOutboxEntry,
   stashCaptureArgs,
 } from "./capture-outbox.mjs";
+import {
+  CONSOLE_NOT_SIGNED_IN,
+  consoleAuthErrorMessage,
+  consoleUnauthorizedMessage,
+} from "./console-fetch.mjs";
+// The runnable form of a HeySpex command on THIS machine — `hs login` when the
+// bin is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" login`.
+// Never an `npx` form: npx resolves from the READER's working directory, and
+// outside a checkout `npx hs` installs the unrelated public package hs@2.0.1
+// ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+import { hsCommand } from "../../scripts/lib/hs-command.mjs";
 
 /**
  * Error taxonomy for capture-session console calls ([[HS-K27H-DIAG-0G86]]).
@@ -39,14 +50,28 @@ import {
  *   message verbatim. (Entries ALREADY in the outbox from a genuine
  *   transport failure still pause the drain on 5xx and retry later — the
  *   ban is on adding new entries for an answered request.)
+ * - `CONSOLE_LOCAL_URL_IN_CLOUD_MODE` / `CONSOLE_NOT_SIGNED_IN`
+ *   ([[HS-9R6S-N8VP-DIAG-capture-writes-report-the-console-as]]): the call
+ *   never had a chance — cloud mode pointed at a local console, no bearer
+ *   token on this machine, or an answered HTTP 401. NEVER stash: nothing
+ *   becomes reachable until `hs login` runs, so a "your words are buffered
+ *   and will sync" promise would be false AND would hide the real cause.
+ *   console-fetch stamps `authProblem` on the transport result; the 401 form
+ *   stays inside the 4xx "the server ANSWERED, never stash" family and only
+ *   swaps the generic CAPTURE_CONFLICT code for an actionable one.
  */
 export const CAPTURE_ERROR_UNREACHABLE = "CONSOLE_UNREACHABLE";
 export const CAPTURE_ERROR_CONFLICT = "CAPTURE_CONFLICT";
 export const CAPTURE_ERROR_FAILED = "PATCH_FAILED";
+export const CAPTURE_ERROR_NOT_SIGNED_IN = CONSOLE_NOT_SIGNED_IN;
 
 /** Classify a `consoleFetch` result by HTTP status range. */
 export function classifyConsoleFetchError(result) {
+  // Sign-in problems are stamped by console-fetch on the status-0 result and
+  // outrank the generic transport class — they never buffer.
+  if (result.authProblem) return result.authProblem;
   if (result.status === 0) return CAPTURE_ERROR_UNREACHABLE;
+  if (result.status === 401) return CONSOLE_NOT_SIGNED_IN;
   if (result.status >= 400 && result.status < 500)
     return CAPTURE_ERROR_CONFLICT;
   return CAPTURE_ERROR_FAILED;
@@ -66,7 +91,7 @@ export function extractConsoleMessage(result) {
  *   - list/create helper failures:  `{ ok:false, error, result }` (status on `result`)
  *
  * @returns {{
- *   kind: 'transport'|'client'|'server',
+ *   kind: 'transport'|'auth'|'client'|'server',
  *   shouldStash: boolean,
  *   error: string,
  *   http_status: number,
@@ -86,6 +111,38 @@ export function describeCaptureWriteFailure(failure) {
   const serverCode = typeof result?.body?.error === "string" ? result.body.error : null;
   const serverMessage = typeof result?.body?.message === "string" ? result.body.message : null;
 
+  // Sign-in problems first ([[HS-9R6S-N8VP-DIAG]]). A refused connection to the
+  // WRONG console is not an outage, and a 401 is not a capture conflict —
+  // both are "run hs login", and neither may touch the offline buffer.
+  const authProblem =
+    typeof result?.authProblem === "string" ? result.authProblem : null;
+  if (status === 0 && authProblem) {
+    return {
+      kind: "auth",
+      shouldStash: false,
+      error: authProblem,
+      http_status: 0,
+      server_error_code: null,
+      server_message: null,
+      message:
+        result?.authMessage
+        || consoleAuthErrorMessage(authProblem, result?.url)
+        || null,
+    };
+  }
+  if (status === 401) {
+    const verbatim401 = serverMessage ? ` The server said: ${serverMessage}` : "";
+    return {
+      kind: "auth",
+      shouldStash: false,
+      error: CONSOLE_NOT_SIGNED_IN,
+      http_status: 401,
+      server_error_code: serverCode,
+      server_message: serverMessage,
+      message: `${consoleUnauthorizedMessage(result?.url)}${verbatim401}`,
+    };
+  }
+
   // status 0 ⇔ genuine transport failure (ECONNREFUSED / DNS / timeout /
   // abort — console-fetch stamps status 0 on every non-response). Anything
   // else is an HTTP response the server actually returned.
@@ -116,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,
@@ -141,9 +203,25 @@ 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`),
+ *   and a message
+ *   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 || {});
@@ -161,6 +239,42 @@ export function respondToCaptureWriteFailure(vaultRoot, args, failure) {
       pending_sync: pending,
     };
   }
+  if (d.kind === "auth") {
+    // NOT buffered, and the payload must not imply otherwise ([[HS-9R6S-N8VP-DIAG]]).
+    return {
+      ok: false,
+      status: "blocked",
+      error: d.error,
+      http_status: d.http_status,
+      server_error: d.server_error_code,
+      console_error: d.server_message ?? d.server_error_code,
+      buffered: false,
+      stashed: [],
+      // The form that actually runs on this machine, never the bare `hs`
+      // spelling ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+      action: hsCommand("login"),
+      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",