heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/promote-capture.mjs

@@ -52,6 +52,7 @@ import { scoreSufficiency } from '../../dev-factory/lib/sufficiency-score.mjs';
 // capture-focus.mjs deep-dive reader rather than a third regex copy.
 import { extractCaptureExpandedConceptFromBody } from './capture-focus.mjs';
 import {
+  collectOccupiedKeysEitherKind,
   mintFileKey,
   mintFamilyKey,
   parseSpecId,
@@ -82,7 +83,27 @@ import {
   bumpUpdated,
   appendChangeLogRow,
   commitWrites,
+  fetchSpecRecordViaConsole,
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
 } from './promotion-helpers.mjs';
+// Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+// The write-side twin of read-path.mjs: in `cloud` write mode a create becomes
+// POST /api/specs (server-minted id + family + filename) and an edit becomes
+// PUT /api/specs/:id. Nothing here opens a socket itself — `consoleFetch` is
+// the same injected dep the cloud-tier READS already use.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+// Cloud-tier read selector ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]) —
+// reused verbatim, never copied. `readViaSelector` picks disk vs neon; the
+// neon branch below fetches through `fetchSpecRecordViaConsole` (an injected
+// consoleFetch, not read-path.mjs's own transport) so tests never open a
+// socket, matching this file's existing deps-injection convention.
+import { readViaSelector } from './read-path.mjs';
 // Reuse the exact same placeholder-count logic RESEARCH_STILL_STUB uses to
 // refuse `heyspex_promote_research` on a stub research doc — proactively
 // surfaced here at creation/extension time instead of only reactively at
@@ -99,6 +120,15 @@ import { findUnresolvedResearchPlaceholders } from './promote-research.mjs';
 // vendor/heyspex-mcp/spec-id-lib.mjs (`parseSpecId`).
 // ─────────────────────────────────────────────────────────────────────────────
 
+// Placeholders the CLOUD path feeds the shared content builders in place of a
+// locally-minted id / file key / family key. They never reach the console:
+// `stripServerMintedFields` removes `id:` and `file_id:` from the request, and
+// an un-inheritable `family:` is deleted alongside them. Their only job is to
+// keep the builder's template well-formed so its BODY is byte-for-byte the
+// markdown the disk path would have written.
+const CLOUD_PENDING_ID = 'HS-PENDING';
+const CLOUD_PENDING_KEY = 'PENDING';
+
 /** True when `id` (either ordering) parses to a spec with the given type label. */
 function hasTypeLabel(id, label) {
   const p = parseSpecId(id);
@@ -295,6 +325,38 @@ function findResearchByIdLocal(vaultRoot, researchId) {
   return null;
 }
 
+/**
+ * Cloud-tier sibling of {@link findCaptureByIdLocal} (HS-KR16). `tier`,
+ * `consoleUrl` and `consoleFetch` are resolved ONCE per handler call
+ * (`handlePromoteCapture` in capture-tools.mjs) and threaded down here —
+ * never re-resolved inside this helper.
+ */
+async function findCaptureByIdViaTier(vaultRoot, captureId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findCaptureByIdLocal(vaultRoot, captureId),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, captureId),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+/**
+ * Cloud-tier sibling of {@link findResearchByIdLocal} (HS-KR16). Same
+ * contract: a bare record, or `null` on a genuine not-found.
+ */
+async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, researchId),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 function findResearchByBasename(vaultRoot, basename) {
   const absPath = join(vaultRoot, 'specs', 'research', `${basename}.md`);
   if (!existsSync(absPath)) return null;
@@ -652,6 +714,26 @@ async function runExecutePhase(args, ctx, deps) {
   const now = (deps?.clock ?? isoNow)();
   const today = now.slice(0, 10);
   const author = 'promote-capture (agent)';
+  // Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+  // Resolved ONCE by the caller (`resolveVaultWriteMode()`) and threaded in on
+  // `deps`; absent (every pre-existing caller and test) it is `local`, so the
+  // disk path below is byte-identical to before this task.
+  //
+  // CREATE FIRST, LINK SECOND: on disk the flow stages every write and commits
+  // them as one transaction, because it mints the research filename itself. In
+  // cloud mode the console mints the id, the family and the filename, so the
+  // basename each capture's `promoted_to:` / `informs_research:` links to is
+  // only knowable AFTER `POST /api/specs` returns. The order therefore
+  // inverts: POST the research doc, take its basename, then PUT each capture.
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  // Steps that have ALREADY landed in the cloud vault, in order. There is no
+  // rollback (the console has no un-create) — on a mid-sequence failure this
+  // list is what the caller is told actually happened.
+  const cloudCompleted = [];
+  // PUTs queued while the primary create is being resolved; flushed at the
+  // commit point below, in order.
+  const cloudUpdates = [];
 
   // ── Resolve / allocate target research basename + path ────────────────────
   let researchBasename;
@@ -672,28 +754,49 @@ async function runExecutePhase(args, ctx, deps) {
     // (ctx.captures[0]) just below. No fallback: era-3 `id:` keys onto the
     // file key alone, so a shared family can never collide.
     const primaryCapture = ctx.captures[0] ?? null;
-    researchFamilyKey =
-      (primaryCapture
-        ? inheritedFamilyKey(
-            primaryCapture.frontmatter?.id ?? null,
-            primaryCapture.frontmatter,
-            primaryCapture.basename,
-          )
-        : null) ?? mintFamilyKey(ctx.vaultRoot, { randomUnit: deps?.randomUnit });
-    // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
-    // and (V3) the anchor for `id:` itself ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]).
-    researchFileKey = mintFileKey(ctx.vaultRoot, { randomUnit: deps?.randomUnit });
-    researchId = `HS-${researchFileKey}`;
-    const outlineName = args.accepted_outline?.name ?? args.new_research_name;
-    const slug = deriveSlug(outlineName);
-    researchBasename = `${researchId}-${researchFamilyKey}-RES-${slug}`;
-    researchAbsPath = join(
-      ctx.vaultRoot,
-      'specs',
-      'research',
-      `${researchBasename}.md`,
-    );
-    researchRelPath = join('specs', 'research', `${researchBasename}.md`);
+    const inherited = primaryCapture
+      ? inheritedFamilyKey(
+          primaryCapture.frontmatter?.id ?? null,
+          primaryCapture.frontmatter,
+          primaryCapture.basename,
+        )
+      : null;
+    if (writeMode === 'cloud') {
+      // NOTHING is minted locally in cloud mode (AC3): `mintFileKey` /
+      // `mintFamilyKey` both derive their answer by scanning the vault for
+      // occupied keys, and in a file-less vault that scan sees an EMPTY set —
+      // so a key minted here can collide with one the cloud vault already
+      // holds. The console mints the file key, the family and the filename
+      // inside `createSpec`. An INHERITED family is still passed through (it
+      // is read off the source capture, not minted, and `createSpec` honours
+      // an explicit `family:` over parent inheritance); with no inheritable
+      // family the field is simply omitted and the server picks one.
+      researchFamilyKey = inherited ?? null;
+      researchFileKey = null;
+      researchId = null;
+      researchBasename = null;
+      researchAbsPath = null;
+      researchRelPath = null;
+    } else {
+      researchFamilyKey =
+        inherited ?? mintFamilyKey(ctx.vaultRoot, { randomUnit: deps?.randomUnit });
+      // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+      // and (V3) the anchor for `id:` itself ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]).
+      // Disk occupancy ([[HS-FJWL]]): the `writeMode === 'cloud'` branch above
+      // mints NOTHING locally, so this is the local-vault branch only.
+      researchFileKey = mintFileKey(collectOccupiedKeysEitherKind(ctx.vaultRoot), { randomUnit: deps?.randomUnit });
+      researchId = `HS-${researchFileKey}`;
+      const outlineName = args.accepted_outline?.name ?? args.new_research_name;
+      const slug = deriveSlug(outlineName);
+      researchBasename = `${researchId}-${researchFamilyKey}-RES-${slug}`;
+      researchAbsPath = join(
+        ctx.vaultRoot,
+        'specs',
+        'research',
+        `${researchBasename}.md`,
+      );
+      researchRelPath = join('specs', 'research', `${researchBasename}.md`);
+    }
     researchCreated = true;
 
     // Sanity: accepted_outline is required to actually create the file.
@@ -775,10 +878,14 @@ async function runExecutePhase(args, ctx, deps) {
     // interim `JTBD (job-to-be-done):` leading block, when present.
     const jtbdSeed =
       ctx.captures.length > 0 ? extractCaptureJtbd(ctx.captures[0].raw) : '';
+    // In cloud mode the id/file key/family placeholders below are stripped
+    // before the request goes out (`stripServerMintedFields`) — the builder is
+    // reused verbatim rather than forked so the BODY the console stores is the
+    // same markdown the disk path writes.
     const newContent = buildResearchStubContent(
-      researchId,
-      researchFileKey,
-      researchFamilyKey,
+      researchId ?? CLOUD_PENDING_ID,
+      researchFileKey ?? CLOUD_PENDING_KEY,
+      researchFamilyKey ?? CLOUD_PENDING_KEY,
       outlineForCreate,
       captureBasenames,
       enhancesBasename,
@@ -786,7 +893,42 @@ async function runExecutePhase(args, ctx, deps) {
       suggestedType,
       jtbdSeed,
     );
-    writes.push({ kind: 'create', absPath: researchAbsPath, content: newContent });
+    if (writeMode === 'cloud') {
+      // ── CREATE FIRST ────────────────────────────────────────────────────
+      const { frontmatter, body } = splitRawSpecForConsole(newContent);
+      const cleaned = stripServerMintedFields(frontmatter);
+      if (!researchFamilyKey) delete cleaned.family;
+      let created;
+      try {
+        created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: 'research',
+          name: outlineForCreate.name,
+          frontmatter: cleaned,
+          body,
+          actingAgent: deps?.actingAgent ?? null,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'create', type: 'research', name: outlineForCreate.name },
+          completed: cloudCompleted,
+        });
+      }
+      // ── …LINK SECOND: every sibling write below now has a real basename.
+      researchId = created.specId;
+      researchBasename = created.basename;
+      researchRelPath = created.relPath;
+      researchAbsPath = null;
+      cloudCompleted.push({
+        kind: 'create',
+        type: 'research',
+        spec_id: created.specId,
+        basename: created.basename,
+        rel_path: created.relPath,
+      });
+    } else {
+      writes.push({ kind: 'create', absPath: researchAbsPath, content: newContent });
+    }
     finalResearchContent = newContent;
   } else {
     const updated = buildUpdatedResearchContent(
@@ -800,11 +942,23 @@ async function runExecutePhase(args, ctx, deps) {
       },
     );
     if (updated.changed) {
-      writes.push({
-        kind: 'update',
-        absPath: researchAbsPath,
-        content: updated.content,
-      });
+      if (writeMode === 'cloud') {
+        // The target research already exists, so its basename is already
+        // known — this PUT carries no create-first dependency and is simply
+        // queued with the capture PUTs below.
+        cloudUpdates.push({
+          label: 'research',
+          specId: researchId,
+          basename: researchBasename,
+          content: updated.content,
+        });
+      } else {
+        writes.push({
+          kind: 'update',
+          absPath: researchAbsPath,
+          content: updated.content,
+        });
+      }
     }
     finalResearchContent = updated.changed ? updated.content : ctx.targetResolution.research.raw;
   }
@@ -842,15 +996,28 @@ async function runExecutePhase(args, ctx, deps) {
       promoted_to_set: updated.setPromotedTo,
     });
     if (updated.changed) {
-      writes.push({
-        kind: 'update',
-        absPath: c.absPath,
-        content: updated.content,
-      });
+      if (writeMode === 'cloud') {
+        cloudUpdates.push({
+          label: 'capture',
+          specId: c.frontmatter?.id ?? c.basename,
+          basename: c.basename,
+          content: updated.content,
+        });
+      } else {
+        writes.push({
+          kind: 'update',
+          absPath: c.absPath,
+          content: updated.content,
+        });
+      }
     }
   }
 
