heyspex 0.1.0 → 0.2.0

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

@@ -1,10 +1,21 @@
 /**
  * HeySpex settings MCP tools — the agent face over the settings core
- * (config-settings.mjs), mounted in cli.mjs as:
+ * (config-settings.mjs) and the settings registry (settings-registry.mjs),
+ * mounted in cli.mjs as:
  *   - heyspex_settings_list  (read — open)
  *   - heyspex_settings_get   (read — open)
  *   - heyspex_settings_set   (WRITE — permission-gated two-step confirm)
  *
+ * THIRD FACE (HS-OTEQ): these tools resolve every read through
+ * `getEffectiveSetting` (file value → registry default → absent) and the
+ * registry's key list, and every write through `validateSettingWrite` — the
+ * same functions the CLI face (`hs settings`) and, later, the console face
+ * resolve through. No fallback of its own: a registry-governed key answers
+ * identically no matter which face asks. A key the registry does not declare
+ * (e.g. `agent_behaviors.*`, `mvp_mode.*`) keeps working exactly as before —
+ * registry entries are additive, never a replacement for the freeform
+ * `.heyspex/config.yaml` surface.
+ *
  * WRITE-PERMISSION GUARDRAIL (owner directive 2026-07-11, documented in
  * specs/protocols/agent-settings-protocol.md): a settings write is a protected
  * class. `heyspex_settings_set` without `confirm_token` never writes — it records
@@ -16,31 +27,62 @@
  * (scripts/claude-hooks/settings-write-gate.mjs) additionally routes the confirm
  * call through the harness permission prompt in Claude Code.
  *
+ * `requestSettingsWrite` (step 1) and `confirmSettingsWrite`/`setConfigLeaf`
+ * (step 2) already run every write through `validateSettingWrite` inside the
+ * core, so this file does not re-validate — it only shapes the core's
+ * `{ ok:false, error, message }` refusal into the tool's response unchanged
+ * (never re-worded), which keeps the reason identical to what the CLI face
+ * gives for the same refused write.
+ *
  * Pattern source: procedure-tools.mjs (pure-logic execute* functions; cli.mjs wraps).
  */
 
 import {
   listConfigLeaves,
-  getConfigLeaf,
+  getEffectiveSetting,
   requestSettingsWrite,
   confirmSettingsWrite,
   validateSettingKey,
   CONFIG_REL,
 } from './config-settings.mjs';
+import { getSettingEntry, listRegistryKeys } from './settings-registry.mjs';
 
 const MCP_FACE = 'mcp';
 
+/** True when `key` equals `prefix` or is nested under it (dotted-segment match). */
+function matchesPrefix(key, prefix) {
+  return !prefix || key === prefix || key.startsWith(prefix + '.');
+}
+
 export function executeSettingsList(vaultRoot, args = {}) {
   const prefix = typeof args.prefix === 'string' ? args.prefix.trim() : '';
-  let settings = listConfigLeaves(vaultRoot);
-  if (prefix) {
-    settings = settings.filter((s) => s.key === prefix || s.key.startsWith(prefix + '.'));
+
+  const fileLeaves = listConfigLeaves(vaultRoot);
+  const seen = new Set();
+  const settings = [];
+
+  // Registry-declared keys first, in registry order, resolved through the same
+  // file → registry-default chain every face reads through — so a key never
+  // written to disk still appears, carrying its shipped default.
+  for (const key of listRegistryKeys()) {
+    if (!matchesPrefix(key, prefix)) continue;
+    const effective = getEffectiveSetting(vaultRoot, key);
+    settings.push({ key, value: effective.value, source: effective.source, found: effective.found });
+    seen.add(key);
   }
+
+  // Then any file leaf outside the registry's namespaces (agent_behaviors.*,
+  // mvp_mode.*, …) — additive, unchanged from the pre-registry behavior.
+  for (const leaf of fileLeaves) {
+    if (seen.has(leaf.key) || !matchesPrefix(leaf.key, prefix)) continue;
+    settings.push({ key: leaf.key, value: leaf.value, source: 'file', found: true });
+  }
+
   return {
     ok: true,
     config_file: CONFIG_REL.replace(/\\/g, '/'),
     count: settings.length,
-    settings: settings.map(({ key, value }) => ({ key, value })),
+    settings,
   };
 }
 
@@ -48,13 +90,26 @@ export function executeSettingsGet(vaultRoot, args = {}) {
   const key = typeof args.key === 'string' ? args.key.trim() : '';
   const check = validateSettingKey(key);
   if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
-  const leaf = getConfigLeaf(vaultRoot, key);
+
+  const effective = getEffectiveSetting(vaultRoot, key);
+  let note;
+  if (effective.source === 'registry_default') {
+    const entry = getSettingEntry(key);
+    note = `Key absent from .heyspex/config.yaml — resolved to the registry default (${entry?.description ?? 'see settings-registry.mjs'}).`;
+  } else if (effective.source === 'absent') {
+    note = 'Key absent from .heyspex/config.yaml and not declared in the settings registry — consumers fall back to their documented default.';
+  } else if (effective.source === 'computed') {
+    note =
+      'Computed live from the machine-local hs trust store (~/.heyspex/trusted-folders.json) — ' +
+      'never read from .heyspex/config.yaml. Read-only: revoke a folder with "hs trust revoke <path>".';
+  }
   return {
     ok: true,
     key,
-    found: leaf.found,
-    value: leaf.found ? leaf.value : null,
-    ...(leaf.found ? {} : { note: 'Key absent from .heyspex/config.yaml — consumers fall back to their documented default.' }),
+    found: effective.found,
+    value: effective.value,
+    source: effective.source,
+    ...(note ? { note } : {}),
   };
 }
 
@@ -81,14 +136,32 @@ export function executeSettingsSet(vaultRoot, args = {}) {
       face: MCP_FACE,
     });
     if (!result.ok) return result;
