heyspex 0.2.0 → 0.2.1

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

@@ -10,11 +10,14 @@ import { childKindFor, getChildRefs, upsertFrontmatterKeys } from './alignment-g
 import { measureDiskLanding, resolveSpecIdForMutation } from './tool-helpers.mjs';
 import { stampSkippedDespiteFindingsOnBreakdownMarker } from './plan-review.mjs';
 import { resolveNextOnDeckPayload } from './on-deck-brief.mjs';
-import { ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier } from './read-path.mjs';
+import { consoleReadErrorFrom, ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier } from './read-path.mjs';
 import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
 import { consoleFetch, controlError, controlOk, enrichConsoleFailurePayloadAsync, postClaimEndpoint } from './console-transport.mjs';
 import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
 import { executeSubmitForReview } from './submit-for-review.mjs';
+import { deferControlWrite } from './write-outbox.mjs';
+
+const isCloudReliant = async () => (await resolveReadTier()) === 'neon';
 
 /**
  * Minimum length for an alignment override reason. Matches the bar the milestone
@@ -265,6 +268,7 @@ export async function handleRecordAlignmentViaTier(vaultRoot, config, args) {
   const consoleUrl = effectiveConsoleUrl();
   try {
     return await readViaSelector({
+    allowDiskFallback: false,
       tier,
       diskRead: () => handleRecordAlignment(vaultRoot, config, args),
       neonRead: () => handleRecordAlignmentCloud(vaultRoot, config, args, { consoleUrl }),
@@ -332,7 +336,7 @@ export async function handleRecordAlignmentCloud(vaultRoot, config, args, { cons
 
   const getRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
   if (!getRes.ok) {
-    throw new Error(`GET /api/specs/${specId} returned ${getRes.status}: ${getRes.error || JSON.stringify(getRes.body ?? {})}`);
+    throw consoleReadErrorFrom(getRes, `GET /api/specs/${specId} returned ${getRes.status}: ${getRes.error || JSON.stringify(getRes.body ?? {})}`, null);
   }
   const spec = getRes.body?.spec;
   if (!spec) {
@@ -680,6 +684,16 @@ export async function handleReportProgress(args = {}) {
     { method: 'PATCH', body },
   );
   if (!result.ok) {
+    // Append-only progress is safe to queue on an outage (degrade, don't die).
+    const deferred = await deferControlWrite(result, {
+      route: `/api/specs/${encodeURIComponent(progressSpecId)}/claim/status`,
+      method: 'PATCH',
+      request_body: body,
+      spec_id: progressSpecId,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: isCloudReliant });
+    if (deferred) return deferred;
     const payload = {
       error: consoleErrorCode(result, 'REPORT_PROGRESS_FAILED'),
       message: consoleErrorMessage(result, `Claim status endpoint returned ${result.status}`),
@@ -919,6 +933,15 @@ export async function handleRecordWip(args = {}) {
     { method: 'POST', body },
   );
   if (!result.ok) {
+    const deferred = await deferControlWrite(result, {
+      route: `/api/specs/${encodeURIComponent(args.spec_id)}/wip`,
+      method: 'POST',
+      request_body: body,
+      spec_id: args.spec_id,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: isCloudReliant });
+    if (deferred) return deferred;
     const payload = {
       error: consoleErrorCode(result, 'WIP_FAILED'),
       message: consoleErrorMessage(result, `WIP endpoint returned ${result.status}`),

package/vendor/heyspex-mcp/cli-verbs.mjs

@@ -12,6 +12,8 @@
 // Browser hand-off primitives for `hs login` (RFC 8252 loopback), epic
 // [[HS-IFQM-IZQ7-EPIC-hs-login-browser-hand-off-for-cli-and]].
 
+import { registryAccountIdForRoot } from './vault-resolve.mjs';
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { DEFAULT_LOGIN_TIMEOUT_MS, buildConnectUrl, describeCallbackFailure, describeRedeemFailure, generateLoginState, openBrowser as openBrowserDefault, startCallbackListener as startCallbackListenerDefault } from './login-handoff.mjs';
 import { getConfig, getConsoleUrl } from './mcp-config.mjs';
 import { homedir, hostname } from 'node:os';
@@ -489,7 +491,7 @@ export async function redeemAndStorePairingCode({
   code,
   label,
   probe = probeCredentialIdentity,
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   requireAccount = null,
 }) {
   let response;
@@ -672,7 +674,7 @@ function currentStoredAccount(homeDir) {
 }
 
 /** Local side: the current account in credentials.yaml, its console, and where the bearer resolves from. */
