heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/deferred-reclaim.mjs

@@ -5,11 +5,11 @@
  */
 
 import { readFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute, resolve, sep } from 'node:path';
 
 import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
-import { mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { collectOccupiedKeysEitherKind, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
 import {
   isoNow,
   deriveSlug,
@@ -22,12 +22,15 @@ import {
 } from './promotion-helpers.mjs';
 import { extractHandoffEnvelopeYaml } from '../../spex-console/src/lib/indexer/handoff-envelope.mjs';
 import { buildDiagnoseSkeletonSections } from './diagnose-skeleton.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
 
 /** Default cap when frontmatter omits `attempt_count` ([[HS-TASK-6OU5]]). */
 export const DEFAULT_DEFER_RECLAIM_ATTEMPT_CAP = 3;
 
+
 function collectOccupiedDiagnoseIds(vaultRoot) {
   const occupied = new Set();
+  // Disk-only scan — misses Neon-only (cloud-filed) diagnoses; see [[HS-7UJZ-O86I-DIAG]].
   const dir = join(vaultRoot, 'specs', 'diagnoses');
   if (!existsSync(dir)) return occupied;
   for (const file of readdirSync(dir)) {
@@ -232,7 +235,24 @@ export function executeDeferredSplitReclaim(vaultRoot, task, opts = {}) {
     parseSpecId(allocatedFamilyId)?.familyKey ?? mintFamilyKey(vaultRoot, { randomUnit: opts.randomUnit });
   // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
   // and (V3) the anchor for `id:` itself.
-  const fileKey = mintFileKey(vaultRoot, { randomUnit: opts.randomUnit });
+  // FILE KEY occupancy ([[HS-FJWL]]). `opts.occupiedKeys` lets a tier-aware
+  // caller hand in the set resolved for ITS read tier
+  // (`collectOccupiedKeysEitherKindViaTier`); absent one, this falls back to
+  // the local `specs/**` walk.
+  //
+  // The fallback is safe HERE and nowhere else, for a reason worth stating:
+  // this function is synchronous and its only caller is the console wrapper
+  // `spex-console/src/lib/delegation/deferred-reclaim.ts`, which `readFileSync`s
+  // the task out of `vaultRoot()` and lets this module `commitWrites` the DLQ
+  // diagnose back into `specs/diagnoses/` — a disk-backed vault end to end (the
+  // line below already notes the cloud-mode gap, [[HS-7UJZ-O86I-DIAG]]). There
+  // is no MCP caller. A session with no local vault fails at the file READ long
+  // before it reaches the mint. Give this an async caller and pass
+  // `occupiedKeys`; do not let the fallback become the cloud path.
+  const fileKey = mintFileKey(
+    opts.occupiedKeys instanceof Set ? opts.occupiedKeys : collectOccupiedKeysEitherKind(vaultRoot),
+    { randomUnit: opts.randomUnit },
+  );
   const diagnoseId = `HS-${fileKey}`;
   const built = buildDlqDiagnoseContent({
     diagnoseId,
@@ -246,7 +266,13 @@ export function executeDeferredSplitReclaim(vaultRoot, task, opts = {}) {
     now,
   });
 
+  // Disk-only write target — a cloud-mode session leaves no Neon row; see [[HS-7UJZ-O86I-DIAG]].
   const diagnoseDir = join(vaultRoot, 'specs', 'diagnoses');
+  try {
+    assertPathUnderRoot(vaultRoot, diagnoseDir, 'deferred-reclaim write');
+  } catch (err) {
+    return { ok: false, error: 'BAD_VAULT_ROOT', message: err.message };
+  }
   if (!existsSync(diagnoseDir)) mkdirSync(diagnoseDir, { recursive: true });
   const diagnoseAbsPath = join(diagnoseDir, `${built.basename}.md`);
   writes.push({ kind: 'create', absPath: diagnoseAbsPath, content: built.content });

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

@@ -0,0 +1,31 @@
+// heyspex_design_* handlers (thin wrappers over design-tools.mjs). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { wrapDesignResult } from './tool-helpers.mjs';
+import { executeGetDoc as executeDesignGetDoc, executeGetPattern as executeDesignGetPattern, executeGetToken as executeDesignGetToken, executeListPatterns as executeDesignListPatterns, executeProposePattern as executeDesignProposePattern } from './design-tools.mjs';
+
+export function handleDesignListPatterns(vaultRoot, args) {
+  return wrapDesignResult(executeDesignListPatterns(vaultRoot, args));
+}
+
+export function handleDesignGetPattern(vaultRoot, args) {
+  return wrapDesignResult(executeDesignGetPattern(vaultRoot, args));
+}
+
+export function handleDesignGetToken(vaultRoot, args) {
+  return wrapDesignResult(executeDesignGetToken(vaultRoot, args));
+}
+
+export function handleDesignGetDoc(vaultRoot, args) {
+  return wrapDesignResult(executeDesignGetDoc(vaultRoot, args));
+}
+
+export function handleDesignProposePattern(vaultRoot, args) {
+  const identity = detectAgentIdentity();
+  const enriched = {
+    ...args,
+    proposed_by: args.proposed_by ?? `${identity.agent} · ${identity.sessionId}`,
+  };
+  return wrapDesignResult(executeDesignProposePattern(vaultRoot, enriched));
+}

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

@@ -11,7 +11,9 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, isAbsolute, resolve, sep } from 'node:path';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
 
 const REGISTRY_DIR = ['spex-console', 'public', 'design-system'];
 const ITEMS_DIR = ['spex-console', 'public', 'design-system', 'r'];
@@ -416,6 +418,7 @@ export function executeProposePattern(vaultRoot, args = {}) {
 
   try {
     if (!existsSync(proposalsDir)) {
+      assertPathUnderRoot(vaultRoot, proposalsDir, 'design-tools write');
       mkdirSync(proposalsDir, { recursive: true });
     }
     writeFileSync(filepath, JSON.stringify(proposal, null, 2) + '\n', 'utf8');

package/vendor/heyspex-mcp/dev-factory-bridge.mjs

@@ -4,11 +4,11 @@
  *
  * Why this file exists ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]]):
  * `research-tools.mjs` used to `import` two modules from
- * `../../dev-factory/dream-research/` at the top level. Those two static imports
+ * `../../dev-factory/spexcrawl/` at the top level. Those two static imports
  * dragged **25 files** into the MCP server's static import closure —
  * `dev-factory/router.mjs` (model routing), `dev-factory/cloud-clients.mjs`
  * (provider clients + env loading), `dev-factory/cost-tracker.mjs`, and the whole
- * `dev-factory/dream-research/` engine. Any npm package that ships a working MCP
+ * `dev-factory/spexcrawl/` engine. Any npm package that ships a working MCP
  * server therefore had to ship all of them, and `npm publish` is a one-way door.
  *
  * Loading them through `await import()` instead means:
@@ -40,8 +40,8 @@ export function loadDreamResearch() {
   dreamResearchPromise = (async () => {
     try {
       const [adapter, tool] = await Promise.all([
-        import('../../dev-factory/dream-research/firecrawl-adapter.mjs'),
-        import('../../dev-factory/dream-research/interactive-firecrawl-tool.mjs'),
+        import('../../dev-factory/spexcrawl/firecrawl-adapter.mjs'),
+        import('../../dev-factory/spexcrawl/interactive-firecrawl-tool.mjs'),
       ]);
       return {
         available: true,

package/vendor/heyspex-mcp/dev-mode-core.mjs

@@ -0,0 +1,45 @@
+/**
+ * dev-mode-core.mjs — one bundler-safe loader for `scripts/lib/dev-mode.mjs`.
+ *
+ * Several handlers on the cloud-safe surface (next_on_deck's WIP pre-fetch,
+ * file_spec's landing probe, read-path's tier selector) load the shared
+ * dev-mode core through a PATH they build at runtime
+ * (`pathToFileURL(join(root, 'scripts', 'lib', 'dev-mode.mjs'))`). That is
+ * correct for the stdio server — `HS_PKG_ROOT` and the pre-split vault-root
+ * layout both have to keep working — but it is invisible to a bundler, so on
+ * the console's `POST /api/mcp` deployment the built path pointed at the
+ * BUILD machine's checkout, missed, and the caller silently degraded (no WIP
+ * block, no landing probe).
+ *
+ * {@link importDevModeCore} keeps the runtime candidates first (identical
+ * stdio behaviour) and falls back to a STATIC relative specifier, which
+ * webpack traces at build time and therefore bundles. Packed installs resolve
+ * it to the same file the path candidates name
+ * (`node_modules/heyspex/scripts/lib/dev-mode.mjs`, shipped via package.json
+ * `files`), so the fallback is the same module by another route — never a
+ * different implementation.
+ */
+import { existsSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Load the shared dev-mode core.
+ *
+ * @param {Array<string|null|undefined>} [candidatePaths]
+ *   Absolute paths to try, in order, before the bundled fallback. A path that
+ *   does not exist (or whose import throws) is skipped.
+ * @returns {Promise<typeof import('../../scripts/lib/dev-mode.mjs')>}
+ */
+export async function importDevModeCore(candidatePaths = []) {
+  for (const candidate of candidatePaths) {
+    if (typeof candidate !== 'string' || !candidate) continue;
+    try {
+      if (existsSync(candidate)) return await import(pathToFileURL(candidate).href);
+    } catch {
+      // Unreadable/unloadable candidate — try the next one, then the fallback.
+    }
+  }
+  // Static specifier: the bundler resolves this at build time, so the module
+  // travels with the serverless chunk instead of being looked up on disk.
+  return import('../../scripts/lib/dev-mode.mjs');
+}

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

@@ -0,0 +1,124 @@
+// heyspex_dev_mode and heyspex_dev_server_status. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// scripts/dev-server-status.mjs and scripts/lib/dev-mode.mjs are CODE-repo
+// artifacts that ship with this package — since the repo split (2026-08-31)
+// the vault root no longer holds them, so resolve them relative to THIS
+// file's checkout first and fall back to the vault root only for pre-split
+// layouts where they were the same repo. `HS_PKG_ROOT` (set by the `hs.mjs`
+// dispatcher for checks-running verbs — see `scripts/lib/checks-code-root.test.mjs`)
+// wins over the derived root when a caller knows the real code checkout is
+// elsewhere; same precedence plan-review.mjs's `resolveCodeAuditRoots` uses.
+const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+
+export async function handleDevServerStatus(vaultRoot) {
+  try {
+    const local = join(CHECKOUT_ROOT, 'scripts', 'dev-server-status.mjs');
+    const scriptPath = existsSync(local)
+      ? local
+      : join(vaultRoot, 'scripts', 'dev-server-status.mjs');
+    const coreUrl = pathToFileURL(scriptPath).href;
+    const mod = await import(coreUrl);
+    const status = await mod.getDevServerStatus({ vaultRoot });
+    return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify(
+          { error: 'DEV_SERVER_STATUS_FAILED', message: String(err?.message ?? err) },
+          null,
+          2,
+        ),
+      }],
+    };
+  }
+}
+
+/**
+ * heyspex_dev_mode — get/set the dev/prod mode + local/cloud reliance (epic
+ * HS-Q6M2). Same self-containment pattern as handleDevServerStatus above:
+ * vendor/ stays dependency-free by dynamically importing the shared core
+ * (scripts/lib/dev-mode.mjs) from the vault root at call time.
+ */
+export async function handleDevMode(vaultRoot, args = {}) {
+  try {
+    const local = join(CHECKOUT_ROOT, 'scripts', 'lib', 'dev-mode.mjs');
+    const scriptPath = existsSync(local)
+      ? local
+      : join(vaultRoot, 'scripts', 'lib', 'dev-mode.mjs');
+    const coreUrl = pathToFileURL(scriptPath).href;
+    const mod = await import(coreUrl);
+    if (args.action === 'set') {
+      if (!args.mode) {
+        return {
+          isError: true,
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ error: 'MISSING_MODE', message: 'action:"set" requires mode (prod | dev | local | cloud)' }),
+          }],
+        };
+      }
+      let result;
+      try {
+        result = await mod.applyDevMode(
+          { mode: args.mode, reliance: args.reliance },
+          { source: 'mcp' },
+        );
+      } catch (err) {
+        if (err?.name === 'DevModeNotAdminError') {
+          return {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ error: 'NOT_ADMIN', message: err.message }),
+            }],
+          };
+        }
+        throw err;
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    // get (default): two-pass — resolve without the cloud rung to learn which
+    // console to ask, then fold the fetched cloud setting into the resolution.
+    const pre = mod.resolveDevMode();
+    const cloud = await mod.fetchCloudDevMode({ consoleUrl: pre.consoleUrl });
+    const resolved = mod.resolveDevMode({
+      cloudSetting: cloud.ok ? cloud.setting : undefined,
+    });
+    // Same `mode_override` object `hs dev --json` / `hs doctor --json` carry
+    // (HS-EVVI — the MCP must never disagree with the CLI on mode). Guarded:
+    // an older shipped core without the helper still answers.
+    const modeOverride =
+      typeof mod.modeOverrideOf === 'function' ? mod.modeOverrideOf(resolved) : null;
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(
+          { resolved, cloudError: cloud.error ?? null, mode_override: modeOverride },
+          null,
+          2,
+        ),
+      }],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify(
+          { error: 'DEV_MODE_FAILED', message: String(err?.message ?? err) },
+          null,
+          2,
+        ),
+      }],
+    };
+  }
+}

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

