heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/research-handlers.mjs

@@ -0,0 +1,623 @@
+// Research tool handlers: heyspex_save_research, promote_research,
+// promote_research_to_diagnose, split_research, complete_research, active_research
+// (the execute-level logic lives in research-tools.mjs and siblings). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeCompleteResearch, loadResearchFocus } from './research-focus.mjs';
+import { allocateRandomVaultId, collectOccupiedIdsFromSpecs } from '../../scripts/vault-id-lib.mjs';
+import { findSpecFile, parseFrontmatter } from './vault-io.mjs';
+import { executeSplitResearch } from './split-research.mjs';
+import { executePromoteResearchToDiagnose } from './promote-research-to-diagnose.mjs';
+import { executePromoteResearch } from './promote-research.mjs';
+import { consoleFetch, enrichConsoleFailurePayloadAsync } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { randomUUID } from 'node:crypto';
+import { basename, join, relative, isAbsolute, resolve, sep } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { readViaSelector, resolveReadTier, resolveVaultWriteMode } from './read-path.mjs';
+import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
+import { collectOccupiedKeysEitherKind, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { measureDiskLanding } from './tool-helpers.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+
+/**
+ * /hs-promote-research — research → milestone promotion with AI-assisted epic
+ * stubs. Implementation lives in `promote-research.mjs`; this wrapper supplies
+ * the console-fetch dep so the AI proposer call routes through console (Haiku
+ * 4.5 via tool-use, matching [[HS-TASK-TAOD]]'s pattern).
+ */
+/**
+ * Cloud-tier reads ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]):
+ * `tier` is resolved ONCE per call here (`resolveReadTier()`) and threaded
+ * into `executePromoteResearch`'s deps — never re-resolved downstream.
+ * `overrides` lets a test inject `{ tier, consoleUrl, consoleFetch,
+ * resolveReadTier }` directly so it never opens a socket; every production
+ * call site (tool-dispatch.mjs) passes none, so the real `resolveReadTier()`
+ * / `getConsoleUrl()` / `consoleFetch` run unchanged.
+ *
+ * Cloud-tier WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * `writeMode` is resolved here on the same once-per-call rule —
+ * `resolveVaultWriteMode()` is the write-side twin of `resolveReadTier()`, and
+ * `handleSaveResearch` in this same file already trusts it. This is the seam
+ * that makes the cloud write path reachable: the execute phase defaults to
+ * `deps.writeMode ?? 'local'`, so without this line a cloud-reliant session
+ * would still mint ids locally and write milestone/epic files to a disk the
+ * console's index has never heard of.
+ */
+export async function handlePromoteResearch(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 ?? getConsoleUrl();
+    const doConsoleFetch = overrides.consoleFetch ?? consoleFetch;
+    const result = await executePromoteResearch(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_RESEARCH_EXCEPTION',
+              message: err?.message ?? String(err),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * heyspex_promote_research_to_diagnose — one research investigation → one
+ * HS-DIAG-* diagnose spec ([[HS-MSHY-TASK-research-diagnose-link-send-bugs-to-the]]).
+ * Research-side sibling of handlePromoteCaptureToDiagnose. Single-phase;
+ * writes the diagnose + the research's produces_diagnose linkage
+ * transactionally.
+ */
+export async function handlePromoteResearchToDiagnose(vaultRoot, args = {}) {
+  try {
+    const result = await executePromoteResearchToDiagnose(vaultRoot, args, {});
+    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_RESEARCH_TO_DIAGNOSE_EXCEPTION', message: err?.message ?? String(err) },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * /hs-split-research — split a research doc into N child research docs.
+ * Implementation lives in `split-research.mjs`; single-phase tool (no AI),
+ * caller provides body_slice + sources_captures partitions.
+ *
+ * `tier` / `writeMode` are resolved HERE, once per call, and threaded down —
+ * the same rule {@link handlePromoteResearch} follows. In cloud write mode the
+ * children are POSTed first and every sibling cross-link is PUT against the
+ * basenames those POSTs returned.
+ */
+export async function handleSplitResearch(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 ?? getConsoleUrl();
+    const doConsoleFetch = overrides.consoleFetch ?? consoleFetch;
+    const result = await executeSplitResearch(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: 'SPLIT_RESEARCH_EXCEPTION',
+              message: err?.message ?? String(err),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+}
+
+export function handleActiveResearch(vaultRoot) {
+  const focus = loadResearchFocus(vaultRoot);
+  if (!focus?.spec_path) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              focus: null,
+              message:
+                'No research pinned. Open an idea in console and click Promote on the doc toolbar, or pass source_idea_id + scope to heyspex_complete_research directly.',
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ focus }, null, 2) }],
+  };
+}
+
+export function handleCompleteResearch(vaultRoot, args) {
+  const result = executeCompleteResearch(vaultRoot, args, {
+    allocateRandomVaultId,
+    findSpecFile,
+  });
+  if (result.error) {
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(result) }] };
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+// `research_type` enum — mirrors schemas/heyspex-frontmatter.schema.json and
+// [[entity-model]] §research ([[HS-120I-TASK-implement-research-type-field-end-to-end]]).
+export const RESEARCH_TYPE_VALUES = ['new-feature', 'enhancement', 'diagnose', 'code-audit', 'reference'];
+
+export const DEFAULT_RESEARCH_TYPE = 'reference';
+
+// `scope` enum — mirrors schemas/heyspex-frontmatter.schema.json and
+// [[entity-model]] §research ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]).
+// Same values + same default as `heyspex_promote_capture` and `heyspex_complete_research`.
+export const RESEARCH_SCOPE_VALUES = ['internal', 'codebase', 'external', 'all'];
+
+export const DEFAULT_RESEARCH_SCOPE = 'internal';
+
+export async function handleSaveResearch(vaultRoot, args) {
+  const { title, summary, content, tags = [], related = [], sources = [], research_type, scope } = args;
+
+  if (!title || !summary || !content) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'MISSING_REQUIRED_FIELDS', message: 'title, summary, and content are required' }) }],
+    };
+  }
+
+  // Optional, defaults to 'reference' — never written blank. Seam for a future
+  // kind-based suggestion is the `research_type` arg itself (a later task can
+  // pass a computed suggestion here); no inference is performed by this tool
+  // (heyspex_save_research has no source capture to derive a kind from —
+  // unlike heyspex_promote_capture, which does, see research-type-suggest.mjs).
+  if (research_type !== undefined && research_type !== null && !RESEARCH_TYPE_VALUES.includes(research_type)) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: `research_type ${JSON.stringify(research_type)} must be one of: ${RESEARCH_TYPE_VALUES.join(', ')}` }) }],
+    };
+  }
+  // HS-MVC1 AC3: track whether the caller supplied research_type at all, so
+  // the response can carry a NON-BLOCKING warning when it defaulted (save
+  // still proceeds — modeled on the `warning: "TARGET_RESEARCH_CLOSED"`
+  // pattern in promote-capture.mjs; this is not a hard gate).
+  const researchTypeWasOmitted = research_type === undefined || research_type === null;
+  const resolvedResearchType = RESEARCH_TYPE_VALUES.includes(research_type) ? research_type : DEFAULT_RESEARCH_TYPE;
+
+  // Optional, defaults to 'internal' — never written blank. NOT required (consistency
+  // fix only, no grace window) — [[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]].
+  if (scope !== undefined && scope !== null && !RESEARCH_SCOPE_VALUES.includes(scope)) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: `scope ${JSON.stringify(scope)} must be one of: ${RESEARCH_SCOPE_VALUES.join(', ')}` }) }],
+    };
+  }
+  const resolvedScope = RESEARCH_SCOPE_VALUES.includes(scope) ? scope : DEFAULT_RESEARCH_SCOPE;
+
+  // Vault-root path guard (HS-AI1T) — in BOTH write modes, before any tier or
+  // network resolution: a relative / drive-relative root is refused before
+  // anything touches disk. The directory itself is created only on the local
+  // write path below (a cloud-reliant machine may have no vault clone at all,
+  // and must not grow a phantom `specs/research/` on every save).
+  const researchDir = join(vaultRoot, 'specs', 'research');
+  if (!existsSync(researchDir)) {
+    try {
+      assertPathUnderRoot(vaultRoot, researchDir, 'research-handlers write');
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'BAD_VAULT_ROOT', message: err.message }) }],
+      };
+    }
+  }
+
+  // Shared between the two write paths: the acting agent (`assisted_by`
+  // auto-stamp, [[HS-EPIC-IKIM-authorship-provenance-frontmatter-owner]] AC #2),
+  // the cleaned `related` ids, and the markdown body.
+  const actingAgent = detectAgentIdentity(args.agent, args.session_id).agent;
+  const relatedIds = related.map((r) => String(r).replace(/^\[\[|\]\]$/g, ''));
+  const bodyMarkdown = buildResearchBodyMarkdown({ title, summary, content, sources });
+
+  // WHERE THE WRITE GOES ([[HS-DJWP-MCPC-TASK]] closed the read half; this is
+  // the write half). `vaultWriteMode` comes from the same dev-mode resolver
+  // every read tier trusts: `cloud` for prod and dev+cloud, `local` only for
+  // dev+local. A disk write in cloud mode is a split brain — a file the
+  // console's index has never heard of, on a machine that may not even hold a
+  // clone — so cloud mode files through the console exactly like
+  // heyspex_file_spec does (POST /api/specs, server-minted id).
+  const writeMode = await resolveVaultWriteMode();
+  if (writeMode === 'cloud') {
+    return saveResearchViaConsole({
+      vaultRoot,
+      title,
+      summary,
+      tags,
+      relatedIds,
+      researchType: resolvedResearchType,
+      scope: resolvedScope,
+      bodyMarkdown,
+      actingAgent,
+      researchTypeWasOmitted,
+    });
+  }
+
+  if (!existsSync(researchDir)) {
+    mkdirSync(researchDir, { recursive: true });
+  }
+
+  // [[HS-DJWP-MCPC-TASK]] "Occupied-id scans" family: id allocation needs the
+  // occupied set BEFORE the write — in cloud reliance that comes from `GET
+  // /api/vault/occupied-ids?bucket=research` instead of scanning
+  // `specs/research` on disk.
+  const tier = await resolveReadTier();
+  const consoleUrl = getConsoleUrl();
+  let occupiedResearch;
+  try {
+    occupiedResearch = await readViaSelector({
+      tier,
+      diskRead: () => {
+        const existingFiles = readdirSync(researchDir).filter(f => f.endsWith('.md') && !f.endsWith('.review.md'));
+        const scanSpecs = [];
+        for (const file of existingFiles) {
+          try {
+            const filePath = join(researchDir, file);
+            const fileContent = readFileSync(filePath, 'utf8');
+            const { frontmatter } = parseFrontmatter(fileContent);
+            scanSpecs.push({
+              id: String(frontmatter.id ?? ''),
+              basename: file.replace(/\.md$/i, ''),
+              type: 'research',
+            });
+          } catch {
+            /* skip unreadable */
+          }
+        }
+        return collectOccupiedIdsFromSpecs(scanSpecs).research;
+      },
+      neonRead: async () => {
+        const res = await consoleFetch('/api/vault/occupied-ids?bucket=research');
+        if (!res.ok) {
+          throw new Error(`GET /api/vault/occupied-ids?bucket=research returned ${res.status}: ${res.error || ''}`);
+        }
+        return new Set(Array.isArray(res.body?.ids) ? res.body.ids : []);
+      },
+      routeLabel: 'GET /api/vault/occupied-ids?bucket=research',
+      consoleUrl,
+    });
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'CONSOLE_UNREACHABLE_CLOUD_MODE', message: String(err?.message ?? err) }) }],
+    };
+  }
+  // Era-3 file-key-first ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // FAMILY token still comes from the legacy allocator's `HS-<family>-RES`
+  // draw (parentless research — no family to inherit); `id:` keys onto the
+  // file key alone.
+  const allocatedFamilyId = allocateRandomVaultId('research', occupiedResearch);
+  const familyKey = parseSpecId(allocatedFamilyId)?.familyKey ?? mintFamilyKey(vaultRoot);
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  // Disk occupancy ([[HS-FJWL]]): cloud write mode returned above (the
+  // `writeMode === 'cloud'` branch files through the console, which mints the
+  // id itself), so this line only ever runs on a disk-backed vault.
+  const fileKey = mintFileKey(collectOccupiedKeysEitherKind(vaultRoot));
+  const researchId = `HS-${fileKey}`;
+
+  const slug = researchSlug(title);
+
+  const filename = `${researchId}-${familyKey}-RES-${slug}.md`;
+  const filepath = join(researchDir, filename);
+
+  // Build frontmatter
+  const today = new Date().toISOString().split('T')[0];
+  const relatedLinks = relatedIds.map((cleanId) => `  - "[[${cleanId}]]"`).join('\n');
+  const tagsArray = tags.length > 0 ? `[${tags.join(', ')}]` : '[]';
+
+  // `assisted_by` auto-stamp: a research doc filed via MCP is agent-created, so
+  // stamp the acting agent. `owner` stays the vault owner (no authenticated user
+  // on this direct-disk path). Omit-when-empty: no line when no agent is detected.
+  const assistedByBlock = actingAgent ? `assisted_by:\n  - ${yamlScalar(actingAgent)}\n` : '';
+
+  const fileContent = `---
+id: ${researchId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(title)}
+type: research
+research_type: ${resolvedResearchType}
+scope: ${resolvedScope}
+status: open
+owner: pwher
+created: ${today}
+updated: ${today}
+${assistedByBlock}tags: ${tagsArray}
+${relatedLinks ? `related:\n${relatedLinks}` : 'related: []'}
+---
+
+${bodyMarkdown}`;
+
+  try {
+    writeFileSync(filepath, fileContent, 'utf8');
+  } catch (e) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'WRITE_FAILED', message: e.message }) }],
+    };
+  }
+
+  // Report on the RESULT, not the request ([[HS-IOJW-5YDH-DIAG]] sweep): stat
+  // the file before claiming it saved.
+  const landed = measureDiskLanding(vaultRoot, filepath);
+  if (!landed.on_disk) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'WRITE_NOT_ON_DISK',
+          message: `writeFileSync reported success but no file exists at ${filepath}. Treat the research as unsaved.`,
+          research_id: researchId,
+          landed,
+        }, null, 2),
+      }],
+    };
+  }
+
+  const result = {
+    success: true,
+    research_id: researchId,
+    filename,
+    filepath: relative(vaultRoot, filepath),
+    landed,
+    message: `Research saved to specs/research/${filename}`,
+    next_steps: researchNextSteps(slug),
+  };
+
+  // HS-MVC1 AC3: non-blocking warning — the save already succeeded above
+  // (resolvedResearchType was written to disk either way); this only informs
+  // the caller that research_type was not supplied so it defaulted, rather
+  // than silently going unnoticed.
+  if (researchTypeWasOmitted) attachResearchTypeWarning(result);
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/** The filename slug — same rule on both write paths. */
+function researchSlug(title) {
+  return String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+}
+
+/** Markdown after the frontmatter: title, summary, content, optional sources. */
+export function buildResearchBodyMarkdown({ title, summary, content, sources = [] }) {
+  let sourcesSection = '';
+  if (sources.length > 0) {
+    sourcesSection = '\n## Sources\n\n';
+    for (const src of sources) {
+      if (src.url && src.title) {
+        sourcesSection += `- [${src.title}](${src.url})${src.description ? ` — ${src.description}` : ''}\n`;
+      }
+    }
+  }
+  return `# ${title}\n\n${summary}\n\n${content}\n${sourcesSection}\n`;
+}
+
+function researchNextSteps(linkTarget) {
+  return [
+    `Add [[${linkTarget}]] wikilinks to related specs`,
+    `Update the research file as implementation progresses`,
+    // Research is evergreen ([[research-is-evergreen]]) — it never closes.
+    `Add \`enhances:\` to bind to a milestone (or \`bound_epic:\` when an epic is filed) — research stays status: open`,
+  ];
+}
+
+// HS-MVC1 AC3: non-blocking warning — the save already succeeded; this only
+// informs the caller that research_type was not supplied so it defaulted.
+function attachResearchTypeWarning(result) {
+  result.warning = 'RESEARCH_TYPE_MISSING';
+  result.warning_message = `research_type was not supplied — defaulted to "${DEFAULT_RESEARCH_TYPE}". Consider passing an explicit research_type (${RESEARCH_TYPE_VALUES.join(', ')}) next time; this does not block the save.`;
+}
+
+/**
+ * Cloud write mode: file the research doc through the console, the same call
+ * heyspex_file_spec makes (filing-tools.mjs `handleFileSpec` — POST /api/specs,
+ * idempotency-key header, no timeout retry against a remote console per
+ * [[HS-2FQY]]'s double-mint guard). The console mints the id and the family
+ * (`createSpec`: `research` -> `specs/research/`, `RES`), so nothing is
+ * allocated client-side and no occupied-id scan is needed.
+ *
+ * Returns the SAME result shape as the disk path — `success`, `research_id`,
+ * `filename`, `filepath`, `landed`, `message`, `next_steps` (+ the
+ * research_type warning) — so callers and the `/hs-res` flow read one shape.
+ * `filepath` is the console's vault-relative path (`specs/research/...`);
+ * `landed.tier` is `cloud` and `landed.on_disk` is `false`, by construction:
+ * nothing was written to this machine.
+ */
+async function saveResearchViaConsole({
+  vaultRoot,
+  title,
+  summary,
+  tags,
+  relatedIds,
+  researchType,
+  scope,
+  bodyMarkdown,
+  actingAgent,
+  researchTypeWasOmitted,
+}) {
+  // No `status:` — the console seeds `open` and refuses an out-of-band status
+  // on create ([[HS-ISZP]]); only the disk path writes it itself.
+  const frontmatter = {
+    research_type: researchType,
+    scope,
+    ...(tags.length > 0 ? { tags } : {}),
+    ...(relatedIds.length > 0 ? { related: relatedIds.map((id) => `[[${id}]]`) } : {}),
+  };
+  const body = {
+    type: 'research',
+    name: title,
+    summary,
+    frontmatter,
+    body: bodyMarkdown,
+    ...(actingAgent ? { acting_agent: actingAgent } : {}),
+  };
+
+  let result;
+  try {
+    result = await consoleFetch('/api/specs', {
+      method: 'POST',
+      body,
+      headers: { 'idempotency-key': randomUUID() },
+      retryOnTimeout: false,
+    });
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'SAVE_RESEARCH_FAILED', message: String(err?.message ?? err) }) }],
+    };
+  }
+
+  if (!result.ok) {
+    const payload = await enrichConsoleFailurePayloadAsync(result, {
+      error: consoleErrorCode(result, 'SAVE_RESEARCH_FAILED'),
+      message: consoleErrorMessage(result, `POST /api/specs returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { type: 'research', name: title },
+      write_mode: 'cloud',
+      ...(result.errorKind === 'timeout'
+        ? {
+            hint:
+              'The create may still have completed server-side after this client timed out. '
+              + 'Search for a research doc with this exact name before re-saving — a blind re-save can mint a duplicate id ([[HS-2FQY]]).',
+          }
+        : {}),
+    });
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+
+  // POST returns { spec: { id, relPath, ... }, write, warnings? }.
+  const spec = result.body?.spec ?? null;
+  const researchId = typeof spec?.id === 'string' && spec.id ? spec.id : null;
+  const relPath = spec?.relPath ?? spec?.path ?? null;
+  if (!researchId) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'SAVE_RESEARCH_MALFORMED_RESPONSE',
+          message: `POST /api/specs answered ${result.status} but carried no spec.id — treat the research as unsaved and check the console before re-saving.`,
+          url: result.url,
+          console_response: result.body,
+        }, null, 2),
+      }],
+    };
+  }
+  const filename = relPath ? basename(String(relPath)) : null;
+  const consoleWrite = result.body?.write ?? null;
+  const consoleUrl = result.url ?? getConsoleUrl();
+  const landed = {
+    tier: 'cloud',
+    reported_by: consoleWrite ? 'console' : 'inferred_from_console_url',
+    console_url: consoleUrl,
+    rel_path: relPath,
+    abs_path: null,
+    on_disk: false,
+    in_local_vault: false,
+    vault_root: vaultRoot ?? null,
+    console_write: consoleWrite,
+  };
+  const out = {
+    success: true,
+    research_id: researchId,
+    filename,
+    filepath: relPath,
+    landed,
+    message: `Research saved through the console at ${consoleUrl}${relPath ? ` (${relPath})` : ''} — cloud write mode, nothing written to local disk`,
+    next_steps: researchNextSteps(filename ? filename.replace(/\.md$/i, '') : researchId),
+    ...(Array.isArray(result.body?.warnings) && result.body.warnings.length > 0
+      ? { console_warnings: result.body.warnings }
+      : {}),
+  };
+  if (researchTypeWasOmitted) attachResearchTypeWarning(out);
+  return {
+    content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+  };
+}

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

@@ -15,7 +15,7 @@
  *     out of scope — that is [[HS-X5GJ-RES-EU6J]], a separate feature built on top of this fix).
  *   - `heyspex_firecrawl_research` is the on-demand execution surface that makes the configured
  *     Firecrawl backend REACHABLE from an interactive turn — it is a thin MCP wrapper around
- *     dev-factory/dream-research/interactive-firecrawl-tool.mjs, which itself wraps the
+ *     dev-factory/spexcrawl/interactive-firecrawl-tool.mjs, which itself wraps the
  *     existing, self-tested default-backends.mjs/firecrawl-adapter.mjs implementation (no
  *     search/scrape logic is reimplemented here).
  *
@@ -24,7 +24,7 @@
 
 import { listConfigLeaves } from './config-settings.mjs';
 // The deep-research backend is loaded LAZILY through the bridge, never imported
-// statically — a static import here pulls 25 SpexFleet / dream-research files into
+// statically — a static import here pulls 25 SpexFleet / spexcrawl files into
 // the MCP server's package closure. See dev-factory-bridge.mjs for the full
 // rationale ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]]).
 import { loadDreamResearch } from './dev-factory-bridge.mjs';
@@ -65,7 +65,7 @@ export async function executeResolveResearchPlan(vaultRoot) {
         'reports an explicit { downgraded: true, reason } if the backend is unavailable — never substitute ' +
         'web-native silently. IMPORTANT (research-routing-hard-rule-sonnet, "Sonnet is the fallback, ' +
         'Firecrawl is the default"): once the fetch succeeds, hand the gathered text to DeepSeek for ' +
-        'synthesis (dev-factory/dream-research/synthesize-cli.mjs, or the `hs-res` skill for anything ' +
+        'synthesis (dev-factory/spexcrawl/synthesize-cli.mjs, or the `hs-res` skill for anything ' +
         'beyond a single lookup) — do NOT reason over/summarize the results yourself. Sonnet doing its ' +
         'own synthesis is the fallback branch only, used after an explicit unreachability report and ' +
         'never silently.'
@@ -85,7 +85,7 @@ export async function executeResolveResearchPlan(vaultRoot) {
 /**
  * Run one Firecrawl search or scrape for an interactive agent turn (rung 0 `sequential`) —
  * the on-demand execution surface for whatever heyspex_resolve_research_plan resolved.
- * Delegates entirely to dev-factory/dream-research/interactive-firecrawl-tool.mjs; this
+ * Delegates entirely to dev-factory/spexcrawl/interactive-firecrawl-tool.mjs; this
  * function only maps the MCP snake_case args onto that module's contract.
  */
 export async function executeFirecrawlResearch(args = {}) {