+    // MEASURED, NOT ASSUMED ([[HS-IOJW-5YDH-DIAG]] sweep). "applied and audited"
+    // used to be printed unconditionally while `appendSettingsAudit`'s boolean
+    // was thrown away inside `setConfigLeaf`, so a settings write with no audit
+    // row — the one artifact that makes a protected-class write reviewable after
+    // the fact — read exactly like a fully audited one. The config write itself
+    // DID land, so `ok` stays true and nothing is retried; `audited` + `status`
+    // are what let the caller tell a full success from a partial one.
+    const audited = result.audited === true;
     return {
       ok: true,
-      status: 'applied',
+      status: audited ? 'applied' : 'applied_not_audited',
+      partial: !audited,
+      audited,
       key: result.key,
       previous: result.previous,
       value: result.value,
       created: result.created,
-      note: 'Setting applied and audited to .heyspex/settings-history.jsonl.',
+      // HS-4C76 fix 3: the core seeds a missing config.yaml from the template on
+      // the first write instead of refusing; surface that so the caller can say so.
+      ...(result.seeded === true ? { seeded: true } : {}),
+      note: audited
+        ? `Setting applied and audited to .heyspex/settings-history.jsonl.${result.seeded === true ? ' (.heyspex/config.yaml was missing and was seeded from the template first.)' : ''}`
+        : 'Setting APPLIED to .heyspex/config.yaml, but the audit append to ' +
+          '.heyspex/settings-history.jsonl FAILED — this write has NO audit row. The value is live; do not ' +
+          're-apply it. Tell the user the change is in effect but unaudited, and check that ' +
+          '.heyspex/settings-history.jsonl is writable.',
     };
   }
 

package/vendor/heyspex-mcp/spec-edit-tools.mjs

