heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/read-path.mjs

@@ -46,16 +46,16 @@
  * import) so tests can stub scripts/lib/dev-mode.mjs and prove the verdict
  * comes from `resolveDevMode` itself, not from string-matching this file.
  */
-import { dirname, join } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getActiveConfig } from './vault-resolve.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { join } from 'node:path';
+import { importDevModeCore } from './dev-mode-core.mjs';
 // THIS PACKAGE's own root (vendor/heyspex-mcp/read-path.mjs -> two levels
 // up) — repo root in the monorepo, `node_modules/heyspex` in a packed
 // install. Used to locate this package's OWN sibling code (dev-mode.mjs);
-// see the module doc above for why this is never the vault root.
-const PACKAGE_ROOT = join(__dirname, '..', '..');
+// see the module doc above for why this is never the vault root. Derived in
+// ONE place (package-root.mjs) so a bundler bakes one build-machine path
+// into the console's remote-MCP chunk instead of one per module.
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { getActiveConfig } from './vault-resolve.mjs';
 
 /**
  * Resolve the VAULT root via the same shared 5-tier resolver every other MCP
@@ -78,8 +78,11 @@ export function resolveVaultRoot() {
 
 /** Real loader: dynamic-imports the shared dev-mode core from THIS PACKAGE's own root. */
 export async function loadRealDevMode() {
-  const coreUrl = pathToFileURL(join(PACKAGE_ROOT, 'scripts', 'lib', 'dev-mode.mjs')).href;
-  return import(coreUrl);
+  // Path candidate first (stdio / packed installs), then the static
+  // specifier a bundler can trace — see dev-mode-core.mjs. In a bundled
+  // deployment `import.meta.url` no longer points at a real checkout, so the
+  // path-built URL misses and the fallback is what actually loads.
+  return importDevModeCore([join(PACKAGE_ROOT, 'scripts', 'lib', 'dev-mode.mjs')]);
 }
 
 /**
@@ -111,6 +114,23 @@ export async function resolveReadTier({ env, homeDir, loadDevMode = loadRealDevM
   return resolved.readTier;
 }
 
+/**
+ * resolveVaultWriteMode({ env, homeDir, loadDevMode? }) -> "local" | "cloud"
+ *
+ * The write-side twin of {@link resolveReadTier}: whatever
+ * `resolveDevMode(...).vaultWriteMode` says — `local` only for dev mode with
+ * local reliance, `cloud` for prod and for dev with cloud reliance. A
+ * create-flow that writes the vault directly (save_research) consults THIS
+ * before touching disk, so a cloud-reliant session never leaves a file the
+ * console's index has never heard of (the split-brain a disk write in cloud
+ * mode produces). Same injectable loader as the read tier.
+ */
+export async function resolveVaultWriteMode({ env, homeDir, loadDevMode = loadRealDevMode } = {}) {
+  const mod = await loadDevMode();
+  const resolved = mod.resolveDevMode({ env, homeDir });
+  return resolved.vaultWriteMode === 'local' ? 'local' : 'cloud';
+}
+
 /**
  * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl })
  *

package/vendor/heyspex-mcp/receipt-shape.mjs

@@ -0,0 +1,146 @@
+// The read-back receipt envelope for `hs` verbs that live in plain .mjs under
+// vendor/heyspex-mcp/ and so cannot import the TypeScript receipt
+// (spex-console/src/lib/cli/receipt.ts, [[HS-STCY-WW9R-TASK-add-a-shared-receipt-that-reads-back]]).
+// Same envelope, same words: `{ local, cloud, verified, agree, diffs, changed,
+// failed?, retry? }`, a two-column "local (this machine) | cloud (console)"
+// table and one "Result:" line with the same anchors (verified / unverified /
+// disagree / failed). Only the side fields differ per verb, so a verb passes a
+// row table naming which local field and which cloud field each row shows
+// and whether the row must agree. `hs login` is the first user
+// ([[HS-CRNE-WW9R-TASK-give-hs-install-and-hs-login-the]], epic
+// [[HS-L6HW-WW9R-EPIC-one-http-transport-and-measured]] invariant 6).
+//
+// Pure: no IO, never throws.
+
+/** `EXIT.ACCOUNT_MISMATCH` in spex-console/src/lib/cli/control-shared.ts — the console confirmed another account. */
+export const EXIT_ACCOUNT_MISMATCH = 20;
+/** `EXIT.RECEIPT_DISAGREE` in control-shared.ts — both sides were read back and disagree. */
+export const EXIT_RECEIPT_DISAGREE = 21;
+
+/**
+ * @typedef {{ read: boolean, reason?: string, [field: string]: unknown }} ReceiptSide
+ * @typedef {{ label: string, local?: string, cloud?: string, compare?: boolean }} ReceiptRow
+ *   One table row: the local side's field, the cloud side's field, and
+ *   whether the two must be equal for `agree` (a diff is named by `label`).
+ */
+
+/** A side that was not read back, with the reason. */
+export function unreadSide(reason) {
+  return { read: false, reason };
+}
+
+const META = new Set(['read', 'reason']);
+
+function valueOf(side, field) {
+  if (!side || !field) return null;
+  const v = side[field];
+  return v === undefined ? null : v;
+}
+
+/**
+ * Build the receipt from the two read-backs.
+ *  - `verified`: both sides were read back;
+ *  - `diffs`: every `compare` row whose two values differ (only when verified);
+ *  - `agree`: verified with no diffs;
+ *  - `changed`: per side, every field that differs from the `before` read of
+ *    that side (`[]` on an unchanged re-run; a side with no before read, or
+ *    not read after, contributes nothing).
+ * @param {{ local: ReceiptSide | null, cloud: ReceiptSide | null, rows: ReceiptRow[],
+ *   before?: { local?: ReceiptSide | null, cloud?: ReceiptSide | null },
+ *   failed?: { side: 'local' | 'cloud', reason?: string }, retry?: string }} input
+ */
+export function buildSidesReceipt({ local, cloud, rows, before = {}, failed, retry }) {
+  const l = local ?? unreadSide('not read back');
+  const c = cloud ?? unreadSide('not read back');
+  if (failed?.reason) (failed.side === 'cloud' ? c : l).reason = failed.reason;
+  const verified = l.read === true && c.read === true;
+
+  const diffs = [];
+  if (verified) {
+    for (const row of rows) {
+      if (!row.compare) continue;
+      const lv = valueOf(l, row.local);
+      const cv = valueOf(c, row.cloud);
+      if (lv !== cv) diffs.push({ field: row.label, local: lv, cloud: cv });
+    }
+  }
+
+  const changed = [];
+  for (const [name, after] of [['local', l], ['cloud', c]]) {
+    const prior = before[name];
+    if (!prior?.read || !after.read) continue;
+    const fields = new Set([...Object.keys(prior), ...Object.keys(after)].filter((f) => !META.has(f)));
+    for (const field of fields) {
+      const from = valueOf(prior, field);
+      const to = valueOf(after, field);
+      if (from !== to) changed.push({ side: name, field, from, to });
+    }
+  }
+
+  return {
+    local: l,
+    cloud: c,
+    verified,
+    agree: verified && diffs.length === 0,
+    diffs,
+    changed,
+    ...(failed ? { failed: failed.side } : {}),
+    ...(retry ? { retry } : {}),
+  };
+}
+
+/** The one-word state a script or test can branch on (same as receipt.ts `receiptStatus`). */
+export function sidesReceiptStatus(receipt) {
+  if (receipt.failed) return 'failed';
+  if (!receipt.verified) return 'unverified';
+  if (!receipt.agree) return 'disagree';
+  return 'verified';
+}
+
+function cell(side, field) {
+  if (!field) return '';
+  if (!side.read) return '(not read)';
+  const v = valueOf(side, field);
+  if (v === null) return '(none)';
+  if (typeof v === 'boolean') return v ? 'yes' : 'no';
+  return String(v);
+}
+
+const show = (v) => (v === null || v === undefined ? '(none)' : String(v));
+
+/**
+ * The text sink: the same two-column table and "Result:" line as receipt.ts
+ * `formatReceipt`, rows taken from `rows`.
+ * @param {ReturnType<typeof buildSidesReceipt>} receipt
+ * @param {ReceiptRow[]} rows
+ */
+export function formatSidesReceipt(receipt, rows) {
+  const table = [
+    ['', 'local (this machine)', 'cloud (console)'],
+    ...rows.map((r) => [r.label, cell(receipt.local, r.local), cell(receipt.cloud, r.cloud)]),
+  ];
+  const w0 = Math.max(...table.map((r) => r[0].length));
+  const w1 = Math.max(...table.map((r) => r[1].length));
+  const lines = [
+    'Read back after the write:',
+    ...table.map(([a, b, c]) => `  ${a.padEnd(w0)}  ${b.padEnd(w1)}  ${c}`.trimEnd()),
+  ];
+  const status = sidesReceiptStatus(receipt);
+  const retry = receipt.retry ? ` Retry: \`${receipt.retry}\`` : '';
+  if (status === 'failed') {
+    const reason = receipt[receipt.failed].reason;
+    lines.push(`Result: failed -- the ${receipt.failed} half did not land${reason ? ` (${reason})` : ''}.${retry}`);
+  } else if (status === 'unverified') {
+    const unread = ['local', 'cloud'].filter((s) => !receipt[s].read);
+    const why = unread.map((s) => `${s}${receipt[s].reason ? `: ${receipt[s].reason}` : ''}`).join('; ');
+    lines.push(`Result: unverified -- the ${unread.join(' and ')} side was not read back (${why}).`);
+  } else if (status === 'disagree') {
+    lines.push(
+      `Result: the two sides disagree on ${receipt.diffs.map((d) => d.field).join(', ')}.${retry}`,
+      ...receipt.diffs.map((d) => `  ${d.field}: local ${show(d.local)} | cloud ${show(d.cloud)}`),
+    );
+  } else {
+    lines.push('Result: verified -- both sides were read back and agree.');
+  }
+  return lines.join('\n');
+}

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