-export function readLoginLocalSide({ homeDir = homedir(), env = process.env } = {}) {
+export function readLoginLocalSide({ homeDir = heyspexHome(), env = process.env } = {}) {
   try {
     const { id, entry } = currentStoredAccount(homeDir);
     return {
@@ -692,7 +694,7 @@ export function readLoginLocalSide({ homeDir = homedir(), env = process.env } =
  * account, at that account's console (else `fallbackConsoleUrl`). Never
  * includes token material.
  */
-export async function readLoginCloudSide({ homeDir = homedir(), probe = probeCredentialIdentity, fallbackConsoleUrl } = {}) {
+export async function readLoginCloudSide({ homeDir = heyspexHome(), probe = probeCredentialIdentity, fallbackConsoleUrl } = {}) {
   const { entry } = currentStoredAccount(homeDir);
   if (!entry?.mcp_token) return unreadSide('no stored sign-in to ask the console about');
   const identity = await probe({ consoleUrl: entry.console_url ?? fallbackConsoleUrl, token: entry.mcp_token });
@@ -1032,7 +1034,7 @@ export async function runLoginCli(argv, deps = {}) {
     probe = probeCredentialIdentity,
     stdout = process.stdout,
     stderr = process.stderr,
-    homeDir = homedir(),
+    homeDir = heyspexHome(),
     resolveConsoleUrl = getConsoleUrl,
     env = process.env,
   } = deps;
@@ -1318,7 +1320,7 @@ export async function runWhoamiCli(argv, deps = {}) {
     probe = probeCredentialIdentity,
     readBearer: readBearerDep,
     env = process.env,
-    homeDir = homedir(),
+    homeDir = heyspexHome(),
     stdout = process.stdout,
     stderr = process.stderr,
     resolveConsoleUrl = getConsoleUrl,
@@ -1468,7 +1470,7 @@ export function parseLogoutCliArgs(argv) {
 
 /** `hs logout [--account <id|email>]` — remove one stored account (default: the current one). */
 export async function runLogoutCli(argv, deps = {}) {
-  const { homeDir = homedir(), env = process.env, stdout = process.stdout, stderr = process.stderr } = deps;
+  const { homeDir = heyspexHome(), env = process.env, stdout = process.stdout, stderr = process.stderr } = deps;
   const parsed = parseLogoutCliArgs(argv);
   if (parsed.help) {
     stdout.write(`${LOGOUT_CLI_HELP}\n`);
@@ -1800,7 +1802,7 @@ export function mergeRemoteMcpJson(existingJson, cloudEntry) {
  * ever risking the value landing in a committed file
  * ([[HS-D1QU-B0IT-EPIC-cloud-mcp-alongside-the-satellite-pin]] AC4).
  */
-export function resolveInstallBearer({ env = process.env, homeDir = homedir() } = {}) {
+export function resolveInstallBearer({ env = process.env, homeDir = heyspexHome() } = {}) {
   // The ONE shared reader (./credentials.mjs, HS-HL0D) — the same precedence
   // the MCP runtime, `hs whoami` and the CLI gate use; only its SOURCE leaves
   // this function. `credentials` keeps this verb's pinned --json vocabulary.
@@ -1837,17 +1839,13 @@ const MARKER_ACCOUNT_LINE_RE = /^account:[ \t]*["']?([^"'\r\n#]+)/m;
  * account reader, ./session-owner.mjs), else `null` ("unrecorded"). Never
  * throws.
  * @param {{ vaultRoot: string, env?: object, homeDir?: string }} opts
- * @returns {{ accountId: string, source: 'heyspex.yaml' | 'config.yaml' } | null}
+ * @returns {{ accountId: string, source: 'registry' | 'config.yaml' } | null}
  */
-export function readRecordedRepoAccount({ vaultRoot, env = process.env, homeDir = homedir() }) {
-  let marker = null;
-  try {
-    marker = readFileSync(join(vaultRoot, 'heyspex.yaml'), 'utf8');
-  } catch {
-    marker = null;
-  }
-  const fromMarker = typeof marker === 'string' ? marker.match(MARKER_ACCOUNT_LINE_RE)?.[1]?.trim() : '';
-  if (fromMarker) return { accountId: fromMarker, source: 'heyspex.yaml' };
+export function readRecordedRepoAccount({ vaultRoot, env = process.env, homeDir = heyspexHome() }) {
+  // The repo-to-account binding is machine-local (registry row), never the
+  // committed marker; a legacy `account:` line in heyspex.yaml is ignored.
+  const fromRegistry = registryAccountIdForRoot(vaultRoot, { registryDir: join(homeDir, '.heyspex') });
+  if (fromRegistry) return { accountId: fromRegistry, source: 'registry' };
   const configured = resolveSessionOwnerUncached({ env, homeDir });
   return configured ? { accountId: configured, source: 'config.yaml' } : null;
 }
@@ -1904,7 +1902,7 @@ export function decideRemoteInstallAccount({ probe, recorded, consoleUrl, tokenS
     // install --remote` give ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]],
     // install-identity.ts). Compared only with this machine's configured
     // account (no `account:` in the marker) it stays unconfirmed (17).
-    const fromMarker = recorded.source === 'heyspex.yaml';
+    const fromMarker = recorded.source === 'registry';
     const repair = fromMarker ? `hs login --account ${recorded.accountId}` : 'hs login --switch-account';
     return refuse(
       fromMarker ? EXIT_ACCOUNT_MISMATCH : 17,
@@ -1923,8 +1921,8 @@ export function decideRemoteInstallAccount({ probe, recorded, consoleUrl, tokenS
   }
   const repoLine = !recorded
     ? '  repo:     unrecorded (heyspex.yaml has no account:, no account_id in ~/.heyspex/config.yaml) -- using the signed-in account'
-    : recorded.source === 'heyspex.yaml'
-      ? `  repo:     ${recorded.accountId} (heyspex.yaml) -- matches the signed-in account`
+    : recorded.source === 'registry'
+      ? `  repo:     ${recorded.accountId} (registry) -- matches the signed-in account`
       : `  repo:     unrecorded in heyspex.yaml -- compared with this machine's configured account ${recorded.accountId} (~/.heyspex/config.yaml), which matches`;
   return {
     ok: true,
@@ -1948,7 +1946,7 @@ export function decideRemoteInstallAccount({ probe, recorded, consoleUrl, tokenS
 export async function runMcpInstallCli(argv, deps = {}) {
   const {
     env = process.env,
-    homeDir = homedir(),
+    homeDir = heyspexHome(),
     stdout = process.stdout,
     stderr = process.stderr,
     vaultRoot: vaultRootOverride,

package/vendor/heyspex-mcp/cli.mjs

@@ -35,6 +35,7 @@ import {
   migrateLegacyIdeaFocus,
 } from './capture-focus.mjs';
 import {
+  announcePointerVaultOnce,
   getAccountIdHeader,
   getAuthHeader,
   getVaultIdHeader,
@@ -382,7 +383,12 @@ if (!RUNNING_AS_CLI && !INFO_ONLY && process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP
   stampMcpBuildRecord();
 
   try {
-    const { vaultRoot: bootVaultRoot } = getConfig();
+    const { vaultRoot: bootVaultRoot, vaultId: bootVaultId, vaultSource: bootVaultSource } = getConfig();
+    // A repo that names no vault resolves to the account-wide pointer; the
+    // transport refuses its console calls (console-fetch.mjs VAULT_NOT_PINNED)
+    // unless HEYSPEX_ALLOW_POINTER_VAULT=1 — in which case say which vault
+    // this process will act on, once, right here at start.
+    announcePointerVaultOnce({ vaultId: bootVaultId, repoRootAbs: bootVaultRoot, source: bootVaultSource });
     if (existsSync(bootVaultRoot)) {
       captureChannelWatcher = createCaptureChannelWatcher({
         vaultRoot: bootVaultRoot,

package/vendor/heyspex-mcp/close-branch-report.mjs

@@ -0,0 +1,102 @@
+/**
+ * Session-close branch report
+ * ([[HS-PPX7-CWPX-TASK-session-close-names-the-branch-each]], epic
+ * [[HS-B8CY-CWPX-EPIC-one-session-one-reviewable-change]] AC5).
+ *
+ * At close-out, names the branch each half of the session landed on — the
+ * CODE half (the checked-out git branch of the session's code repo) and the
+ * SPEC half (branches the cloud drain committed this session's specs to, read
+ * from `GET /api/source/session-branch`) — and says plainly whether they are
+ * the same branch. Pure core (`buildCloseBranchReport`) + a thin gatherer
+ * (`gatherCloseBranchReport`) with injected `consoleFetch` / `runGit`.
+ *
+ * Honesty rule: a half that could not be read is reported UNKNOWN, and an
+ * unknown half never yields a "same branch" claim.
+ */
+import { spawnSync } from 'node:child_process';
+
+/**
+ * The written rule for a drain commit that landed on a different branch than
+ * the code (mid-session drain while the working tree is on another branch).
+ * Mirrored verbatim into the live-proof runbook.
+ */
+export const MID_SESSION_DRAIN_RULE =
+  'The cloud drain commits spec files on its own branch without touching your working tree. ' +
+  'To join the halves: `git fetch origin <spec-branch>`, then on your code branch run ' +
+  '`git merge --no-ff origin/<spec-branch>` (or `git cherry-pick <commit>` for one commit). ' +
+  'Never rebase-merge; a dirty working tree is fine because the merge only adds spec files. ' +
+  'Next time run `hs source branch declare` before cloud writes so both halves land on one branch.';
+
+/**
+ * @param {{ codeBranch: string | null, specBranches: string[] | null, declared?: string | null }} input
+ *   codeBranch / specBranches are null when that half could not be read.
+ * @returns {{ status: 'same'|'differ'|'none'|'unknown', matches: boolean, lines: string[] }}
+ */
+export function buildCloseBranchReport({ codeBranch, specBranches, declared = null }) {
+  const lines = [];
+  lines.push(`Code branch: ${codeBranch ?? 'unknown (no checked-out branch / git unavailable)'}`);
+  if (specBranches === null) {
+    lines.push('Spec branch(es): unknown (console unreachable)');
+  } else if (specBranches.length === 0) {
+    lines.push('Spec branch(es): none — no cloud spec commits this session');
+  } else {
+    lines.push(`Spec branch(es): ${specBranches.join(', ')}`);
+  }
+  if (declared) lines.push(`Declared session branch: ${declared}`);
+
+  if (codeBranch === null || specBranches === null) {
+    const which = [codeBranch === null ? 'code' : null, specBranches === null ? 'spec' : null]
+      .filter(Boolean)
+      .join(' and ');
+    lines.push(`Match: unknown — the ${which} half could not be read.`);
+    return { status: 'unknown', matches: false, lines };
+  }
+  if (specBranches.length === 0) {
+    lines.push('Match: nothing to compare — the cloud drain made no spec commits for this session.');
+    return { status: 'none', matches: false, lines };
+  }
+  const differing = specBranches.filter((b) => b !== codeBranch);
+  if (differing.length === 0) {
+    lines.push('Match: yes — same branch, the code and the spec files can be reviewed together.');
+    return { status: 'same', matches: true, lines };
+  }
+  lines.push(`Match: NO — spec commits are on ${differing.join(', ')}, code is on ${codeBranch}.`);
+  lines.push(MID_SESSION_DRAIN_RULE);
+  return { status: 'differ', matches: false, lines };
+}
+
+function defaultRunGit(args, cwd) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+/** Current checked-out branch of `cwd`, or null. */
+export function readCodeBranch({ cwd = process.cwd(), runGit = defaultRunGit } = {}) {
+  try {
+    const r = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    const out = String(r?.stdout ?? '').trim();
+    if (r?.status !== 0 || !out || out === 'HEAD') return null;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather both halves and build the report. Never throws.
+ * `consoleFetch(path)` is the MCP's console client (`{ ok, body }`).
+ */
+export async function gatherCloseBranchReport({ consoleFetch, cwd = process.cwd(), runGit } = {}) {
+  const codeBranch = readCodeBranch({ cwd, runGit });
+  let specBranches = null;
+  let declared = null;
+  try {
+    const res = await consoleFetch('/api/source/session-branch');
+    if (res?.ok && Array.isArray(res.body?.drainCommits)) {
+      specBranches = [...new Set(res.body.drainCommits.map((c) => c.branch).filter(Boolean))];
+      declared = res.body.declaration?.branch ?? null;
+    }
+  } catch {
+    specBranches = null;
+  }
+  return buildCloseBranchReport({ codeBranch, specBranches, declared });
+}

package/vendor/heyspex-mcp/cloud-vault-writes.mjs

@@ -39,6 +39,16 @@
 import { randomUUID } from 'node:crypto';
 import { walkSpecListPages } from './list-tools.mjs';
 import { parseFrontmatter } from './vault-io.mjs';
+import {
+  buildDeferredPayload,
+  drainAndSummarize,
+  getWriteOutboxRoot,
+  isOutageClassResult,
+  stashIfOutage,
+  stashWrite,
+  failureOf,
+  DEFERRED_RECEIPT,
+} from './write-outbox.mjs';
 
 /**
  * Raised when a `cloud`-mode write fails. Mirrors
@@ -53,6 +63,50 @@ export class CloudWriteUnreachableError extends Error {
   }
 }
 
+/**
+ * Raised INSTEAD of a plain {@link CloudWriteUnreachableError} when the write hit
+ * an outage (status 0 / timeout / 5xx) and was queued to the write outbox
+ * ([[heyspex-is-online-only-no-offline]] 2026-08-20 amendment). It extends the
+ * unreachable error so every existing `catch` still works, but it carries
+ * `deferred: true` + the truthful receipt: the write did NOT land yet, and it is
+ * NOT lost. Callers that can return a tool response render
+ * {@link deferredPayloadFromError}; callers that need the new spec's id/basename
+ * (promotion chains) cannot continue and surface it as before.
+ */
+export class CloudWriteDeferredError extends CloudWriteUnreachableError {
+  constructor(message, details = {}) {
+    super(message, details);
+    this.deferred = true;
+  }
+}
+
+/** The `{ status: 'deferred', … }` tool payload for a deferred error, or null. */
+export function deferredPayloadFromError(err) {
+  if (!err?.deferred || !err.outbox_id) return null;
+  return {
+    status: 'deferred',
+    outbox_id: err.outbox_id,
+    pending_sync: err.pending_sync ?? 1,
+    receipt: err.receipt ?? DEFERRED_RECEIPT,
+    ...(err.completed_steps ? { completed_steps: err.completed_steps } : {}),
+  };
+}
+
+/** Details carrying the replayable request for a no-stash caller (commitWritesViaConsole). */
+function outageRequest(noStash, result, entry) {
+  return noStash && isOutageClassResult(result)
+    ? { outage_request: { ...entry, failure: failureOf(result) } }
+    : {};
+}
+
+function deferredError(routeLabel, consoleUrl, stashed, vaultRoot, details = {}) {
+  const payload = buildDeferredPayload(stashed, vaultRoot);
+  return new CloudWriteDeferredError(
+    `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl ?? '<unknown console>'} — ${DEFERRED_RECEIPT} (outbox_id ${payload.outbox_id})`,
+    { route: routeLabel, console_url: consoleUrl ?? null, ...details, outbox_id: payload.outbox_id, pending_sync: payload.pending_sync, receipt: payload.receipt },
+  );
+}
+
 /** Build the canonical failure error for a route + console + detail. */
 export function cloudWriteFailure(routeLabel, consoleUrl, detail, details = {}) {
   return new CloudWriteUnreachableError(
@@ -155,7 +209,10 @@ export async function createSpecViaConsole({
   actingAgent = null,
   idempotencyKey = null,
   routeLabel = 'POST /api/specs',
+  vaultRoot = null,
+  noStash = false,
 }) {
+  const outboxRoot = noStash ? null : vaultRoot ?? getWriteOutboxRoot();
   if (typeof consoleFetch !== 'function') {
     throw cloudWriteFailure(routeLabel, consoleUrl, 'no consoleFetch dependency was injected');
   }
@@ -186,24 +243,55 @@ export async function createSpecViaConsole({
     ...(actingAgent ? { acting_agent: actingAgent } : {}),
   };
 
+  // One key per LOGICAL call: the stash below stores THIS key so a replay is the
+  // same create, never a second mint ([[HS-2FQY]]).
+  const createKey = idempotencyKey ?? randomUUID();
+  const createEntry = {
+    op: 'create',
+    kind: 'create',
+    route: '/api/specs',
+    method: 'POST',
+    request_body: requestBody,
+    idempotency_key: createKey,
+    acting_agent: actingAgent,
+  };
+  if (outboxRoot) await drainAndSummarize(outboxRoot, consoleFetch);
   let result;
   try {
     result = await consoleFetch('/api/specs', {
       method: 'POST',
       body: requestBody,
-      headers: { 'idempotency-key': idempotencyKey ?? randomUUID() },
+      headers: { 'idempotency-key': createKey },
       retryOnTimeout: false,
     });
   } catch (err) {
+    if (outboxRoot) {
+      const stashed = stashWrite(outboxRoot, {
+        ...createEntry,
+        failure: { status: 0, errorKind: 'network', message: String(err?.message ?? err).slice(0, 500) },
+      });
+      if (stashed) throw deferredError(routeLabel, consoleUrl, stashed, outboxRoot, { attempted: { type: requestBody.type, name: requestBody.name } });
+    }
     throw cloudWriteFailure(routeLabel, consoleUrl, String(err?.message ?? err), {
       attempted: { type: requestBody.type, name: requestBody.name },
+      ...outageRequest(noStash, { ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) }, createEntry),
     });
   }
   if (!result?.ok) {
+    const stashed = outboxRoot
+      ? stashIfOutage(result, createEntry, outboxRoot)
+      : null;
+    if (stashed) {
+      throw deferredError(routeLabel, result?.url ?? consoleUrl, stashed, outboxRoot, {
+        status: result?.status ?? null,
+        attempted: { type: requestBody.type, name: requestBody.name },
+      });
+    }
     throw cloudWriteFailure(routeLabel, result?.url ?? consoleUrl, describeResult(result), {
       status: result?.status ?? null,
       console_response: result?.body ?? null,
       attempted: { type: requestBody.type, name: requestBody.name },
+      ...outageRequest(noStash, result, createEntry),
       ...(result?.errorKind === 'timeout'
         ? {
             hint:
@@ -250,8 +338,11 @@ export async function updateSpecViaConsole({
   frontmatter,
   body,
   routeLabel = null,
+  vaultRoot = null,
+  noStash = false,
 }) {
   const route = routeLabel ?? `PUT /api/specs/${specId}`;
+  const outboxRoot = noStash ? null : vaultRoot ?? getWriteOutboxRoot();
   if (typeof consoleFetch !== 'function') {
     throw cloudWriteFailure(route, consoleUrl, 'no consoleFetch dependency was injected');
   }
@@ -261,20 +352,40 @@ export async function updateSpecViaConsole({
   if (typeof frontmatter !== 'object' || frontmatter === null) {
     throw cloudWriteFailure(route, consoleUrl, 'PUT /api/specs/:id requires a frontmatter object');
   }
+  const putPath = `/api/specs/${encodeURIComponent(specId)}`;
+  const putBody = { frontmatter, body: typeof body === 'string' ? body : '' };
+  const updateEntry = {
+    op: 'update',
+    kind: 'update',
+    route: putPath,
+    method: 'PUT',
+    request_body: putBody,
+    spec_id: specId,
+    // The cloud copy this edit was based on; replay refuses (cloud_newer)
+    // when the cloud has moved on since.
+    pre_image_updated: frontmatter?.updated ?? null,
+  };
+  const stashUpdate = (result) => (outboxRoot ? stashIfOutage(result, updateEntry, outboxRoot) : null);
+  if (outboxRoot) await drainAndSummarize(outboxRoot, consoleFetch);
   let result;
   try {
-    result = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`, {
-      method: 'PUT',
-      body: { frontmatter, body: typeof body === 'string' ? body : '' },
-    });
+    result = await consoleFetch(putPath, { method: 'PUT', body: putBody });
   } catch (err) {
-    throw cloudWriteFailure(route, consoleUrl, String(err?.message ?? err), { spec_id: specId });
+    const stashed = stashUpdate({ ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) });
+    if (stashed) throw deferredError(route, consoleUrl, stashed, outboxRoot, { spec_id: specId });
+    throw cloudWriteFailure(route, consoleUrl, String(err?.message ?? err), {
+      spec_id: specId,
+      ...outageRequest(noStash, { ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) }, updateEntry),
+    });
   }
   if (!result?.ok) {
+    const stashed = stashUpdate(result);
+    if (stashed) throw deferredError(route, result?.url ?? consoleUrl, stashed, outboxRoot, { status: result?.status ?? null, spec_id: specId });
     throw cloudWriteFailure(route, result?.url ?? consoleUrl, describeResult(result), {
       status: result?.status ?? null,
       console_response: result?.body ?? null,
       spec_id: specId,
+      ...outageRequest(noStash, result, updateEntry),
       ...(result?.status === 404 ? { notFound: true } : {}),
     });
   }
@@ -350,8 +461,10 @@ export async function listSpecsViaConsole({
  * `{ ok: false, error, completed }` — the same `{ ok }`-shaped verdict
  * `commitWrites` returns, so callers branch identically.
  */
-export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl = null, actingAgent = null } = {}) {
+export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl = null, actingAgent = null, vaultRoot = null } = {}) {
   const results = [];
+  const outboxRoot = vaultRoot ?? getWriteOutboxRoot();
+  if (outboxRoot && typeof consoleFetch === 'function') await drainAndSummarize(outboxRoot, consoleFetch);
   for (let i = 0; i < (writes ?? []).length; i++) {
     const w = writes[i];
     const { frontmatter, body } = splitRawSpec(w.content);
@@ -370,6 +483,7 @@ export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl
           frontmatter,
           body,
           actingAgent: meta.actingAgent ?? actingAgent,
+          noStash: true,
         });
         results.push({
           kind: 'create',
@@ -387,6 +501,7 @@ export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl
           specId,
           frontmatter,
           body,
+          noStash: true,
         });
         results.push({
           kind: 'update',
@@ -405,8 +520,83 @@ export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl
     } catch (err) {
       err.failed_step = { index: i, kind: w.kind, abs_path: w.absPath ?? null };
       err.completed_steps = results;
+      // Outage on step i: queue steps i..n-1 as ONE ordered batch (each step keeps
+      // its own idempotency key) so the remainder replays in order.
+      const failedReq = err.outage_request;
+      if (outboxRoot && failedReq) {
+        const steps = [failedReq];
+        for (let j = i + 1; j < writes.length; j++) {
+          const planned = planBatchStep(writes[j], actingAgent);
+          if (!planned) break;
+          steps.push(planned);
+        }
+        if (steps.length === writes.length - i) {
+          const stashed = stashWrite(outboxRoot, {
+            op: 'batch',
+            route: failedReq.route,
+            method: failedReq.method,
+            request_body: null,
+            acting_agent: actingAgent,
+            failure: failedReq.failure,
+            steps,
+            completed_steps: results,
+          });
+          if (stashed) {
+            const deferred = deferredError('commitWritesViaConsole', consoleUrl, stashed, outboxRoot, {
+              status: err.status ?? null,
+              failed_step: err.failed_step,
+              completed_steps: results,
+            });
+            return { ok: false, error: deferred, completed: results, deferred: true };
+          }
+        }
+      }
       return { ok: false, error: err, completed: results };
     }
   }
   return { ok: true, results };
 }
+
+/** Build a replayable batch step for a write that was never attempted. */
+function planBatchStep(w, actingAgent) {
+  const { frontmatter, body } = splitRawSpec(w.content);
+  const meta = w.cloud ?? {};
+  if (w.kind === 'create') {
+    const type = meta.type ?? frontmatter.type ?? null;
+    const name = meta.name ?? frontmatter.name ?? null;
+    if (!type || !name) return null;
+    const cleaned = stripServerMintedFields(frontmatter);
+    delete cleaned.name;
+    delete cleaned.type;
+    if (isDefaultInitialStatus(cleaned.status)) delete cleaned.status;
+    const summary = meta.summary ?? frontmatter.summary ?? null;
+    const agent = meta.actingAgent ?? actingAgent;
+    return {
+      kind: 'create',
+      route: '/api/specs',
+      method: 'POST',
+      request_body: {
+        type: String(type).trim(),
+        name: String(name).trim(),
+        ...(summary ? { summary } : {}),
+        ...(Object.keys(cleaned).length > 0 ? { frontmatter: cleaned } : {}),
+        body,
+        ...(agent ? { acting_agent: agent } : {}),
+      },
+      idempotency_key: randomUUID(),
+    };
+  }
+  if (w.kind === 'update') {
+    const specId = meta.specId ?? frontmatter.id ?? (w.absPath ? basenameFromRelPath(w.absPath) : null);
+    if (!specId) return null;
+    return {
+      kind: 'update',
+      route: `/api/specs/${encodeURIComponent(specId)}`,
+      method: 'PUT',
+      request_body: { frontmatter, body },
+      spec_id: specId,
+      pre_image_updated: frontmatter?.updated ?? null,
+    };
+  }
+  return null;
+}