heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/response-budget.mjs

@@ -0,0 +1,348 @@
+// Byte budget for every MCP READ tool
+// ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]] under
+// [[HS-49AL-8KK5-EPIC-hot-row-cache-and-bounded-agent-tools]]).
+//
+// Before this module no byte budget existed anywhere in the MCP server: memory
+// recall bounded by COUNT and sliced, list tools that page
+// ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]], `list-tools.mjs`)
+// fit their own 8 KB page, and everything else returned whatever it had —
+// `heyspex_list_known_tags` once handed an agent 138 KB in one call
+// ([[HS-7QM6-1Q1C-DIAG-heyspex-list-known-tags-response-busts-t]]).
+//
+// The contract:
+//   - every read-shaped catalog tool (name matching {@link READ_TOOL_NAME_PATTERN})
+//     declares `budget: { max_bytes }` in `tool-catalog.mjs`
+//     ({@link DEFAULT_TOOL_BUDGET_BYTES} unless the tool says otherwise);
+//   - `tool-dispatch.mjs` runs every declared budget through
+//     {@link applyToolBudget} on the way out, so a tool that pages natively
+//     (list-tools, known-tags) is merely re-checked, and a tool that does NOT
+//     page is bounded anyway;
+//   - {@link enforceByteBudget} measures `Buffer.byteLength(JSON.stringify(result))`
+//     — the whole MCP result envelope, a strict superset of the text the agent
+//     reads — and when over budget drops trailing items from the payload's list,
+//     re-points `next_cursor` at the FIRST DROPPED item, and sets
+//     `truncated: true`. It never returns more than `max_bytes`: a payload with
+//     no list (or whose single remaining item is itself too big) has its
+//     longest strings cut with a marker, and as the last resort the payload is
+//     replaced by a tiny `RESPONSE_OVER_BUDGET` envelope.
+//
+// The generic `next_cursor` is a BUDGET cursor: an opaque base64url token the
+// dispatcher recognises on the way IN (`applyToolBudget` strips it, re-issues
+// the tool's own `after`, and resumes from the first dropped item), so a tool
+// with no native paging is still walkable to exhaustion one bounded page at a
+// time, and a tool WITH native paging keeps its own cursor untouched (the
+// budget cursor carries it inside).
+
+/** 48 000 bytes ≈ 12k tokens at ~4 bytes/token — the default ceiling for one read-tool reply. */
+export const DEFAULT_TOOL_BUDGET_BYTES = 48_000;
+
+/**
+ * Read-shaped tool names: the verb segment (after any namespace segment such as
+ * `design_`) is one of list / get / recall / search / next / ground.
+ * `heyspex_get_procedure`, `heyspex_design_get_pattern`, `heyspex_list_known_tags`,
+ * `heyspex_next_on_deck`, `heyspex_ground_plan` all match; `heyspex_claim_spec`
+ * does not.
+ */
+export const READ_TOOL_NAME_PATTERN = /^heyspex_(?:[a-z0-9]+_)*?(?:list|get|recall|search|next|ground)_/;
+
+/**
+ * Suffix-shaped reads (`heyspex_claim_list`, `heyspex_events_show`,
+ * `heyspex_settings_get`, …) — not in the task's prefix list, but every one of
+ * them returns rows or a record to an agent and so declares a budget too.
+ */
+export const READ_TOOL_SUFFIX_PATTERN = /_(?:list|show|get|load)$/;
+
+export function isReadShapedToolName(name) {
+  return READ_TOOL_NAME_PATTERN.test(name) || READ_TOOL_SUFFIX_PATTERN.test(name);
+}
+
+export const TRUNCATION_MARKER = '…[truncated: byte budget]';
+
+/** The measure every budget is checked against — the whole MCP result envelope. */
+export function measureResultBytes(result) {
+  return Buffer.byteLength(JSON.stringify(result), 'utf8');
+}
+
+// ── Budget cursor ────────────────────────────────────────────────────────────
+
+/**
+ * `{ key, at, index, after }` → opaque base64url token.
+ *   key   — the payload field holding the list that was trimmed
+ *   at    — identity ({@link itemIdentity}) of the FIRST DROPPED item, or null
+ *   index — absolute position of that item in the tool's untrimmed list
+ *   after — the tool's OWN `after` argument for this page (null when none),
+ *           re-issued verbatim when the walker comes back with this cursor
+ */
+export function encodeBudgetCursor({ key, at, index, after }) {
+  return Buffer.from(
+    JSON.stringify({ budget: 1, key: String(key), at: at == null ? null : String(at), index: Number(index) || 0, after: after ?? null }),
+    'utf8',
+  ).toString('base64url');
+}
+
+/** Decode a budget cursor; `null` for anything that is not one (a tool's own cursor, garbage, non-strings). */
+export function decodeBudgetCursor(cursor) {
+  if (typeof cursor !== 'string' || cursor.length === 0) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (parsed && typeof parsed === 'object' && parsed.budget === 1 && typeof parsed.key === 'string') {
+      return {
+        key: parsed.key,
+        at: typeof parsed.at === 'string' ? parsed.at : null,
+        index: Number.isFinite(parsed.index) && parsed.index >= 0 ? Math.floor(parsed.index) : 0,
+        after: typeof parsed.after === 'string' && parsed.after ? parsed.after : null,
+      };
+    }
+  } catch {
+    // not a budget cursor
+  }
+  return null;
+}
+
+/** Stable identity for a list item — the field a resume can find it by again. Null when nothing fits. */
+export function itemIdentity(item) {
+  if (item == null) return null;
+  if (typeof item !== 'object') return String(item);
+  for (const field of ['id', 'name', 'tag', 'key', 'path', 'spec_id']) {
+    const v = item[field];
+    if (typeof v === 'string' && v) return v;
+    if (typeof v === 'number') return String(v);
+  }
+  return null;
+}
+
+/** The top-level array field carrying the most bytes — the list a trim should shorten. */
+export function pickListKey(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  let best = null;
+  let bestBytes = -1;
+  for (const [key, value] of Object.entries(payload)) {
+    if (!Array.isArray(value) || value.length === 0) continue;
+    const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8');
+    if (bytes > bestBytes) {
+      best = key;
+      bestBytes = bytes;
+    }
+  }
+  return best;
+}
+
+function parsePayload(result) {
+  const block = result?.content?.[0];
+  if (!block || block.type !== 'text' || typeof block.text !== 'string') return { block: null, payload: null };
+  try {
+    const payload = JSON.parse(block.text);
+    return { block, payload: payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : null };
+  } catch {
+    return { block, payload: null };
+  }
+}
+
+function withPayload(result, block, payload, pretty) {
+  const text = pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+  return { ...result, content: [{ ...block, text }, ...result.content.slice(1)] };
+}
+
+function isPretty(text) {
+  return /^\s*[{[]\s*\n/.test(text);
+}
+
+/**
+ * Resume a tool's untrimmed result from a budget cursor: drop every item before
+ * the first-dropped item the cursor names. Returns the sliced result plus the
+ * absolute `offset` the slice started at (so the NEXT budget cursor's `index`
+ * stays absolute). A cursor whose list key does not exist in the payload
+ * resumes nothing (offset 0) rather than failing — the walker still terminates
+ * because the page is re-fitted below.
+ */
+export function resumeFromBudgetCursor(result, cursor) {
+  const { block, payload } = parsePayload(result);
+  if (!block || !payload || !Array.isArray(payload[cursor.key])) return { result, offset: 0 };
+  const list = payload[cursor.key];
+  let offset = -1;
+  if (cursor.at != null) offset = list.findIndex((item) => itemIdentity(item) === cursor.at);
+  if (offset === -1) offset = Math.min(cursor.index, list.length);
+  const next = { ...payload, [cursor.key]: list.slice(offset) };
+  return { result: withPayload(result, block, next, isPretty(block.text)), offset };
+}
+
+// ── Enforcement ──────────────────────────────────────────────────────────────
+
+/** Largest `n` in `[lo, hi]` for which `fits(n)` holds (`fits` is monotone: smaller n ⇒ fewer bytes). */
+function largestFitting(lo, hi, fits) {
+  let best = lo - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    if (fits(mid)) {
+      best = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+/** Walk a payload for its string leaves (depth-limited) — `[path, length]`, longest first. */
+function longestStrings(value, path = [], depth = 0, out = []) {
+  if (depth > 4 || value == null) return out;
+  if (typeof value === 'string') {
+    out.push({ path, length: value.length });
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => longestStrings(v, [...path, i], depth + 1, out));
+  } else if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) longestStrings(v, [...path, k], depth + 1, out);
+  }
+  return out;
+}
+
+function getAt(obj, path) {
+  return path.reduce((acc, k) => (acc == null ? undefined : acc[k]), obj);
+}
+
+function setAt(obj, path, value) {
+  const clone = Array.isArray(obj) ? [...obj] : { ...obj };
+  if (path.length === 1) {
+    clone[path[0]] = value;
+    return clone;
+  }
+  clone[path[0]] = setAt(obj[path[0]], path.slice(1), value);
+  return clone;
+}
+
+function overBudgetEnvelope(result, { tool, bytes, maxBytes }) {
+  const text = JSON.stringify({
+    error: 'RESPONSE_OVER_BUDGET',
+    tool: tool ?? null,
+    truncated: true,
+    bytes,
+    max_bytes: maxBytes,
+    message: `The tool reply was ${bytes} bytes against a ${maxBytes}-byte budget and could not be trimmed to fit. Narrow the call (filters, a smaller limit, compact mode) and retry.`,
+  });
+  return { ...(result?.isError ? { isError: true } : {}), content: [{ type: 'text', text }] };
+}
+
+/**
+ * Bound one MCP tool result to `maxBytes` (measured on the whole envelope).
+ *
+ * @param result   the MCP result `{ content: [{ type: 'text', text }], isError? }`
+ * @param options.maxBytes     the budget ({@link DEFAULT_TOOL_BUDGET_BYTES} when omitted)
+ * @param options.listKey      the payload field to trim; auto-detected ({@link pickListKey}) when omitted
+ * @param options.tool         tool name, recorded in the trim envelope
+ * @param options.after        the tool's own `after` arg for this page — carried inside the budget cursor
+ * @param options.indexOffset  absolute index of the payload list's first item (a resumed page)
+ * @returns {{ result: object, bytes: number, truncated: boolean, dropped: number }}
+ */
+export function enforceByteBudget(result, options = {}) {
+  const maxBytes = Number.isFinite(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : DEFAULT_TOOL_BUDGET_BYTES;
+  const tool = options.tool ?? null;
+  if (!result || !Array.isArray(result.content)) {
+    return { result, bytes: measureResultBytes(result ?? null), truncated: false, dropped: 0 };
+  }
+  let bytes = measureResultBytes(result);
+  if (bytes <= maxBytes) return { result, bytes, truncated: false, dropped: 0 };
+
+  const { block, payload } = parsePayload(result);
+  let dropped = 0;
+
+  if (block && payload) {
+    const pretty = isPretty(block.text);
+    let current = payload;
+
+    // 1. Drop trailing list items; the cursor points at the first dropped one.
+    const key = options.listKey && Array.isArray(payload[options.listKey]) ? options.listKey : pickListKey(payload);
+    if (key && Array.isArray(current[key]) && current[key].length > 1) {
+      const list = current[key];
+      const offset = Number(options.indexOffset) || 0;
+      const shaped = (n) => ({
+        ...current,
+        [key]: list.slice(0, n),
+        next_cursor: encodeBudgetCursor({ key, at: itemIdentity(list[n]), index: offset + n, after: options.after ?? null }),
+        truncated: true,
+        budget: { max_bytes: maxBytes, list_key: key, returned: n, dropped: list.length - n },
+      });
+      const fits = (n) => measureResultBytes(withPayload(result, block, shaped(n), pretty)) <= maxBytes;
+      // Never an empty page with a cursor: at least one item stays, and if that
+      // lone item still does not fit the string cut below handles it.
+      const keep = Math.max(1, largestFitting(1, list.length - 1, fits));
+      current = shaped(keep);
+      dropped = list.length - keep;
+      bytes = measureResultBytes(withPayload(result, block, current, pretty));
+    }
+
+    // 2. Still over: cut the longest strings, longest first, until it fits.
+    if (bytes > maxBytes) {
+      current = { ...current, truncated: true, budget: { ...(current.budget ?? {}), max_bytes: maxBytes, strings_cut: 0 } };
+      let guard = 0;
+      while (bytes > maxBytes && guard < 64) {
+        guard += 1;
+        const candidates = longestStrings(current).filter((c) => c.length > TRUNCATION_MARKER.length + 8 && c.path[0] !== 'next_cursor');
+        if (candidates.length === 0) break;
+        candidates.sort((a, b) => b.length - a.length);
+        const target = candidates[0];
+        const value = getAt(current, target.path);
+        const overshoot = bytes - maxBytes;
+        // Cut generously: the overshoot plus the marker, but never below 8 chars of the original.
+        const keepChars = Math.max(8, value.length - overshoot - TRUNCATION_MARKER.length);
+        current = setAt(current, target.path, value.slice(0, keepChars) + TRUNCATION_MARKER);
+        current.budget = { ...current.budget, strings_cut: (current.budget.strings_cut ?? 0) + 1 };
+        bytes = measureResultBytes(withPayload(result, block, current, pretty));
+      }
+    }
+
+    if (bytes <= maxBytes) {
+      return { result: withPayload(result, block, current, pretty), bytes, truncated: true, dropped };
+    }
+  } else if (block) {
+    // 3. Non-JSON text: cut the text itself to fit.
+    const text = block.text;
+    const fitsText = (n) => measureResultBytes({ ...result, content: [{ ...block, text: text.slice(0, n) + TRUNCATION_MARKER }, ...result.content.slice(1)] }) <= maxBytes;
+    const keep = largestFitting(0, text.length, fitsText);
+    if (keep >= 0) {
+      const cut = { ...result, content: [{ ...block, text: text.slice(0, keep) + TRUNCATION_MARKER }, ...result.content.slice(1)] };
+      return { result: cut, bytes: measureResultBytes(cut), truncated: true, dropped: 0 };
+    }
+  }
+
+  // 4. Last resort — the envelope is a few hundred bytes and always fits.
+  const envelope = overBudgetEnvelope(result, { tool, bytes, maxBytes });
+  return { result: envelope, bytes: measureResultBytes(envelope), truncated: true, dropped };
+}
+
+/**
+ * The dispatcher's hook: run `invoke(args)` for a tool that declares `budget`,
+ * resuming from a budget cursor on the way in and enforcing the budget on the
+ * way out. A tool without a budget is invoked untouched. `invoke` may return a
+ * Promise (several handlers are async) — the result is unwrapped either way.
+ */
+export function applyToolBudget(name, args, invoke, budget) {
+  const maxBytes = Number(budget?.max_bytes);
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return invoke(args);
+
+  let effectiveArgs = args ?? {};
+  let resume = null;
+  if (typeof effectiveArgs.after === 'string') {
+    resume = decodeBudgetCursor(effectiveArgs.after);
+    if (resume) {
+      effectiveArgs = { ...effectiveArgs };
+      if (resume.after) effectiveArgs.after = resume.after;
+      else delete effectiveArgs.after;
+    }
+  }
+
+  const finish = (raw) => {
+    let result = raw;
+    let indexOffset = 0;
+    if (resume) ({ result, offset: indexOffset } = resumeFromBudgetCursor(result, resume));
+    return enforceByteBudget(result, {
+      maxBytes,
+      listKey: budget.list_key,
+      tool: name,
+      after: typeof effectiveArgs.after === 'string' ? effectiveArgs.after : null,
+      indexOffset,
+    }).result;
+  };
+
+  const raw = invoke(effectiveArgs);
+  return raw && typeof raw.then === 'function' ? raw.then(finish) : finish(raw);
+}

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

@@ -5,6 +5,23 @@
  * Mirrors `.heyspex/focus.yaml` (build pipeline) and `.heyspex/research-focus.yaml`
  * (research pipeline). Honored unconditionally when present, same semantics as
  * [[focus-yaml-always-wins-in-hs-next]].
+ *
+ * CLOUD WRITE MODE ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * this module is deliberately NOT routed through the console, and that is a
+ * decision rather than an omission. The pin it writes is LOCAL MACHINE STATE,
+ * not vault content — it lives in the repo's dot-directory, never under
+ * `specs/`, carries no id/type/frontmatter contract, and is not indexed by
+ * anything. It is therefore not a split brain the way a stray `specs/*.md`
+ * would be: a pin is per-workstation by design, and two machines are SUPPOSED
+ * to be able to hold different ones. HS-KR16 §Scope made exactly this call for
+ * the promote-research review-gate markers in the same dot-directory.
+ *
+ * The corollary: because it is not vault content, it also has no spec `type`
+ * and therefore no `POST /api/specs` route it could be filed through — routing
+ * it would mean inventing a type, which is the thing
+ * `CLOUD_MODE_UNSUPPORTED_WRITE` exists to refuse. Keeping the disk write is
+ * the correct behaviour in BOTH modes; it is not degraded and does not need to
+ * be reported.
  */
 
 import {
@@ -14,8 +31,10 @@ import {
   mkdirSync,
   rmSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute, resolve, sep } from 'node:path';
 import { parseSimpleFocusYaml } from './capture-focus.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
 
 export function reviewFocusPath(vaultRoot) {
   return join(vaultRoot, '.heyspex', 'review-focus.yaml');
@@ -36,6 +55,11 @@ export function writeReviewFocus(vaultRoot, { specId, reason }) {
     return { error: 'MISSING_SPEC_ID', message: 'spec_id is required' };
   }
   const dir = join(vaultRoot, '.heyspex');
+  try {
+    assertPathUnderRoot(vaultRoot, dir, 'review-focus write');
+  } catch (err) {
+    return { error: 'BAD_VAULT_ROOT', message: err.message };
+  }
   mkdirSync(dir, { recursive: true });
   const lines = [
     '# HeySpex review-on-deck — MCP /hs-review ([[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]])',

package/vendor/heyspex-mcp/search-specs.mjs

@@ -0,0 +1,280 @@
+/**
+ * search-specs.mjs — `heyspex_search_specs`, the vault's text search for agents
+ * ([[HS-YFLS]] fix 2).
+ *
+ * THE DEFECT THIS CLOSES
+ * ----------------------
+ * The bug-filing protocol tells an agent to "search specs/diagnoses/ before
+ * filing" — and no MCP tool searched specs by text. In PROD mode the vault is
+ * CLOUD-primary and the local mirror is incomplete (537 files on disk against
+ * 559 in the system of record), so a `grep` over the checkout is not a search
+ * of the vault: it answers "not on this disk", which is not the same claim.
+ * `heyspex_resolve_focus_intent` is the nearest thing and it is built for a
+ * different job — given the AC2 symptom sentence it returns 20 specs matched on
+ * a broad `security` tag and neither of the two that actually describe it.
+ *
+ * WHAT THIS IS
+ * ------------
+ * A duplicate check. It reads the CLOUD vault through `GET /api/search` — the
+ * system of record, never local disk — asks a handful of bounded angles
+ * ({@link ./symptom-query.mjs}, see that module for why one query cannot work),
+ * merges the windows, and returns enough per row to JUDGE a duplicate without a
+ * second call: id, name, type, status, a marked-up snippet, and which angles
+ * matched.
+ *
+ * A NEGATIVE MUST MEAN "NOT THERE", NEVER "COULD NOT LOOK" ([[HS-YFLS]] AC3)
+ * -------------------------------------------------------------------------
+ * Every way of not finding something is reported as a DIFFERENT thing:
+ *
+ *   result: "no_match"  — the corpus WAS searched and holds nothing. `searched`
+ *                         is true and `queries_tried` lists exactly what was
+ *                         asked. This is the only shape an agent may act on by
+ *                         filing a new spec.
+ *   result: "no_query"  — nothing searchable was extracted from the input.
+ *   isError envelopes   — CONSOLE_UNREACHABLE / CONSOLE_NOT_SIGNED_IN /
+ *                         VAULT_SCOPE_UNRESOLVED (a transient 503, retry) /
+ *                         VAULT_SCOPE_UNAUTHORIZED (the caller's vault could
+ *                         not be resolved, so the endpoint returned an empty
+ *                         page that means nothing about the corpus) /
+ *                         SEARCH_FAILED / SEARCH_RESPONSE_UNRECOGNIZED.
+ *
+ * An angle that fails fails the WHOLE call. A partial answer is indistinguishable
+ * from a complete one at the call site, and a silently partial duplicate check is
+ * exactly how the duplicate gets filed.
+ */
+
+import { consoleFetch as defaultConsoleFetch, controlOk } from './console-transport.mjs';
+import { buildSymptomQueries } from './symptom-query.mjs';
+
+/** Rows requested per angle. Bounded: this tool never walks the vault. */
+const ANGLE_LIMIT = 20;
+
+/** Default / maximum rows returned to the agent. */
+const DEFAULT_TOP_K = 10;
+const MAX_TOP_K = 30;
+
+/** Snippets are for judging a duplicate, not for reading the spec. */
+const MAX_SNIPPET_CHARS = 320;
+
+function errorResult(payload) {
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * Classify a non-OK `/api/search` response. Each code sends the agent somewhere
+ * different, which is the entire point of not collapsing them into "no results".
+ */
+function searchFailure(res, query) {
+  const status = res?.status ?? 0;
+  const code =
+    status === 0
+      ? 'CONSOLE_UNREACHABLE'
+      : status === 401
+        ? 'CONSOLE_NOT_SIGNED_IN'
+        : status === 503
+          ? 'VAULT_SCOPE_UNRESOLVED'
+          : 'SEARCH_FAILED';
+  const message =
+    code === 'CONSOLE_UNREACHABLE'
+      ? 'The console did not answer, so the vault was NOT searched. Check heyspex_dev_server_status (or console reachability in cloud mode) — do NOT read this as "no matching spec".'
+      : code === 'CONSOLE_NOT_SIGNED_IN'
+        ? 'The console refused this caller (401), so the vault was NOT searched. Re-pair the MCP bearer — do NOT read this as "no matching spec".'
+        : code === 'VAULT_SCOPE_UNRESOLVED'
+          ? 'This console instance has not resolved its active vault yet (transient). Retry shortly — the vault was NOT searched.'
+          : `GET /api/search returned ${status}, so the vault was NOT searched.`;
+  return errorResult({
+    error: code,
+    message,
+    searched: false,
+    status,
+    url: res?.url ?? null,
+    attempted_query: query ?? null,
+    console_response: res?.body ?? null,
+  });
+}
+
+/** `<mark>`s are kept — they show WHERE the match landed — but the row is capped. */
+function normalizeSnippet(value) {
+  if (typeof value !== 'string') return '';
+  const flat = value.replace(/\s+/g, ' ').trim();
+  return flat.length > MAX_SNIPPET_CHARS ? `${flat.slice(0, MAX_SNIPPET_CHARS)}…` : flat;
+}
+
+function normalizeRow(row) {
+  const id = typeof row?.id === 'string' ? row.id : null;
+  if (!id) return null;
+  const rank = Number(row?.rank);
+  return {
+    id,
+    name: String(row?.name ?? id),
+    type: String(row?.type ?? 'unknown'),
+    status: String(row?.status ?? 'unknown').toLowerCase(),
+    rank: Number.isFinite(rank) && rank > 0 ? rank : 0,
+    snippet: normalizeSnippet(row?.snippet),
+  };
+}
+
+/**
+ * One bounded page for one angle. Returns `{ rows, mode }` on success, or a
+ * ready-to-return error envelope under `{ failure }` — never an empty page
+ * standing in for a failure.
+ */
+async function fetchAngle(fetchImpl, { q, limit, type, status }) {
+  const params = new URLSearchParams();
+  params.set('q', q);
+  params.set('limit', String(limit));
+  params.set('scope', 'body');
+  if (type) params.set('type', type);
+  if (status) params.set('status', status);
+
+  let res;
+  try {
+    res = await fetchImpl(`/api/search?${params.toString()}`);
+  } catch (err) {
+    return {
+      failure: errorResult({
+        error: 'CONSOLE_UNREACHABLE',
+        message: `The console search endpoint threw (${err?.message ?? err}), so the vault was NOT searched. Do NOT read this as "no matching spec".`,
+        searched: false,
+        attempted_query: q,
+      }),
+    };
+  }
+  if (!res || !res.ok) return { failure: searchFailure(res, q) };
+
+  const body = res.body && typeof res.body === 'object' ? res.body : {};
+  // The route answers a caller whose vault scope it could not authorize with a
+  // 200 and an EMPTY page carrying `vaultScope.authorized: false`. That page is
+  // a permission verdict, not a statement about the corpus — the one shape that
+  // would otherwise read as a clean "no duplicate exists".
+  if (body.vaultScope && body.vaultScope.authorized === false) {
+    return {
+      failure: errorResult({
+        error: 'VAULT_SCOPE_UNAUTHORIZED',
+        message: `The console could not resolve a vault for this caller (${body.vaultScope.reason ?? 'unknown'}), so the empty page it returned says nothing about the vault. Do NOT read this as "no matching spec".`,
+        searched: false,
+        reason: body.vaultScope.reason ?? null,
+        attempted_query: q,
+      }),
+    };
+  }
+  const rows = Array.isArray(body.rows) ? body.rows : Array.isArray(body.results) ? body.results : null;
+  // `mode` ("fts" | "bm25" | "trgm" | "memory") is the endpoint's proof that it
+  // actually ran a query. Its absence alongside no rows is an unrecognized
+  // shape, and an unrecognized shape is never a negative result.
+  if (rows === null || typeof body.mode !== 'string') {
+    return {
+      failure: errorResult({
+        error: 'SEARCH_RESPONSE_UNRECOGNIZED',
+        message: 'GET /api/search answered 200 with a body this tool cannot read as a search result (no `rows`/`mode`), so the vault was NOT searched.',
+        searched: false,
+        attempted_query: q,
+        console_response: body,
+      }),
+    };
+  }
+  return { rows: rows.map(normalizeRow).filter(Boolean), mode: body.mode };
+}
+
+/**
+ * `heyspex_search_specs` — find specs in the CLOUD vault by symptom text.
+ *
+ * args: { query, top_k?, type?, status? }
+ * deps: { fetchImpl } (tests inject; production uses the shared consoleFetch)
+ */
+export async function handleSearchSpecs(args = {}, { fetchImpl = defaultConsoleFetch } = {}) {
+  const query = typeof args.query === 'string' ? args.query.trim() : '';
+  if (!query) {
+    return errorResult({
+      error: 'SEARCH_QUERY_REQUIRED',
+      message: '`query` is required — pass the symptom sentence (or the concept) you would otherwise grep for.',
+      searched: false,
+    });
+  }
+  const topKRaw = Number(args.top_k);
+  const topK = Number.isFinite(topKRaw) && topKRaw > 0 ? Math.min(MAX_TOP_K, Math.trunc(topKRaw)) : DEFAULT_TOP_K;
+  const type = typeof args.type === 'string' && args.type.trim() ? args.type.trim() : undefined;
+  const status = typeof args.status === 'string' && args.status.trim() ? args.status.trim() : undefined;
+
+  const { terms, queries } = buildSymptomQueries(query);
+  if (queries.length === 0) {
+    return controlOk({
+      query,
+      terms,
+      queries_tried: [],
+      searched: false,
+      result: 'no_query',
+      match_count: 0,
+      matches: [],
+      message: 'No searchable term survived normalization (the input was punctuation or stopwords only) — the vault was NOT searched. Rephrase with the concrete nouns from the symptom.',
+    });
+  }
+
+  /** id → merged candidate. */
+  const byId = new Map();
+  const queriesTried = [];
+  let mode = null;
+
+  for (const angle of queries) {
+    // eslint-disable-next-line no-await-in-loop -- a handful of bounded angles, deliberately sequential so a failure stops the walk.
+    const page = await fetchAngle(fetchImpl, { q: angle.q, limit: ANGLE_LIMIT, type, status });
+    if (page.failure) return page.failure;
+    mode = mode ?? page.mode;
+    queriesTried.push({ label: angle.label, q: angle.q, hits: page.rows.length, mode: page.mode });
+    page.rows.forEach((row, position) => {
+      const existing = byId.get(row.id);
+      if (!existing) {
+        byId.set(row.id, { ...row, matched_by: [angle.label], best_position: position });
+        return;
+      }
+      // Keep the strongest evidence each angle produced for this spec.
+      existing.rank = Math.max(existing.rank, row.rank);
+      existing.best_position = Math.min(existing.best_position, position);
+      if (!existing.snippet && row.snippet) existing.snippet = row.snippet;
+      if (!existing.matched_by.includes(angle.label)) existing.matched_by.push(angle.label);
+    });
+  }
+
+  // Agreement across angles first (a spec the quoted concept AND the loose term
+  // window both surfaced is the likeliest duplicate), then the endpoint's own
+  // `ts_rank_cd`, then the order it handed rows back — which is the only signal
+  // left on the disk read tier, where every rank is 0.
+  const matches = [...byId.values()]
+    .sort(
+      (a, b) =>
+        b.matched_by.length - a.matched_by.length ||
+        b.rank - a.rank ||
+        a.best_position - b.best_position ||
+        a.id.localeCompare(b.id),
+    )
+    .slice(0, topK)
+    .map(({ best_position: _position, ...row }) => row);
+
+  if (matches.length === 0) {
+    return controlOk({
+      query,
+      terms,
+      queries_tried: queriesTried,
+      searched: true,
+      corpus: 'cloud-vault (GET /api/search — the system of record, not local disk)',
+      result: 'no_match',
+      match_count: 0,
+      matches: [],
+      mode,
+      message: `Searched the vault on ${queriesTried.length} angle(s) and found NOTHING. This is an explicit negative: the corpus was read and holds no spec matching these terms — it is safe to file.`,
+    });
+  }
+
+  return controlOk({
+    query,
+    terms,
+    queries_tried: queriesTried,
+    searched: true,
+    corpus: 'cloud-vault (GET /api/search — the system of record, not local disk)',
+    result: 'match',
+    match_count: matches.length,
+    mode,
+    matches,
+    message: 'Read each match before filing: a spec that already describes this symptom must be commented on or reopened, not duplicated.',
+  });
+}