@@ -0,0 +1,117 @@
+// heyspex_start_recipe and heyspex_list_recipes handlers (recipe-tools.mjs holds the store). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { wrapDesignResult } from './tool-helpers.mjs';
+import { executeListRecipes, executeStartRecipe } from './recipe-tools.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { consoleErrorMessage } from './console-fetch.mjs';
+import { createCaptureSessionOnConsole, writeCaptureFocusVendor } from './capture-tools.mjs';
+
+// heyspex_list_recipes — pure catalog scan wrapped for the tool surface.
+export function handleListRecipes(vaultRoot, args) {
+  return wrapDesignResult(executeListRecipes(vaultRoot, args));
+}
+
+// heyspex_start_recipe — resolve the recipe (pure) then, when the console is
+// reachable, create + pin a capture session tied to it (mirrors
+// handlePinCapture). The recipe start context is returned in every case so the
+// flow can be walked even when the capture could not be created (offline).
+export async function handleStartRecipe(vaultRoot, args) {
+  const resolved = executeStartRecipe(vaultRoot, args);
+  if (resolved.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(resolved, null, 2) }],
+    };
+  }
+  const recipe = resolved.recipe;
+  const identity = detectAgentIdentity();
+
+  const createResult = await createCaptureSessionOnConsole({
+    opened_by: 'agent',
+    opened_by_session: identity.sessionId,
+    mode: 'attended',
+    status: 'pending',
+  });
+
+  if (createResult.ok && createResult.session) {
+    const session = createResult.session;
+    const pin = await writeCaptureFocusVendor(vaultRoot, {
+      specId: session.id,
+      specPath: session.specPath || '',
+      reason: `Started workflow-recipe ${recipe.recipe_id} (${recipe.name})`,
+      claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+    });
+    if (!pin.pinned) {
+      // The session row WAS created and the recipe context is intact — both are
+      // returned so nothing is lost and no second session gets minted. But the
+      // message may not say "pinned" over a pin that never persisted
+      // ([[HS-IOJW-5YDH-DIAG]] sweep: report the result, not the request).
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            started: true,
+            pinned: false,
+            error: 'CAPTURE_PIN_NOT_WRITTEN',
+            source: 'database',
+            capture: { spec_id: session.id, spec_path: session.specPath || null },
+            pin,
+            recipe,
+            message:
+              `Capture session ${session.id} was created for workflow-recipe ${recipe.recipe_id}, but the ` +
+              `capture-on-deck pin was NOT written (${pin.reason}). A later /hs-capture with no id will ` +
+              'resolve to a DIFFERENT capture. Do not re-run heyspex_start_recipe (it would mint a second ' +
+              `session) — re-pin with heyspex_pin_capture({ spec_id: "${session.id}" }) once the console is healthy.`,
+          }, null, 2),
+        }],
+      };
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          started: true,
+          pinned: true,
+          pin,
+          source: 'database',
+          capture: { spec_id: session.id, spec_path: session.specPath || null },
+          recipe,
+          message: `Capture session ${session.id} created and pinned (${pin.tier}) for workflow-recipe ${recipe.recipe_id}. Walk the capture_sequence, then file the spec pre-filled from spec_template (recipe_id + tool_scope stamp provenance).`,
+        }, null, 2),
+      }],
+    };
+  }
+
+  // The create failed → the recipe context is still fully returned so the flow
+  // can be walked / filed later. No divergent local capture file is minted
+  // (capture is online-only, [[heyspex-is-online-only-no-offline]]).
+  //
+  // HS-I6HT: this used to hardcode "HeySpex can't reach the server right now"
+  // for EVERY failure, so a sign-in failure printed an outage sentence next to
+  // a CONSOLE_NOT_SIGNED_IN code — two contradictory stories in one payload.
+  // `consoleErrorMessage` already writes the right sentence per class (sign-in,
+  // 401, wrong port, timeout, genuinely down); use it whenever it has one, and
+  // keep the old wording only as the last-resort fallback.
+  const answered =
+    typeof createResult.result?.body?.message === 'string'
+      ? createResult.result.body.message
+      : null;
+  const whatHappened =
+    (createResult.result ? consoleErrorMessage(createResult.result, answered) : null)
+    || "HeySpex can't reach the server right now.";
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        started: false,
+        status: 'deferred',
+        error: createResult.error || 'CONSOLE_UNREACHABLE',
+        recipe,
+        message:
+          `${whatHappened} The capture wasn't created, but the recipe's steps are returned below and nothing is lost. Fix the cause above, then call again to pin the capture.`,
+      }, null, 2),
+    }],
+  };
+}

