heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/blocker-resolver.mjs

@@ -669,7 +669,20 @@ function buildTerminalLeafClaimTarget(node, alignmentState, breadcrumb, level =
  * `{ kind: 'has_claimable', ref, child }` when a non-terminal child exists so
  * the caller can recurse without re-walking.
  */
-export function classifyEpicChildRollup(epic, loadRef, schedulerOrderIds = [], reviewLevel = 'task') {
+/**
+ * `excludeIds` (lower-cased spec ids, optional): tasks another agent is
+ * actively holding ([[HS-3C9M-A4TX-CAP]]). A held child is passed over for the
+ * next launchable sibling so a parallel agent gets fresh work; when every
+ * launchable child is held the rollup says so (`all_held`) instead of
+ * pretending the epic is review-blocked or closed.
+ */
+export function classifyEpicChildRollup(
+  epic,
+  loadRef,
+  schedulerOrderIds = [],
+  reviewLevel = 'task',
+  excludeIds = null,
+) {
   const fm = epic?.frontmatter || {};
   const childRefs = rankRefsBySchedulerOrder(
     Array.isArray(fm.children) ? fm.children.map(wikilinkTarget).filter(Boolean) : [],
@@ -679,6 +692,7 @@ export function classifyEpicChildRollup(epic, loadRef, schedulerOrderIds = [], r
 
   let loadedCount = 0;
   let inReviewCount = 0;
+  let heldCount = 0;
   const statuses = [];
   for (const ref of childRefs) {
     if (typeof loadRef !== 'function') break;
@@ -688,11 +702,17 @@ export function classifyEpicChildRollup(epic, loadRef, schedulerOrderIds = [], r
     const status = specStatus(child);
     statuses.push(status);
     if (!CLAIM_TERMINAL_STATUSES.has(status)) {
+      const childId = String(specId(child) || ref).toLowerCase();
+      if (excludeIds && excludeIds.has(childId)) {
+        heldCount += 1;
+        continue;
+      }
       return { kind: 'has_claimable', ref, child };
     }
     if (REVIEW_AWAITING_STATUSES.has(status)) inReviewCount += 1;
   }
 
+  if (heldCount > 0) return { kind: 'all_held', held: heldCount };
   if (loadedCount === 0) return { kind: 'no_children' };
   const rollupKind = classifyParentRollup(statuses, 'task', reviewLevel);
   if (rollupKind === 'reviewer_blocked') {
@@ -752,6 +772,7 @@ export function computeClaimTarget(
   loadRef,
   schedulerOrderIds = [],
   rollupOpts,
+  excludeIds = null,
 ) {
   if (!spec) return null;
   void vaultRoot;
@@ -768,6 +789,7 @@ export function computeClaimTarget(
     new Set(),
     schedulerOrderIds,
     reviewLevel,
+    excludeIds,
   );
 }
 
@@ -779,6 +801,7 @@ function resolveClaimTargetRecursive(
   visited,
   schedulerOrderIds = [],
   reviewLevel = 'task',
+  excludeIds = null,
 ) {
   if (!spec) return null;
   const id = specId(spec);
@@ -800,7 +823,17 @@ function resolveClaimTargetRecursive(
   }
 
   if (type === 'epic') {
-    const rollup = classifyEpicChildRollup(spec, loadRef, schedulerOrderIds, reviewLevel);
+    const rollup = classifyEpicChildRollup(
+      spec,
+      loadRef,
+      schedulerOrderIds,
+      reviewLevel,
+      excludeIds,
+    );
+    // Every launchable child is held by another agent: no target here, so a
+    // milestone walk moves on to its next epic (and a root epic yields null —
+    // the caller falls back to the held task with a "held by" note).
+    if (rollup.kind === 'all_held') return null;
     if (rollup.kind === 'has_claimable') {
       const child = rollup.child;
       const childBreadcrumb = [...breadcrumb, specId(child)].filter(Boolean);
@@ -812,6 +845,7 @@ function resolveClaimTargetRecursive(
         visited,
         schedulerOrderIds,
         reviewLevel,
+        excludeIds,
       );
       if (childTarget) return childTarget;
     }
@@ -844,6 +878,7 @@ function resolveClaimTargetRecursive(
         visited,
         schedulerOrderIds,
         reviewLevel,
+        excludeIds,
       );
       if (childTarget) return childTarget;
     }

package/vendor/heyspex-mcp/breakdown-ladder.mjs

@@ -23,7 +23,10 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { resolveConsoleDeps } from './breakdown-source.mjs';
+import { listSpecsViaConsole } from './cloud-vault-writes.mjs';
 import { getFrontmatterBlock, getScalarField } from './promotion-helpers.mjs';
+import { readViaSelector } from './read-path.mjs';
 
 /**
  * Statuses a candidate must NOT be in to count as covering the area. Mirrors the
@@ -136,12 +139,28 @@ function scanDir(vaultRoot, dirParts, type) {
  * attach a bug fix to the wrong epic.
  */
 export function scanExistingCoverage(vaultRoot, source, opts = {}) {
+  const prepared = prepareCoverageScan(source, opts);
+  if (!prepared) return { milestones: [], epics: [], source_terms: [] };
+
+  return {
+    source_terms: prepared.source_terms,
+    milestones: prepared.rank(scanDir(vaultRoot, ['specs', 'milestones'], 'milestone')),
+    epics: prepared.rank(scanDir(vaultRoot, ['specs', 'epics'], 'epic')),
+  };
+}
+
+/**
+ * The source-side half of {@link scanExistingCoverage} — its term set and its
+ * ranker — lifted out so BOTH read tiers rank identically. Returns `null` for
+ * the "source carries no subject terms" early-out. Pure; no I/O.
+ */
+function prepareCoverageScan(source, opts = {}) {
   const minOverlap = Number.isFinite(opts.minOverlap) ? opts.minOverlap : 2;
   const limit = Number.isFinite(opts.limit) ? opts.limit : 5;
 
   const block = frontmatterOf(source?.raw ?? '');
   const sourceTerms = new Set(terms(subjectText(block, source?.basename)));
-  if (sourceTerms.size === 0) return { milestones: [], epics: [], source_terms: [] };
+  if (sourceTerms.size === 0) return null;
 
   const rank = (candidates) =>
     candidates
@@ -162,13 +181,109 @@ export function scanExistingCoverage(vaultRoot, source, opts = {}) {
       .sort((a, b) => b.overlap - a.overlap || a.basename.localeCompare(b.basename))
       .slice(0, limit);
 
+  return { rank, source_terms: [...sourceTerms].sort() };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cloud (`neon`) read tier ([[HS-T6GS-MCPC-EPIC]]).
+//
+// `scanDir` above `readdirSync`es `specs/milestones` and `specs/epics`. In the
+// `neon` tier there may be no vault checkout at all, so that scan is an ENOENT,
+// not a slow path. The cloud twin is `GET /api/specs?type=milestone|epic`
+// (`listSpecsViaConsole`, which follows `next_cursor` so a caller that used to
+// see every FILE still sees every ROW).
+//
+// `scanExistingCoverage` itself is untouched and stays synchronous — it IS the
+// `diskRead` arm, so `promote-diagnose.mjs`'s existing call site keeps working
+// unchanged. The tier is resolved ONCE by the owning handler and threaded in as
+// `deps.tier`, defaulting to `'disk'`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `GET /api/specs` summary rows carry `name`, `tags` and `milestone`, but
+ * `SpecSummary` has NO `summary` field. The disk scan's subject text is
+ * `name + tags + summary`, so cloud-tier ranking sees a slightly smaller term
+ * set. Reported as a warning on the result rather than swallowed — a thinner
+ * signal that looks identical to the full one is how a "no coverage found"
+ * answer mints a milestone the vault already has.
+ */
+export const COVERAGE_CLOUD_FIDELITY_WARNING =
+  'cloud-tier coverage ranking omits each candidate\'s `summary:` text — GET /api/specs summary rows carry name + tags + milestone but no summary field, so overlap is computed from a smaller term set than the disk scan uses';
+
+/** One `GET /api/specs` row → the candidate shape {@link scanDir} produces. */
+function candidateFromRow(row, type) {
+  const basename = row?.basename ?? row?.id ?? null;
+  if (!basename) return null;
+  const status = String(row?.status ?? 'open').trim().toLowerCase();
+  if (!COVERAGE_ELIGIBLE_STATUSES.has(status)) return null;
+  if (row?.archived === true) return null;
+  if (row?.canonical === false) return null;
+  const name = row?.name ?? basename;
+  const tags = Array.isArray(row?.tags) ? row.tags.join(' ') : '';
   return {
-    source_terms: [...sourceTerms].sort(),
-    milestones: rank(scanDir(vaultRoot, ['specs', 'milestones'], 'milestone')),
-    epics: rank(scanDir(vaultRoot, ['specs', 'epics'], 'epic')),
+    type,
+    id: row?.id ?? basename,
+    basename,
+    name,
+    status,
+    milestone: row?.milestone ?? null,
+    // `row.summary` is read opportunistically: absent from SpecSummary today,
+    // free fidelity the day the route projects it.
+    terms: new Set(terms([name, tags, row?.summary ?? ''].join(' '))),
   };
 }
 
+/** List one entity type through the console and shape it into scan candidates. */
+async function scanTypeViaConsole({ consoleFetch, consoleUrl }, type) {
+  const rows = await listSpecsViaConsole({ consoleFetch, consoleUrl, type });
+  return (rows ?? []).map((r) => candidateFromRow(r, type)).filter(Boolean);
+}
+
+/**
+ * Tier-aware {@link scanExistingCoverage}.
+ *
+ * @param {string} vaultRoot
+ * @param {{ raw?: string, basename?: string }} source
+ * @param {{ minOverlap?: number, limit?: number }} [opts]
+ * @param {{ tier?: 'disk'|'neon', consoleUrl?: string, consoleFetch?: Function }} [deps]
+ *
+ * `tier` defaults to `'disk'`, whose arm is `scanExistingCoverage(...)`
+ * verbatim — byte-identical, and no console call is made. A `neon`-tier
+ * console failure surfaces as `ConsoleUnreachableCloudModeError`
+ * (`CONSOLE_UNREACHABLE_CLOUD_MODE`); there is no silent disk fallback.
+ */
+export async function scanExistingCoverageViaTier(vaultRoot, source, opts = {}, deps = {}) {
+  const { tier = 'disk' } = deps;
+  const console_ = resolveConsoleDeps(tier, deps);
+  return readViaSelector({
+    tier,
+    diskRead: () => scanExistingCoverage(vaultRoot, source, opts),
+    neonRead: async () => {
+      const prepared = prepareCoverageScan(source, opts);
+      if (!prepared) {
+        return {
+          milestones: [],
+          epics: [],
+          source_terms: [],
+          cloud_read_warnings: [COVERAGE_CLOUD_FIDELITY_WARNING],
+        };
+      }
+      const [milestones, epics] = await Promise.all([
+        scanTypeViaConsole(console_, 'milestone'),
+        scanTypeViaConsole(console_, 'epic'),
+      ]);
+      return {
+        source_terms: prepared.source_terms,
+        milestones: prepared.rank(milestones),
+        epics: prepared.rank(epics),
+        cloud_read_warnings: [COVERAGE_CLOUD_FIDELITY_WARNING],
+      };
+    },
+    routeLabel: 'GET /api/specs?type=milestone|epic',
+    consoleUrl: console_.consoleUrl,
+  });
+}
+
 /**
  * Extract the source's own `## Fix` section, verbatim. Returns `''` when there is
  * none — a write-up with no Fix section has not been investigated far enough to be

package/vendor/heyspex-mcp/breakdown-source.mjs

@@ -23,7 +23,12 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { listSpecsViaConsole } from './cloud-vault-writes.mjs';
+import { consoleFetch as realConsoleFetch } from './console-transport.mjs';
+import { getConsoleUrl } from './mcp-config.mjs';
 import { getFrontmatterBlock, getScalarField } from './promotion-helpers.mjs';
+import { readViaSelector } from './read-path.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
 
 /**
  * The kinds of document the breakdown stage accepts, and the folder each lives in.
@@ -234,3 +239,269 @@ export function readSourceFrontmatter(record) {
     type: getScalarField(block, 'type') ?? null,
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cloud (`neon`) read tier ([[HS-T6GS-MCPC-EPIC]]).
+//
+// Everything above `readdirSync`es `specs/research` and `specs/diagnoses`. In
+// the `neon` tier there may be NO vault checkout at all, so the folder scan is
+// not slow — it is an ENOENT. The cloud twin of a folder scan is
+// `GET /api/specs?type=…` (`listSpecsViaConsole`, which follows `next_cursor`
+// so a caller that used to see every FILE still sees every ROW).
+//
+// The sync exports above are UNCHANGED and keep working for every existing
+// caller (`promote-diagnose.mjs`, `promote-research.mjs`) — they are the
+// `diskRead` arm verbatim. Tier-aware callers use the async `*ViaTier`
+// siblings, the same convention the rest of the server uses
+// (`loadSpecByIdViaTier`, `handleRecordAlignmentViaTier`, …). The tier is
+// resolved ONCE by the handler that owns the request and threaded in as
+// `deps.tier`; nothing here calls `resolveReadTier()` itself, and `tier`
+// defaults to `'disk'`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Console dependencies for a `neon`-tier read, injectable end to end so a test
+ * can drive a recorder and never open a socket. `getConsoleUrl()` is only
+ * CALLED on the cloud path (it walks the vault resolver), never on disk.
+ */
+export function resolveConsoleDeps(tier, deps = {}) {
+  if (tier !== 'neon') return { consoleFetch: null, consoleUrl: null };
+  return {
+    consoleFetch: deps.consoleFetch ?? realConsoleFetch,
+    consoleUrl: deps.consoleUrl ?? getConsoleUrl(),
+  };
+}
+
+/**
+ * Rebuild a `---`-delimited markdown document from the `{ frontmatter, body }`
+ * pair `GET /api/specs/:id` returns (`SpecDetail` carries no raw markdown).
+ *
+ * Every consumer of `record.raw` in this stage reads it through
+ * `getFrontmatterBlock` / `getScalarField` / a `## Heading` regex
+ * (`readSourceFrontmatter`, `scanExistingCoverage`, `countFixes`,
+ * `causeIsKnown`), so the reconstruction only has to satisfy those: one line
+ * per scalar, a block list per array, `yamlScalar` quoting — the SAME quoter
+ * every disk writer in this package uses, so a value round-trips through
+ * `getScalarField` identically whether it came from a file or from the wire.
+ * Embedded newlines in a scalar are folded to spaces (a single-line YAML
+ * scalar is the only shape `getScalarField` reads on disk either).
+ */
+export function stringifyCloudSpec(frontmatter = {}, body = '') {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(frontmatter ?? {})) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`);
+      for (const item of value) lines.push(`  - ${yamlScalar(item)}`);
+      continue;
+    }
+    if (typeof value === 'object') continue; // no consumer here reads a nested map
+    lines.push(
+      `${key}: ${typeof value === 'string' ? yamlScalar(value.replace(/\r?\n/g, ' ')) : String(value)}`,
+    );
+  }
+  lines.push('---', '');
+  return `${lines.join('\n')}\n${String(body ?? '')}`;
+}
+
+/** `GET /api/specs/:id` → a record shaped exactly like the disk `loadRecord` one. */
+async function fetchCloudRecord({ consoleFetch, consoleUrl }, kind, ref) {
+  const res = await consoleFetch(`/api/specs/${encodeURIComponent(ref)}`);
+  if (res?.status === 404) return null; // not_found / ambiguous_id — a real answer.
+  if (!res?.ok) {
+    throw new Error(
+      `GET /api/specs/${ref} returned ${res?.status}: ${res?.error || JSON.stringify(res?.body ?? {})}`,
+    );
+  }
+  const spec = res.body?.spec;
+  if (!spec) return null;
+  const frontmatter = spec.frontmatter || {};
+  const basename = spec.basename ?? String(spec.relPath ?? ref).split(/[\\/]/).pop().replace(/\.md$/i, '');
+  return {
+    kind: kind ?? spec.type ?? null,
+    basename,
+    // No local file exists in cloud mode — say so rather than hand back a path
+    // that looks writable. `relPath` stays populated for error messages.
+    absPath: null,
+    relPath: spec.relPath ?? null,
+    raw: stringifyCloudSpec(frontmatter, spec.body ?? ''),
+    frontmatter,
+    body: spec.body ?? '',
+    cloud: true,
+    consoleUrl: consoleUrl ?? null,
+  };
+}
+
+/**
+ * The four-step resolution ladder of {@link resolveWithinKind}, run against the
+ * console's spec listing instead of a directory listing. Same steps, same
+ * first-hit-wins order, same "report ambiguity rather than resolve it" rule.
+ *
+ * One fidelity note: step 3 matches the row's `id` only. `SpecSummary` carries
+ * no `file_id`, so a reference given as a bare `file_id:` that differs from
+ * `id:` falls through to step 4 (id-prefix) here where disk would have caught
+ * it at step 3. Both steps resolve the same document when they hit; the
+ * difference is only which step reports it.
+ */
+function resolveWithinKindFromRows(rows, ref) {
+  const named = (rows ?? []).filter((r) => typeof r?.basename === 'string' && r.basename);
+
+  const exact = named.filter((r) => r.basename === ref);
+  if (exact.length === 1) return { row: exact[0] };
+
+  const lowered = ref.toLowerCase();
+  const ciExact = named.filter((r) => r.basename.toLowerCase() === lowered);
+  if (ciExact.length === 1) return { row: ciExact[0] };
+  if (ciExact.length > 1) {
+    return { ambiguous: ciExact.map((r) => r.basename), step: 'case-insensitive basename' };
+  }
+
+  const idHits = named.filter((r) => r.id === ref);
+  if (idHits.length === 1) return { row: idHits[0] };
+  if (idHits.length > 1) {
+    return { ambiguous: idHits.map((r) => r.basename), step: 'frontmatter id' };
+  }
+
+  const prefixHits = named.filter((r) => r.basename.startsWith(`${ref}-`));
+  if (prefixHits.length === 1) return { row: prefixHits[0] };
+  if (prefixHits.length > 1) {
+    return { ambiguous: prefixHits.map((r) => r.basename), step: 'id prefix' };
+  }
+
+  return { miss: true };
+}
+
+/**
+ * Cloud twin of {@link resolveBreakdownSource}. Returns the SAME result shapes
+ * — `{ record }` or one of `INVALID_ARGS` / `SOURCE_ID_AMBIGUOUS` /
+ * `SOURCE_NOT_FOUND` / `SOURCE_TYPE_MISMATCH` — so a caller branches
+ * identically on either tier.
+ */
+async function resolveBreakdownSourceViaConsole(rawRef, opts, deps) {
+  const kinds = Array.isArray(opts.kinds) && opts.kinds.length > 0
+    ? opts.kinds.filter((k) => k in BREAKDOWN_SOURCE_KINDS)
+    : Object.keys(BREAKDOWN_SOURCE_KINDS);
+
+  const ref = normalizeSourceRef(rawRef);
+  if (!ref) {
+    return { error: 'INVALID_ARGS', message: 'a source id or basename is required' };
+  }
+
+  // Every known kind is searched, not only the requested ones — same reason as
+  // the disk path: a hit under a kind the caller did not ask for is the
+  // type-mismatch case, and reporting it as such beats a bare "not found".
+  const hits = [];
+  const ambiguities = [];
+  for (const kind of Object.keys(BREAKDOWN_SOURCE_KINDS)) {
+    const rows = await listSpecsViaConsole({
+      consoleFetch: deps.consoleFetch,
+      consoleUrl: deps.consoleUrl,
+      type: kind,
+    });
+    const found = resolveWithinKindFromRows(rows, ref);
+    if (found.row) hits.push({ kind, row: found.row });
+    else if (found.ambiguous) ambiguities.push({ kind, ...found });
+  }
+
+  if (hits.length > 1) {
+    return {
+      error: 'SOURCE_ID_AMBIGUOUS',
+      message: `${rawRef} resolves to ${hits.length} documents across ${hits.map((h) => h.kind).join(' + ')} — pass the full basename instead`,
+      candidates: hits.map((h) => h.row.basename),
+    };
+  }
+
+  if (hits.length === 0) {
+    if (ambiguities.length > 0) {
+      const first = ambiguities[0];
+      return {
+        error: 'SOURCE_ID_AMBIGUOUS',
+        message: `${rawRef} matches ${first.ambiguous.length} files under ${BREAKDOWN_SOURCE_KINDS[first.kind].dir.join('/')}/ by ${first.step} — pass the exact basename or the frontmatter id: instead`,
+        candidates: first.ambiguous,
+      };
+    }
+    // The type listings only cover research + diagnoses. On disk a document of
+    // some OTHER type sitting in one of those folders is still found and
+    // reported as a type mismatch; here one direct id lookup buys the same
+    // answer, so "you passed a task to the breakdown stage" keeps reading as
+    // that instead of a misleading "not found".
+    const other = await fetchCloudRecord(deps, null, ref);
+    if (other?.kind && !(String(other.kind).toLowerCase() in BREAKDOWN_SOURCE_KINDS)) {
+      return {
+        error: 'SOURCE_TYPE_MISMATCH',
+        message: `${rawRef} resolved to ${other.relPath ?? other.basename}, which is \`type: ${String(other.kind).toLowerCase()}\` — the breakdown stage accepts a research doc or a bug write-up`,
+        resolved_basename: other.basename,
+        resolved_type: String(other.kind).toLowerCase(),
+      };
+    }
+    return {
+      error: 'SOURCE_NOT_FOUND',
+      message: `${rawRef} not found under ${kinds.map((k) => BREAKDOWN_SOURCE_KINDS[k].dir.join('/') + '/').join(' or ')} (tried exact basename, case-insensitive basename, frontmatter id:, and id-prefix match)`,
+      searched_kinds: kinds,
+    };
+  }
+
+  const { kind, row } = hits[0];
+  const record = await fetchCloudRecord(deps, kind, row.id ?? row.basename);
+  if (!record) {
+    return {
+      error: 'SOURCE_NOT_FOUND',
+      message: `${rawRef} was listed by GET /api/specs?type=${kind} as ${row.basename} but GET /api/specs/${row.id ?? row.basename} did not return it`,
+      searched_kinds: kinds,
+    };
+  }
+
+  // The document's own `type:` wins, exactly as on disk; the listing's `type`
+  // is the fallback when the document declares none.
+  const declared = String(record.frontmatter?.type ?? '').trim().toLowerCase();
+  if (declared) {
+    if (!(declared in BREAKDOWN_SOURCE_KINDS)) {
+      return {
+        error: 'SOURCE_TYPE_MISMATCH',
+        message: `${rawRef} resolved to ${record.relPath ?? record.basename}, which is \`type: ${declared}\` — the breakdown stage accepts a research doc or a bug write-up`,
+        resolved_basename: record.basename,
+        resolved_type: declared,
+      };
+    }
+    record.kind = declared;
+  } else {
+    record.kind = kind;
+  }
+
+  if (!kinds.includes(record.kind)) {
+    return {
+      error: 'SOURCE_TYPE_MISMATCH',
+      message: `${rawRef} resolved to ${record.relPath ?? record.basename}, a ${BREAKDOWN_SOURCE_KINDS[record.kind].label} — this call expects ${kinds.map((k) => BREAKDOWN_SOURCE_KINDS[k].label).join(' or ')}`,
+      resolved_basename: record.basename,
+      resolved_type: record.kind,
+    };
+  }
+
+  return { record };
+}
+
+/**
+ * Tier-aware {@link resolveBreakdownSource}.
+ *
+ * @param {string} vaultRoot
+ * @param {string} rawRef
+ * @param {{ kinds?: string[] }} [opts]
+ * @param {{ tier?: 'disk'|'neon', consoleUrl?: string, consoleFetch?: Function }} [deps]
+ *
+ * `tier` defaults to `'disk'`, whose arm is `resolveBreakdownSource(...)`
+ * verbatim — byte-identical, and no console call is made. A `neon`-tier
+ * console failure surfaces as `ConsoleUnreachableCloudModeError`
+ * (`CONSOLE_UNREACHABLE_CLOUD_MODE`), never as a silent fall back to a disk
+ * copy that may not exist.
+ */
+export async function resolveBreakdownSourceViaTier(vaultRoot, rawRef, opts = {}, deps = {}) {
+  const { tier = 'disk' } = deps;
+  const console_ = resolveConsoleDeps(tier, deps);
+  return readViaSelector({
+    tier,
+    diskRead: () => resolveBreakdownSource(vaultRoot, rawRef, opts),
+    neonRead: () => resolveBreakdownSourceViaConsole(rawRef, opts, console_),
+    routeLabel: 'GET /api/specs?type=research|diagnose',
+    consoleUrl: console_.consoleUrl,
+  });
+}

package/vendor/heyspex-mcp/breakdown-writer.mjs

@@ -26,7 +26,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { collectOccupiedKeysEitherKind, allocateFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { allocateFileKey, parseSpecId } from './spec-id-lib.mjs';
 import { listVaultPillars, resolvePillar } from './promote-research.mjs';
 import {
   appendChangeLogRow,
@@ -250,12 +250,32 @@ export function requireResolvableMilestone(vaultRoot, milestoneRef) {
  * @returns `{ spawned, writes }` on success, or `{ error, message, ... }`. Nothing is
  * written until every gate has passed; the commit itself rolls back as a unit.
  */
-export function executeBreakdownWrites({ vaultRoot, source, sourceFrontmatter, ladder, placement, args = {}, deps = {} }) {
+export function executeBreakdownWrites({ vaultRoot, source, sourceFrontmatter, ladder, placement, occupiedKeys, args = {}, deps = {} }) {
   const now = (deps.clock ?? isoNow)();
   const today = now.slice(0, 10);
   const sourceBasename = source.basename;
   const familyKey = inheritedFamilyKey(sourceFrontmatter, sourceBasename) ?? 'BFIX';
-  const occupied = collectOccupiedKeysEitherKind(vaultRoot);
+  // TIER-AWARE OCCUPANCY, SUPPLIED BY THE CALLER ([[HS-FJWL]]). This used to be
+  // `collectOccupiedKeysEitherKind(vaultRoot)` inline — a `specs/**` walk that
+  // is complete on the disk tier and blind on the cloud tier, where a filed
+  // spec has a Neon row and no local `.md`. A file key is the unique per-file
+  // identity under Naming V3, so minting against a stale local clone re-issues
+  // a live id. The resolution is the CALLER's (promote-diagnose.mjs), which is
+  // async and can reach the console; this writer stays synchronous.
+  //
+  // No disk fallback when it is missing: a silent default is exactly the blind
+  // scan this fix removes, so an unsupplied set refuses the whole breakdown.
+  if (!(occupiedKeys instanceof Set)) {
+    return {
+      error: 'OCCUPANCY_NOT_RESOLVED',
+      message:
+        'executeBreakdownWrites requires a resolved `occupiedKeys` Set ([[HS-FJWL]]) — the ' +
+        'caller resolves it for the active read tier via collectOccupiedKeysEitherKindViaTier. ' +
+        'Refusing to fall back to a local vault scan, which is blind to cloud-only specs and ' +
+        'would mint a duplicate file key.',
+    };
+  }
+  const occupied = new Set(occupiedKeys);
   const mintKey = () => {
     const key = allocateFileKey(occupied, { randomUnit: deps.randomUnit });
     occupied.add(key);