@@ -0,0 +1,54 @@
+// heyspex_verify_reproduction and heyspex_promote_diagnose handlers. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executePromoteDiagnose } from './promote-diagnose.mjs';
+import { consoleFetch } from './console-transport.mjs';
+import { resolveConsoleReliance } from './console-fetch.mjs';
+import { resolveSpecIdForMutation } from './tool-helpers.mjs';
+import { executeVerifyReproduction } from './verify-reproduction.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+
+/**
+ * `heyspex_promote_diagnose` — the breakdown stage entered from a bug write-up
+ * ([[HS-ALBV]]). Same stage as `heyspex_promote_research`, second input kind.
+ */
+export async function handlePromoteDiagnose(vaultRoot, args = {}) {
+  const result = await executePromoteDiagnose({ vaultRoot, args, deps: { consoleFetch } });
+  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) }],
+  };
+}
+
+/**
+ * `heyspex_verify_reproduction` — record a reproduction re-run on a diagnose and
+ * close it on a clean run ([[HS-09W1]] of [[HS-ALBV]]). The close goes through the
+ * status API so the reproduction gate inside it is what decides, not this handler.
+ * In cloud reliance the diagnose is resolved and the verdict recorded through the
+ * console — a cloud-filed diagnose has no file on disk ([[HS-7UJZ-O86I-DIAG]]).
+ */
+export async function handleVerifyReproduction(vaultRoot, args = {}) {
+  const resolved = await resolveSpecIdForMutation(args.spec_id);
+  if (resolved.response) return resolved.response;
+  const result = await executeVerifyReproduction({
+    vaultRoot,
+    consoleFetch,
+    args: { ...args, spec_id: resolved.specId },
+    agent: detectAgentIdentity(args.by, undefined).agent,
+    getReliance: resolveConsoleReliance,
+  });
+  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) }],
+  };
+}

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