package/vendor/heyspex-mcp/regen-tasks.mjs

@@ -21,7 +21,24 @@
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute, resolve, sep } from 'node:path';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+// Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+// Regen has no create-first/link-second reorder — nothing it writes links to a
+// basename another write in the same batch mints — but the same rule applies:
+// a `writeFileSync` under `specs/` in cloud mode is a split brain.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+import {
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+  cloudModeUnsupportedWrite,
+} from './promotion-helpers.mjs';
+
 
 const TERMINAL_STATUSES = new Set([
   'closed',
@@ -49,6 +66,11 @@ export function softDeleteToTrash(vaultRoot, relPath, bucket = 'misc') {
   if (!existsSync(abs)) return { ok: false, error: 'not_found', source: relPath };
   const basename = relPath.split(/[\\/]/).pop() || `${timestamp()}-spec.md`;
   const trashDir = join(vaultRoot, 'specs', '.trash', bucket);
+  try {
+    assertPathUnderRoot(vaultRoot, trashDir, 'regen-tasks write');
+  } catch (err) {
+    return { ok: false, error: 'BAD_VAULT_ROOT', source: relPath, message: err.message };
+  }
   mkdirSync(trashDir, { recursive: true });
   const dest = join(trashDir, `${timestamp()}-${basename}`);
   renameSync(abs, dest);
@@ -136,7 +158,77 @@ function epicSlugFromRel(relPath) {
  *
  * Both modes return `{ ok, mode, task, epic, brief?, commit_result? }`.
  */
-export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body, retire_reason, loadTask }) {
+/**
+ * The cloud twin of the `.trash/` soft-delete — EXPLICIT DEGRADE.
+ *
+ * `softDeleteToTrash` renames a file into `specs/.trash/<bucket>/`, which is
+ * not a spec of any type the console models (no TYPE_TO_FOLDER entry, no id,
+ * no frontmatter contract), so there is no POST/PUT route that could carry it.
+ * In cloud mode the replacement still happens — `PUT /api/specs/:id` overwrites
+ * the body and the console keeps its own version history — but the local
+ * `.trash/` copy the [[destructive-action-checklist]] recovery procedure names
+ * does not exist. That is REPORTED on every affected entry rather than
+ * silently skipped, so the caller knows which recovery path applies.
+ */
+function cloudTrashDegrade(relPath) {
+  return cloudModeUnsupportedWrite(
+    `specs/.trash/… (soft-delete of ${relPath})`,
+    'a trash copy is not a spec of any type the console models, so there is no route to write it; the replacement itself still landed through PUT /api/specs/:id and the console keeps its own version history',
+    { recovery: 'Restore the previous body from the console\'s spec history rather than from a local .trash/ file.' },
+  );
+}
+
+/**
+ * Replace one existing spec's body through the console.
+ * `new_body` is the agent-authored full markdown (frontmatter + body), the
+ * same string the disk path writes verbatim.
+ */
+async function putBodyViaConsole(specId, newBody, cloudDeps) {
+  const { frontmatter, body } = splitRawSpecForConsole(newBody);
+  return updateSpecViaConsole({ ...cloudDeps, specId, frontmatter, body });
+}
+
+/**
+ * Cloud-mode `executeRegenTask` commit. Same result shape as the disk path
+ * plus `write_mode: 'cloud'` and the `.trash/` degrade note.
+ */
+async function regenTaskCommitViaConsole({ taskSummary, epicSummary, new_body, retire_reason, cloudDeps }) {
+  let res;
+  try {
+    res = await putBodyViaConsole(taskSummary.id, new_body, cloudDeps);
+  } catch (err) {
+    return {
+      ok: false,
+      ...cloudWriteFailureResult(err, {
+        step: { kind: 'update', type: 'task', spec_id: taskSummary.id },
+        completed: [],
+      }),
+    };
+  }
+  return {
+    ok: true,
+    mode: 'commit',
+    write_mode: 'cloud',
+    task: { id: res.specId ?? taskSummary.id, rel_path: res.relPath ?? taskSummary.rel_path },
+    retired_to: null,
+    retire_reason: retire_reason || null,
+    epic: epicSummary ? { id: epicSummary.id } : null,
+    cloud_mode_unsupported_writes: [cloudTrashDegrade(taskSummary.rel_path ?? taskSummary.id)],
+    message:
+      `Replaced the body of ${taskSummary.id} through the console (cloud write mode — nothing was written to local disk). ` +
+      'No local .trash/ copy was made; recover the previous body from the console\'s spec history.',
+  };
+}
+
+export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body, retire_reason, loadTask, writeMode, consoleFetch, consoleUrl }) {
+  // Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]),
+  // resolved ONCE by the caller and defaulting to `local`. This function stays
+  // SYNCHRONOUS on the local path on purpose — `spec-edit-tools.mjs` consumes
+  // its return value synchronously — and returns a Promise only in cloud mode,
+  // which a cloud-aware caller awaits (awaiting the plain object the local
+  // path returns is a no-op, so one call site serves both).
+  const cloudWriteMode = resolveWriteModeFromDeps({ writeMode });
+  const cloudDeps = { consoleFetch, consoleUrl };
   if (!task_id) {
     return { ok: false, error: 'MISSING_TASK_ID', message: 'task_id is required' };
   }
@@ -159,6 +251,15 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
         message: 'commit: true requires non-empty new_body',
       };
     }