@@ -0,0 +1,446 @@
+// Spec editing tools: heyspex_regen_task, regen_tasks_for_epic, backfill_epic,
+// edit_file, propose_metadata, list_known_tags, canvas_inbox. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeCanvasInbox } from './canvas-inbox.mjs';
+import { consoleFetch, controlError, controlOk } from './console-transport.mjs';
+import { detectTagDrift } from './plan-ground.mjs';
+import { consoleErrorMessage } from './console-fetch.mjs';
+import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
+import { resolveVaultWriteMode } from './read-path.mjs';
+import { splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
+import { writeFileSync } from 'node:fs';
+import { executeShipEpicCloudAware } from './plan-push.mjs';
+import { executeRegenTask, executeRegenTasksForEpic } from './regen-tasks.mjs';
+import { loadTask } from './vault-io.mjs';
+import { InvalidListCursorError, fitPageToByteBudget, resolvePageLimit } from './list-tools.mjs';
+import { DEFAULT_TOOL_BUDGET_BYTES } from './response-budget.mjs';
+
+export function handleRegenTask(vaultRoot, args = {}) {
+  const result = executeRegenTask(vaultRoot, {
+    task_id: args.task_id,
+    commit: args.commit === true || args.commit === 'true',
+    new_body: args.new_body,
+    retire_reason: args.retire_reason,
+    loadTask: (ref) => loadTask(vaultRoot, ref),
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    isError: result.ok === false,
+  };
+}
+
+export function handleRegenTasksForEpic(vaultRoot, args = {}) {
+  const result = executeRegenTasksForEpic(vaultRoot, {
+    epic_id: args.epic_id,
+    commit: args.commit === true || args.commit === 'true',
+    task_specs: args.task_specs,
+    loadTask: (ref) => loadTask(vaultRoot, ref),
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    isError: result.ok === false,
+  };
+}
+
+/**
+ * [[HS-Y00G-EPIC]] — Safe file edit: claim → write → release.
+ * Acquires the file claim, writes content to disk, and releases the claim.
+ * If claim fails (already claimed by another agent), returns the conflict info.
+ *
+ * WHERE THE WRITE GOES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+ * The write mode is resolved ONCE here, at the handler entry, and threaded to
+ * step 2 below:
+ *
+ *   - `local` — byte-identical to the original behavior: `writeFileSync` to
+ *     `args.file_path`, and the success payload carries exactly the fields it
+ *     always did.
+ *   - `cloud` — the mutated markdown is split back into the
+ *     `{ frontmatter, body }` pair `PUT /api/specs/:id` takes and sent through
+ *     {@link updateSpecViaConsole}. Nothing touches this machine's disk: a
+ *     markdown file written in cloud reliance is a split brain, a document on a
+ *     machine the console's index has never heard of (and that may hold no
+ *     vault clone at all).
+ *
+ * The spec id comes from the POST-EDIT content's own `id:` frontmatter — the
+ * caller has already produced the finished document, so its frontmatter is the
+ * authority on which spec this edit replaces. Content with no resolvable `id:`
+ * (a non-spec file, or a spec fragment) has NO cloud route: there is no console
+ * verb for "write these bytes to this arbitrary path". That degrades explicitly
+ * as `CLOUD_MODE_UNSUPPORTED_WRITE` naming the file — never a silent fallback
+ * to the disk write the mode just forbade.
+ *
+ * @param {object} args
+ * @param {object} [deps] Injection seam so tests drive every branch without a
+ *   socket: `consoleFetch` (defaults to the real transport), `consoleUrl`
+ *   (defaults to `getConsoleUrl()`), `resolveWriteMode` (defaults to
+ *   `resolveVaultWriteMode`).
+ */
+export async function handleEditFile(args = {}, deps = {}) {
+  if (!args.file_path || typeof args.file_path !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'file_path is required' }) }],
+    };
+  }
+  if (typeof args.content !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'content is required and must be a string' }) }],
+    };
+  }
+
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const fetchDep = deps.consoleFetch ?? consoleFetch;
+  // Resolved ONCE per handler entry, then threaded to step 2. `?? 'local'`
+  // keeps every pre-existing caller on exactly the disk write it had.
+  const writeMode = (await (deps.resolveWriteMode ?? resolveVaultWriteMode)()) ?? 'local';
+
+  // Step 1: Acquire claim
+  const claimBody = {
+    file_path: args.file_path,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    ttl_ms: 300000, // 5-minute default for file claims
+  };
+  if (args.working_spec_id && typeof args.working_spec_id === 'string') {
+    claimBody.working_spec_id = args.working_spec_id;
+  }
+
+  const claimResult = await fetchDep('/api/file-claims/acquire', { method: 'POST', body: claimBody });
+
+  if (claimResult.status === 409) {
+    const conflict = claimResult.body && typeof claimResult.body === 'object' ? claimResult.body : {};
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({
+        error: 'FILE_CLAIMED',
+        message: `CONFLICT: file "${args.file_path}" is claimed by another agent.`,
+        claimed_by: conflict.existing?.agent ?? 'unknown',
+        claimed_session: conflict.existing?.sessionId ?? null,
+        expires_at: conflict.existing?.expiresAt ?? null,
+        conflict: conflict,
+      }, null, 2) }],
+    };
+  }
+
+  if (!claimResult.ok) {
+    return controlError(claimResult, 'EDIT_FILE_CLAIM_FAILED', { file_path: args.file_path });
+  }
+
+  // Always release before returning a failure, so a rejected write never leaves
+  // the file locked for the claim's full TTL.
+  const releaseClaim = () =>
+    fetchDep('/api/file-claims/release', { method: 'DELETE', body: { file_path: args.file_path } });
+
+  // Step 2: Write — to disk in local mode, to `PUT /api/specs/:id` in cloud mode.
+  let cloudWrite = null;
+  if (writeMode === 'cloud') {
+    const consoleUrl = deps.consoleUrl ?? getConsoleUrl();
+    const { frontmatter, body } = splitRawSpec(args.content);
+    const specId = typeof frontmatter?.id === 'string' ? frontmatter.id.trim() : '';
+    if (!specId) {
+      await releaseClaim();
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'CLOUD_MODE_UNSUPPORTED_WRITE',
+          message:
+            `heyspex_edit_file cannot write "${args.file_path}" in cloud vault-write mode: the content carries no `
+            + '`id:` frontmatter, and the console has no route that writes arbitrary bytes to an arbitrary path '
+            + '(POST /api/specs creates a typed spec, PUT /api/specs/:id replaces one by id). NOTHING WAS WRITTEN — '
+            + 'the local disk write is deliberately NOT used as a fallback, because a file written here would be '
+            + 'invisible to the console index this session reads from.',
+          file_path: args.file_path,
+          write_mode: 'cloud',
+          console_url: consoleUrl,
+          on_disk: false,
+        }, null, 2) }],
+      };
+    }
+    try {
+      cloudWrite = await updateSpecViaConsole({
+        consoleFetch: fetchDep,
+        consoleUrl,
+        specId,
+        frontmatter,
+        body,
+      });
+    } catch (err) {
+      await releaseClaim();
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+          message: String(err?.message ?? err),
+          file_path: args.file_path,
+          spec_id: specId,
+          write_mode: 'cloud',
+          on_disk: false,
+          ...(err?.notFound ? { not_found: true } : {}),
+        }, null, 2) }],
+      };
+    }
+  } else {
+    try {
+      writeFileSync(args.file_path, args.content, 'utf8');
+    } catch (err) {
+      // Release the claim on write failure so the file isn't locked forever
+      await releaseClaim();
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'WRITE_FAILED',
+          message: `Failed to write file: ${err?.message ?? err}`,
+          file_path: args.file_path,
+        }) }],
+      };
+    }
+  }
+
+  // Step 3: Release claim
+  const releaseResult = await releaseClaim();
+
+  return controlOk({
+    written: true,
+    file_path: args.file_path,
+    released: releaseResult.ok ? releaseResult.body?.released ?? true : false,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    // Cloud-only additions — the local payload stays byte-identical to the
+    // shape every existing caller already parses.
+    ...(cloudWrite
+      ? {
+          write_mode: 'cloud',
+          on_disk: false,
+          spec_id: cloudWrite.specId,
+          rel_path: cloudWrite.relPath,
+          console_url: cloudWrite.consoleUrl,
+        }
+      : {}),
+  });
+}
+
+/**
+ * Known-tags paging contract, mirrored from the console route
+ * (`spex-console/src/lib/scheduler/known-tags-query.ts`): the cursor is
+ * base64url JSON `{ c: count, t: tag }` over the `(count DESC, tag ASC)` sort
+ * key of the aggregate query. Encoded here only to RE-POINT the cursor when the
+ * byte budget trims a page — the console mints every cursor it hands out.
+ */
+export const KNOWN_TAGS_TOOL = Object.freeze({
+  default_limit: 100,
+  max_limit: 500,
+  // Measured on `content[0].text`; the dispatcher re-measures the whole envelope (escaped), so leave headroom.
+  byte_budget: Math.floor(DEFAULT_TOOL_BUDGET_BYTES * 0.8),
+});
+
+export function encodeKnownTagsCursor({ count, tag }) {
+  return Buffer.from(JSON.stringify({ c: Number(count) || 0, t: String(tag ?? '') }), 'utf8').toString('base64url');
+}
+
+/**
+ * `heyspex_list_known_tags` — the closed tag vocabulary for the focus-areas NLU
+ * path ([[HS-TASK-I0EK]] / [[HS-EPIC-7WJN]]). GET /api/scheduler/known-tags →
+ * ONE page `{ tags: [{ name, count }], next_cursor, page }` from an aggregate
+ * query paged with a keyset cursor over (count, tag)
+ * ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]], resolving
+ * [[HS-7QM6-1Q1C-DIAG-heyspex-list-known-tags-response-busts-t]] — the reply
+ * that once hit 138 KB). `limit` and `after` pass straight through to the
+ * console; the page is then fitted to the tool's byte budget, re-pointing
+ * `next_cursor` at the last tag kept so nothing is lost. Agents call this
+ * before proposing a focus pivot so they only suggest tags that exist.
+ * Requires a reachable console.
+ *
+ * Augments the console response with an additive `drift` array ([[HS-TASK-H0SI]]
+ * / [[HS-EPIC-OOPW]]): near-duplicate tag pairs within the page flagged by
+ * lexical string similarity (NOT embeddings) so the agent can propose a merge to
+ * keep the closed vocabulary clean. No tag is mutated here — `drift` is a
+ * suggestion signal only.
+ */
+export async function handleListKnownTags(args = {}, { consoleFetch: fetchDep = consoleFetch, byteBudget = KNOWN_TAGS_TOOL.byte_budget } = {}) {
+  const limit = resolvePageLimit(args.limit, KNOWN_TAGS_TOOL);
+  const params = new URLSearchParams({ limit: String(limit) });
+  if (typeof args.after === 'string' && args.after) params.set('after', args.after);
+  const result = await fetchDep(`/api/scheduler/known-tags?${params.toString()}`);
+  if (!result.ok) {
+    if (result.status === 400 && result.body?.error === 'invalid_cursor') {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_CURSOR', message: new InvalidListCursorError().message, tool: 'heyspex_list_known_tags' }, null, 2) }],
+      };
+    }
+    return controlError(result, 'KNOWN_TAGS_FAILED');
+  }
+  const body = result.body && typeof result.body === 'object' ? result.body : {};
+  const tags = Array.isArray(body.tags) ? body.tags : [];
+  const base = {
+    ...body,
+    tags,
+    next_cursor: typeof body.next_cursor === 'string' && body.next_cursor ? body.next_cursor : null,
+    page: { limit, returned: tags.length, byte_budget: byteBudget, budget_trimmed: false, ...(body.page ?? {}) },
+  };
+  const fitOpts = {
+    rows_key: 'tags',
+    // A page of tags that would fill the whole budget leaves no room for the
+    // drift signal the tool exists to surface: reserve a tenth for the
+    // strongest pairs. A page that needs no trim gets the whole budget.
+    byte_budget: byteBudget - Math.floor(byteBudget * 0.1),
+    cursorFor: (row) => encodeKnownTagsCursor({ count: row.count, tag: row.name }),
+  };
+  // 1. Fit the TAGS to the budget first (with an empty drift envelope in
+  //    place so its bytes are accounted for) — the cursor must land on a tag
+  //    the caller received, and drift over an un-returned tag is noise.
+  let current = fitPageToByteBudget({ ...base, drift: [] }, fitOpts).result;
+  // 2. Drift over the returned page only. It is pairwise (quadratic in page
+  //    size) and sorted by similarity desc, so when it would bust the budget
+  //    keep the strongest pairs that fit. Only when not even zero pairs fit
+  //    (the truncation markers cost a few bytes) does one more tag go, and
+  //    drift is recomputed over what remains.
+  for (;;) {
+    const fitted = fitKnownTagsDrift(current, detectTagDrift(current.tags), byteBudget);
+    if (fitted) return { content: [{ type: 'text', text: fitted.text }] };
+    if (current.tags.length <= 1) {
+      // A lone tag that cannot fit even with no drift: return it rather than
+      // an empty page with no way forward (the list-tools rule).
+      return { content: [{ type: 'text', text: JSON.stringify({ ...current, drift: [] }, null, 2) }] };
+    }
+    const kept = current.tags.slice(0, -1);
+    current = {
+      ...current,
+      tags: kept,
+      next_cursor: fitOpts.cursorFor(kept[kept.length - 1]),
+      page: { ...current.page, returned: kept.length, budget_trimmed: true },
+    };
+  }
+}
+
+/**
+ * Largest similarity-desc prefix of `drift` whose page fits `byteBudget`:
+ * the whole list untouched when it fits, else `page.drift_truncated: true` +
+ * `drift_dropped`. `null` when not even an empty drift list fits.
+ */
+function fitKnownTagsDrift(page, drift, byteBudget) {
+  const serialize = (payload) => JSON.stringify(payload, null, 2);
+  const fits = (text) => Buffer.byteLength(text, 'utf8') <= byteBudget;
+  const full = { ...page, drift };
+  const fullText = serialize(full);
+  if (fits(fullText)) return { payload: full, text: fullText };
+  let lo = 0;
+  let hi = drift.length - 1;
+  let best = null;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const candidate = { ...page, drift: drift.slice(0, mid), page: { ...page.page, drift_truncated: true, drift_dropped: drift.length - mid } };
+    const text = serialize(candidate);
+    if (fits(text)) {
+      best = { payload: candidate, text };
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+/**
+ * AI metadata proposal — [[HS-TASK-TAOD]] Phase 4 of [[HS-EPIC-Y9OJ]].
+ *
+ * Thin MCP wrapper around console `POST /api/ai/propose-metadata` (Haiku 4.5).
+ * One-shot at create time — agents must NOT call this on edit, status change,
+ * or update flows; that's the closed-loop bias the epic explicitly rejects.
+ */
+export async function handleProposeMetadata(args = {}) {
+  const name = typeof args?.name === 'string' ? args.name : '';
+  const body = typeof args?.body === 'string' ? args.body : '';
+  if (!name.trim() && !body.trim()) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { ok: false, reason: 'invalid_request', message: 'name or body is required' },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  const payload = { action: 'propose', name, body };
+  if (typeof args?.specType === 'string') payload.specType = args.specType;
+  if (typeof args?.parentExcerpt === 'string') payload.parentExcerpt = args.parentExcerpt;
+
+  const result = await consoleFetch('/api/ai/propose-metadata', {
+    method: 'POST',
+    body: payload,
+  });
+
+  if (!result.ok) {
+    const reason =
+      result.errorKind === 'timeout'
+        ? 'console_timeout'
+        : result.status === 0
+          ? 'console_unreachable'
+          : 'console_error';
+    const errorPayload = {
+      ok: false,
+      reason,
+      message: consoleErrorMessage(
+        result,
+        `Console /api/ai/propose-metadata returned ${result.status}`,
+      ),
+      console_response: result.body,
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(errorPayload, null, 2) }],
+    };
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result.body, null, 2) }],
+  };
+}
+
+// Ground-truth dev-server status. The heavy logic lives in the repo's
+// scripts/dev-server-status.mjs (the shared core for the hs CLI verb and the
+// PreToolUse reminder hook too); we dynamic-import it from the vault root so
+// the three faces stay in lockstep. Must never throw out of the tool call.
+export async function handleCanvasInbox(vaultRoot, args = {}) {
+  // Session id: explicit arg wins; otherwise the ambient Claude Code session.
+  const explicit = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  const sessionId =
+    explicit ||
+    (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || '').trim();
+
+  const result = await executeCanvasInbox({ vaultRoot, sessionId });
+  return {
+    ...(result.ok ? {} : { isError: true }),
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * `heyspex_ship_epic` / `backfill_epic`. Cloud-aware entry
+ * ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]] sweep):
+ * `executeShipEpicCloudAware` resolves `resolveVaultWriteMode()` ONCE and either
+ * runs the untouched synchronous disk path (`local`) or creates the epic, its
+ * tasks and the review doc through `POST /api/specs` in create-first/link-second
+ * order (`cloud`). The handler became `async` for that — awaiting is safe in
+ * both modes, since the local branch still returns the same plain object.
+ */
+export async function handleShipEpic(vaultRoot, args) {
+  const result = await executeShipEpicCloudAware(vaultRoot, args);
+  if (result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}