@@ -0,0 +1,207 @@
+// Read-only audit views: heyspex_events_show, export_events, evidence_show, milestone_show. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { consoleFetch, controlError, controlOk } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { resolveActiveVault } from './vault-resolve.mjs';
+
+/**
+ * Read the current on-deck pin — [[HS-EPIC-NCPS]] focus_pin / [[HS-EPIC-CLMW]]
+ * `hs pin get`. GET /api/control/pin → { pin: row | null }.
+ */
+/**
+ * Locked empty-state copy — byte-identical to the CLI core
+ * (`spex-console/src/lib/cli/milestone-show.ts` `NEEDS_BREAKDOWN_MESSAGE`) and
+ * the MCEP pill sub-line. [[HS-TASK-HMSE]] / [[HS-EPIC-MNBD]].
+ */
+export const MILESTONE_NEEDS_BREAKDOWN_MESSAGE = 'Needs breakdown — file the first epic to start';
+
+/**
+ * Show a milestone + its structured needs-breakdown shape ([[HS-TASK-HMSE]]).
+ * Reads the spec via GET /api/specs/:id, counts `epics:`, and returns
+ * epics_count / needs_breakdown / needs_breakdown_message so console and agent
+ * consumers read the empty state without re-deriving it.
+ */
+export async function handleMilestoneShow(args = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return {
+      isError: true,
+      content: [
+        { type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'spec_id is required' }) },
+      ],
+    };
+  }
+  const result = await consoleFetch(`/api/specs/${encodeURIComponent(args.spec_id)}`);
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'MILESTONE_SHOW_FAILED'),
+      message: consoleErrorMessage(result, `GET /api/specs/${args.spec_id} returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: args.spec_id },
+    };
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  }
+  const spec = result.body?.spec ?? null;
+  if (!spec || spec.type !== 'milestone') {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            error: 'NOT_A_MILESTONE',
+            message: `${args.spec_id} is ${spec ? `a ${spec.type}` : 'not found'}, not a milestone`,
+          }),
+        },
+      ],
+    };
+  }
+  const epics = spec.frontmatter?.epics;
+  const epicsCount = Array.isArray(epics) ? epics.length : 0;
+  const needsBreakdown = epicsCount === 0;
+  const payload = {
+    id: spec.id,
+    name: spec.name ?? null,
+    status: spec.status ?? null,
+    created: spec.frontmatter?.created ?? null,
+    epics_count: epicsCount,
+    needs_breakdown: needsBreakdown,
+    needs_breakdown_message: needsBreakdown ? MILESTONE_NEEDS_BREAKDOWN_MESSAGE : null,
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * Read the per-spec audit log — [[HS-EPIC-NCPS]] spec_events / [[HS-EPIC-CLMW]]
+ * `hs events show`. GET /api/control/spec-events?spec_id=&kind=&since=&limit=.
+ */
+export async function handleEventsShow(args = {}) {
+  const params = new URLSearchParams();
+  if (typeof args.spec_id === 'string') params.set('spec_id', args.spec_id);
+  if (typeof args.kind === 'string') params.set('kind', args.kind);
+  if (typeof args.since === 'string') params.set('since', args.since);
+  if (args.limit !== undefined && args.limit !== null) params.set('limit', String(args.limit));
+  const result = await consoleFetch(`/api/control/spec-events?${params.toString()}`);
+  if (!result.ok) return controlError(result, 'EVENTS_SHOW_FAILED', { spec_id: args.spec_id });
+  return controlOk(result.body);
+}
+
+/**
+ * Consolidated evidence-trail read path
+ * ([[HS-BNDJ-TASK-consolidated-evidence-read-path-evidence]]). Thin wrapper
+ * around GET /api/evidence/:specId — the same `getEvidenceTrail` logic
+ * (`spex-console/src/lib/evidence-trail.ts`) that backs the console UI, so
+ * an assisting agent gets one consolidated answer in one call.
+ */
+export async function handleEvidenceShow(args = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return {
+      isError: true,
+      content: [
+        { type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'spec_id is required' }) },
+      ],
+    };
+  }
+  const result = await consoleFetch(`/api/evidence/${encodeURIComponent(args.spec_id)}`);
+  if (!result.ok) return controlError(result, 'EVIDENCE_SHOW_FAILED', { spec_id: args.spec_id });
+  return controlOk(result.body);
+}
+
+/**
+ * Idempotent union-and-sort merge of one month file — the SAME rule the
+ * console's `mergeMonthLines` (`spex-console/src/lib/control-plane/audit-export.ts`)
+ * applies: existing lines ∪ fresh lines, deduped, sorted (every line starts
+ * with `{"timestamp":"<iso>"` so the sort is timestamp-primary), trailing
+ * newline. Re-running over the same events is byte-identical; existing lines
+ * are never dropped.
+ */
+export function mergeMonthLinesLocal(existing, freshContent) {
+  const set = new Set();
+  for (const src of [existing ?? '', freshContent ?? '']) {
+    for (const line of src.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed) set.add(trimmed);
+    }
+  }
+  if (set.size === 0) return '';
+  return `${[...set].sort().join('\n')}\n`;
+}
+
+/**
+ * Write the month files a CLOUD export returned (`mode: "return"`) into the
+ * caller's vault repo at `<specsDir>/events/<name>`, merging idempotently.
+ * Returns the local receipt to splice into the tool result.
+ */
+export function writeReturnedMonthFiles(files, specsDirAbs, fsDeps = {}) {
+  const exists = fsDeps.existsSync ?? existsSync;
+  const read = fsDeps.readFileSync ?? readFileSync;
+  const write = fsDeps.writeFileSync ?? writeFileSync;
+  const mkdir = fsDeps.mkdirSync ?? mkdirSync;
+  const eventsDir = join(specsDirAbs, 'events');
+  const written = [];
+  const unchanged = [];
+  for (const file of files) {
+    if (!file || typeof file.name !== 'string' || !/^\d{4}-\d{2}\.jsonl$/.test(file.name)) continue;
+    const target = join(eventsDir, file.name);
+    const existing = exists(target) ? read(target, 'utf8') : null;
+    const merged = mergeMonthLinesLocal(existing, file.content);
+    if (merged === (existing ?? '')) {
+      unchanged.push(target);
+      continue;
+    }
+    mkdir(eventsDir, { recursive: true });
+    write(target, merged, 'utf8');
+    written.push(target);
+  }
+  return { vault_events_dir: eventsDir, files_written_locally: written, unchanged_locally: unchanged };
+}
+
+/**
+ * Run the idempotent audit export — [[HS-EPIC-AEHR]] §1. POST
+ * /api/control/export-events. The on-close flush surface for the
+ * session-close protocol (no automatic harness hook yet).
+ *
+ * Two contracts, chosen by the CONSOLE ([[HS-ZD70-OX3V-DIAG-heyspex-export-events-always-409s-in]]):
+ * a local console writes `specs/events/YYYY-MM.jsonl` itself (`mode:
+ * "vault"`); a cloud console has no vault on disk, so it RETURNS the month
+ * files (`mode: "return"`) and this tool merges them into the caller's vault
+ * repo — the same file, written from the other side.
+ */
+export async function handleExportEvents(args = {}) {
+  const body = {};
+  if (typeof args.since === 'string' && args.since.trim()) body.since = args.since.trim();
+  // A LOCAL console writes into ITS OWN vault root; naming ours lets it refuse
+  // (409 vault_root_mismatch) instead of rewriting a different vault's
+  // specs/events/ when this session points at the wrong console. A cloud
+  // console ignores it (it returns the files instead).
+  let vault = null;
+  try {
+    vault = resolveActiveVault();
+    if (vault?.specsDirAbs) body.expected_vault_root = vault.specsDirAbs;
+  } catch { /* best-effort — the export still runs unguarded when unresolvable */ }
+  const result = await consoleFetch('/api/control/export-events', { method: 'POST', body });
+  if (!result.ok) return controlError(result, 'EXPORT_EVENTS_FAILED');
+  const payload = result.body ?? {};
+  if (payload.mode === 'return' && Array.isArray(payload.files)) {
+    if (!vault?.specsDirAbs) {
+      return controlOk({
+        ...payload,
+        files: payload.files.map((f) => ({ name: f?.name, bytes: (f?.content ?? '').length })),
+        note:
+          'The cloud console returned the month files but no local vault could be resolved from this session, so nothing was written. Run from a checkout of the vault repo (heyspex.yaml at its root) to land specs/events/.',
+      });
+    }
+    const receipt = writeReturnedMonthFiles(payload.files, vault.specsDirAbs);
+    return controlOk({
+      ...payload,
+      files: payload.files.map((f) => ({ name: f?.name, bytes: (f?.content ?? '').length })),
+      ...receipt,
+    });
+  }
+  return controlOk(payload);
+}