+    if (cloudWriteMode === 'cloud') {
+      return regenTaskCommitViaConsole({
+        taskSummary,
+        epicSummary,
+        new_body,
+        retire_reason,
+        cloudDeps,
+      });
+    }
     if (!taskSummary.rel_path) {
       return { ok: false, error: 'NO_REL_PATH', task_id };
     }
@@ -172,6 +273,11 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
     // it — that's an agent error and surfaces as a malformed spec at the
     // next /hs-next.
     const destAbs = join(vaultRoot, taskSummary.rel_path);
+    try {
+      assertPathUnderRoot(vaultRoot, dirname(destAbs), 'regen-tasks write');
+    } catch (err) {
+      return { ok: false, error: 'BAD_VAULT_ROOT', task_id, message: err.message };
+    }
     mkdirSync(dirname(destAbs), { recursive: true });
     writeFileSync(destAbs, new_body, 'utf8');
     return {
@@ -222,7 +328,93 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
  * The tool is deliberately deterministic — the LLM thinking happens between
  * brief mode and commit mode in the calling agent.
  */
-export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, task_specs, loadTask }) {
+/**
+ * Cloud-mode `executeRegenTasksForEpic` commit — the same two entry shapes the
+ * disk path takes, routed through the console:
+ *
+ *   `{ id, new_body, retire_reason }` → `PUT /api/specs/:id` (replace in place;
+ *      no local `.trash/` copy — reported, see {@link cloudTrashDegrade}).
+ *   `{ new_id, body, rel_path }`      → `POST /api/specs` (the caller-supplied
+ *      `new_id`/`rel_path` are IGNORED: the console mints the id, the family
+ *      and the filename, so nothing is hand-picked — HS-BYU4 AC3. The minted
+ *      id is reported back in `wrote[]`.)
+ */
+async function regenTasksForEpicCommitViaConsole({ epicSummary, task_specs, loadTask, cloudDeps }) {
+  const retired = [];
+  const wrote = [];
+  const errors = [];
+  const unsupported = [];
+  for (const entry of task_specs) {
+    if (entry && typeof entry === 'object' && entry.id && typeof entry.new_body === 'string') {
+      const target = loadSpecRecord(loadTask, entry.id);
+      const specId = target?.id || target?.frontmatter?.id || entry.id;
+      try {
+        const res = await putBodyViaConsole(specId, entry.new_body, cloudDeps);
+        retired.push({ id: entry.id, trash_path: null, retire_reason: entry.retire_reason || null });
+        unsupported.push(cloudTrashDegrade(target?.relPath || target?.rel_path || entry.id));
+        wrote.push({ id: res.specId ?? specId, rel_path: res.relPath ?? null });
+      } catch (err) {
+        errors.push({
+          id: entry.id,
+          ...cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'task', spec_id: specId },
+            completed: wrote,
+          }),
+        });
+      }
+    } else if (entry && typeof entry === 'object' && entry.new_id && typeof entry.body === 'string') {
+      const { frontmatter, body } = splitRawSpecForConsole(entry.body);
+      const cleaned = stripServerMintedFields(frontmatter);
+      try {
+        const created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: cleaned.type ?? frontmatter.type ?? 'task',
+          name: cleaned.name ?? frontmatter.name ?? String(entry.new_id),
+          summary: cleaned.summary ?? null,
+          frontmatter: cleaned,
+          body,
+        });
+        wrote.push({
+          id: created.specId,
+          rel_path: created.relPath,
+          requested_id: entry.new_id,
+          note:
+            'The console minted this id/filename server-side; the caller-supplied `new_id`/`rel_path` were not used (file keys are never hand-picked).',
+        });
+      } catch (err) {
+        errors.push({
+          new_id: entry.new_id,
+          ...cloudWriteFailureResult(err, {
+            step: { kind: 'create', type: 'task', name: entry.new_id },
+            completed: wrote,
+          }),
+        });
+      }
+    } else {
+      errors.push({ entry, error: 'INVALID_SHAPE' });
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    mode: 'commit',
+    write_mode: 'cloud',
+    epic: { id: epicSummary.id },
+    retired,
+    wrote,
+    errors,
+    bucket: null,
+    ...(unsupported.length > 0 ? { cloud_mode_unsupported_writes: unsupported } : {}),
+    message:
+      `Stage-1-2-3 commit for ${epicSummary.id} through the console: replaced ${retired.length}, wrote ${wrote.length}, errors ${errors.length}. ` +
+      'Cloud write mode — nothing was written to local disk and no .trash/ copies were made; recover previous bodies from the console\'s spec history.',
+  };
+}
+
+export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, task_specs, loadTask, writeMode, consoleFetch, consoleUrl }) {
+  // Same once-per-call resolution + sync-unless-cloud contract as
+  // {@link executeRegenTask} above.
+  const cloudWriteMode = resolveWriteModeFromDeps({ writeMode });
+  const cloudDeps = { consoleFetch, consoleUrl };
   if (!epic_id) {
     return { ok: false, error: 'MISSING_EPIC_ID', message: 'epic_id is required' };
   }
@@ -255,6 +447,9 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
         message: 'commit: true requires task_specs: [{ id, new_body, retire_reason } | { new_id, body, rel_path }]',
       };
     }