-  if (writes.length === 0) {
+  const nothingToWrite =
+    writeMode === 'cloud'
+      ? cloudCompleted.length === 0 && cloudUpdates.length === 0
+      : writes.length === 0;
+  if (nothingToWrite) {
     // Idempotent no-op: research already references every input capture and
     // each capture already references the research. Surface this clearly.
     return {
@@ -871,13 +1038,41 @@ async function runExecutePhase(args, ctx, deps) {
   }
 
   // ── Commit ────────────────────────────────────────────────────────────────
-  const commitResult = commitWrites(writes);
-  if (!commitResult.ok) {
-    return {
-      error: 'WRITE_FAILED',
-      message: commitResult.error?.message ?? 'unknown write failure',
-      rollback_error: commitResult.error?.rollbackError,
-    };
+  if (writeMode === 'cloud') {
+    // Flush the queued PUTs IN ORDER, stopping at the first failure. No
+    // rollback: the error result names the failing step and lists what landed.
+    for (const u of cloudUpdates) {
+      const { frontmatter, body } = splitRawSpecForConsole(u.content);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: u.specId,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: u.label,
+          spec_id: res.specId,
+          basename: res.basename ?? u.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: u.label, spec_id: u.specId, basename: u.basename },
+          completed: cloudCompleted,
+        });
+      }
+    }
+  } else {
+    const commitResult = commitWrites(writes);
+    if (!commitResult.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message: commitResult.error?.message ?? 'unknown write failure',
+        rollback_error: commitResult.error?.rollbackError,
+      };
+    }
   }
 
   return {
@@ -887,7 +1082,11 @@ async function runExecutePhase(args, ctx, deps) {
     research_path: researchRelPath,
     research_created: researchCreated,
     captures: capturePromotionResults,
-    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    ...(writeMode === 'cloud' ? { write_mode: 'cloud' } : {}),
+    writes:
+      writeMode === 'cloud'
+        ? cloudCompleted.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id }))
+        : writes.map((w) => ({ kind: w.kind, path: w.absPath })),
     // TARGET_RESEARCH_CLOSED only occurs on the existing-research branch
     // (researchCreated === false). Family inheritance on the NEW-research
     // branch no longer has a fallback case to warn about (era-3 minting —