+    if (cloudWriteMode === 'cloud') {
+      return regenTasksForEpicCommitViaConsole({ epicSummary, task_specs, loadTask, cloudDeps });
+    }
     const bucket = epicSlugFromRel(epicSummary.rel_path);
     const retired = [];
     const wrote = [];
@@ -273,6 +468,12 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
           continue;
         }
         const abs = join(vaultRoot, rel);
+        try {
+          assertPathUnderRoot(vaultRoot, dirname(abs), 'regen-tasks write');
+        } catch (err) {
+          errors.push({ id: entry.id, error: 'BAD_VAULT_ROOT', message: err.message });
+          continue;
+        }
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, entry.new_body, 'utf8');
         retired.push({ id: entry.id, trash_path: del.trash_path, retire_reason: entry.retire_reason || null });
@@ -283,6 +484,12 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
           errors.push({ new_id: entry.new_id, error: 'CONFLICT', rel_path: entry.rel_path });
           continue;
         }
+        try {
+          assertPathUnderRoot(vaultRoot, dirname(abs), 'regen-tasks write');
+        } catch (err) {
+          errors.push({ new_id: entry.new_id, error: 'BAD_VAULT_ROOT', message: err.message });
+          continue;
+        }
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, entry.body, 'utf8');
         wrote.push({ id: entry.new_id, rel_path: entry.rel_path });