@@ -919,6 +1118,19 @@ export async function executePromoteCapture(vaultRoot, args = {}, deps = {}) {
   const validationError = validateInputShape(args);
   if (validationError) return validationError;
 
+  // Cloud-tier reads ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]):
+  // `deps.tier` is resolved ONCE by the caller (`handlePromoteCapture` in
+  // capture-tools.mjs, via `resolveReadTier()`) and threaded down — never
+  // re-resolved here. Absent (every pre-existing caller/test) defaults to
+  // `disk`, so disk-tier behavior is byte-identical to before this task.
+  // Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+  // `deps.writeMode` is resolved ONCE by the caller (`resolveVaultWriteMode()`)
+  // exactly like `deps.tier`, and defaults to `local` so every pre-existing
+  // caller/test writes to disk unchanged. It is consumed in `runExecutePhase`.
+  const tier = deps.tier ?? 'disk';
+  const consoleUrl = deps.consoleUrl;
+  const consoleFetchDep = deps.consoleFetch;
+
   // 1. Load every input capture; fail on first miss. Ids collapse to the
   // short stored form first (display long `HS-XV4W-HV6H` → `HS-XV4W`) so the
   // basename-prefix and frontmatter-id matches inside the loader hit for any
@@ -926,7 +1138,11 @@ export async function executePromoteCapture(vaultRoot, args = {}, deps = {}) {
   const captures = [];
   for (const rawCaptureId of args.capture_ids) {
     const captureId = shortLookupIdOf(rawCaptureId) ?? rawCaptureId;
-    const capture = findCaptureByIdLocal(vaultRoot, captureId);
+    const capture = await findCaptureByIdViaTier(vaultRoot, captureId, {
+      tier,
+      consoleUrl,
+      consoleFetch: consoleFetchDep,
+    });
     if (!capture) {
       return {
         error: 'CAPTURE_NOT_FOUND',
@@ -1008,9 +1224,10 @@ export async function executePromoteCapture(vaultRoot, args = {}, deps = {}) {
   if (args.target_research === 'NEW') {
     targetResolution = { mode: 'new' };
   } else {
-    const research = findResearchByIdLocal(
+    const research = await findResearchByIdViaTier(
       vaultRoot,
       shortLookupIdOf(args.target_research) ?? args.target_research,
+      { tier, consoleUrl, consoleFetch: consoleFetchDep },
     );
     if (!research) {
       return {
@@ -1190,7 +1407,19 @@ export async function executePromoteCaptureToDiagnose(vaultRoot, args = {}, deps
   const severityRaw = typeof args.severity === 'string' ? args.severity.trim().toLowerCase() : 'warning';
   const severity = VALID_DIAGNOSE_SEVERITIES.has(severityRaw) ? severityRaw : 'warning';
 
-  const capture = findCaptureByIdLocal(vaultRoot, captureId);
+  // Same once-per-call resolution rule as executePromoteCapture: `tier` and
+  // `writeMode` come in on `deps`, already resolved, and default to
+  // `disk`/`local` so every pre-existing caller is byte-identical.
+  const tier = deps?.tier ?? 'disk';
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  const cloudCompleted = [];
+
+  const capture = await findCaptureByIdViaTier(vaultRoot, captureId, {
+    tier,
+    consoleUrl: deps?.consoleUrl,
+    consoleFetch: deps?.consoleFetch,
+  });
   if (!capture) {
     return { error: 'CAPTURE_NOT_FOUND', message: `capture ${captureId} not found under specs/captures/` };
   }
@@ -1207,23 +1436,73 @@ export async function executePromoteCaptureToDiagnose(vaultRoot, args = {}, deps
 
   // A capture→diagnose promotion has no documented family-inheritance hop
   // (unlike capture→research) — mints a fresh family, same as any other
-  // parentless spec.
-  const familyKey = mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  // parentless spec. In CLOUD mode nothing is minted here at all: the console
+  // mints the file key, the family and the filename (AC3).
+  const familyKey =
+    writeMode === 'cloud' ? null : mintFamilyKey(vaultRoot, { randomUnit: deps?.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: deps?.randomUnit });
-  const diagnoseId = `HS-${fileKey}`;
+  // Disk occupancy ([[HS-FJWL]]): guarded by the same `writeMode === 'cloud'`
+  // ternary as the family above — in cloud mode nothing is minted here at all.
+  const fileKey =
+    writeMode === 'cloud'
+      ? null
+      : mintFileKey(collectOccupiedKeysEitherKind(vaultRoot), { randomUnit: deps?.randomUnit });
   const slug = deriveSlug(name);
-  const diagnoseBasename = `${diagnoseId}-${familyKey}-DIAG-${slug}`;
-  const diagnoseRelPath = `specs/diagnoses/${diagnoseBasename}.md`;
-  const diagnoseAbsPath = join(vaultRoot, 'specs', 'diagnoses', `${diagnoseBasename}.md`);
+  let diagnoseId = fileKey ? `HS-${fileKey}` : null;
+  let diagnoseBasename = fileKey ? `${diagnoseId}-${familyKey}-DIAG-${slug}` : null;
+  let diagnoseRelPath = fileKey ? `specs/diagnoses/${diagnoseBasename}.md` : null;
+  const diagnoseAbsPath = fileKey
+    ? join(vaultRoot, 'specs', 'diagnoses', `${diagnoseBasename}.md`)
+    : null;
+
+  const diagnoseContent = buildDiagnoseContent(
+    diagnoseId ?? CLOUD_PENDING_ID,
+    fileKey ?? CLOUD_PENDING_KEY,
+    familyKey ?? CLOUD_PENDING_KEY,
+    name,
+    severity,
+    capture.basename,
+    coreIdea,
+    now,
+  );
 
   const writes = [];
-  writes.push({
-    kind: 'create',
-    absPath: diagnoseAbsPath,
-    content: buildDiagnoseContent(diagnoseId, fileKey, familyKey, name, severity, capture.basename, coreIdea, now),
-  });
+  if (writeMode === 'cloud') {
+    // CREATE FIRST — the capture's `promoted_to:` links to the basename this
+    // POST returns, so it cannot be built until the POST has answered.
+    const { frontmatter, body } = splitRawSpecForConsole(diagnoseContent);
+    const cleaned = stripServerMintedFields(frontmatter);
+    delete cleaned.family; // never inherited on this hop; let the server mint it
+    let created;
+    try {
+      created = await createSpecViaConsole({
+        ...cloudDeps,
+        type: 'diagnose',
+        name,
+        frontmatter: cleaned,
+        body,
+        actingAgent: deps?.actingAgent ?? null,
+      });
+    } catch (err) {
+      return cloudWriteFailureResult(err, {
+        step: { kind: 'create', type: 'diagnose', name },
+        completed: cloudCompleted,
+      });
+    }
+    diagnoseId = created.specId;
+    diagnoseBasename = created.basename;
+    diagnoseRelPath = created.relPath;
+    cloudCompleted.push({
+      kind: 'create',
+      type: 'diagnose',
+      spec_id: created.specId,
+      basename: created.basename,
+      rel_path: created.relPath,
+    });
+  } else {
+    writes.push({ kind: 'create', absPath: diagnoseAbsPath, content: diagnoseContent });
+  }
 
   const captureUpdate = buildUpdatedCaptureContentForDiagnose(capture.raw, {
     diagnoseBasename,
@@ -1232,16 +1511,50 @@ export async function executePromoteCaptureToDiagnose(vaultRoot, args = {}, deps
     author: 'promote-capture (agent)',
   });
   if (captureUpdate.changed) {
-    writes.push({ kind: 'update', absPath: capture.absPath, content: captureUpdate.content });
+    if (writeMode === 'cloud') {
+      // …LINK SECOND.
+      const { frontmatter, body } = splitRawSpecForConsole(captureUpdate.content);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: getScalarField(getFrontmatterBlock(capture.raw)?.block ?? '', 'id') ?? capture.basename,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: 'capture',
+          spec_id: res.specId,
+          basename: res.basename ?? capture.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'capture', basename: capture.basename },
+          completed: cloudCompleted,
+        });
+      }
+    } else {
+      writes.push({ kind: 'update', absPath: capture.absPath, content: captureUpdate.content });
+    }
   }
 
-  const commitResult = commitWrites(writes);
-  if (!commitResult.ok) {
-    return {
-      error: 'WRITE_FAILED',
-      message: commitResult.error?.message ?? 'unknown write failure',
-      rollback_error: commitResult.error?.rollbackError,
-    };
+  if (writeMode !== 'cloud') {
+    const commitResult = commitWrites(writes);
+    if (!commitResult.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message: commitResult.error?.message ?? 'unknown write failure',
+        rollback_error: commitResult.error?.rollbackError,
+      };
+    }
+  }
+
+  // By this point every path (local mint or cloud create-first) has replaced
+  // the transitional fileKey-pending null with a real id — narrow it here so
+  // callers (e.g. `promote-diagnose.ts`) see `string`, not `string | null`.
+  if (!diagnoseId || !diagnoseBasename || !diagnoseRelPath) {
+    throw new Error('promoteCaptureToDiagnose: missing diagnose id after promotion (unexpected)');
   }
 
   return {
@@ -1257,7 +1570,11 @@ export async function executePromoteCaptureToDiagnose(vaultRoot, args = {}, deps
       informs_diagnose_added: captureUpdate.changed,
       promoted_to_set: captureUpdate.setPromotedTo,
     },
-    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    ...(writeMode === 'cloud' ? { write_mode: 'cloud' } : {}),
+    writes:
+      writeMode === 'cloud'
+        ? cloudCompleted.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id }))
+        : writes.map((w) => ({ kind: w.kind, path: w.absPath })),
     human_review_required: false,
   };
 }
@@ -1266,6 +1583,8 @@ export const __testables = {
   validateInputShape,
   findCaptureByIdLocal,
   findResearchByIdLocal,
+  findCaptureByIdViaTier,
+  findResearchByIdViaTier,
   findResearchByBasename,
   collectOccupiedResearchIds,
   collectOccupiedDiagnoseIds,