@ijfw/memory-server 1.4.3 → 1.5.0

package/src/design/iframe-bridge.js

@@ -0,0 +1,242 @@
+/**
+ * IJFW design iframe bridge -- optional vercel:vercel-sandbox composition.
+ *
+ * IJFW core has zero runtime deps and ships a static viewer for design mockups.
+ * When the peer `vercel:vercel-sandbox` skill is present (or the user has set
+ * `IJFW_VERCEL_SANDBOX_URL` to a provisioner endpoint), this bridge upgrades
+ * the static viewer to live iframes running each mockup in an isolated
+ * Firecracker microVM via the vercel-sandbox skill.
+ *
+ * **Every entrypoint graceful-fails.** A missing CLI, an unset env var, a
+ * malformed response, or a network error all return null/false rather than
+ * throwing. The caller MUST fall back to the static-srcdoc viewer in that case.
+ *
+ * Why composition over a hard dep: IJFW is a meta-tool. Pinning vercel-sandbox
+ * would import sandboxing concerns into IJFW's trust model. Peer-skill detection
+ * keeps the boundary clean (and keeps the npm install size at zero).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+
+const SANDBOX_URL_ENV = 'IJFW_VERCEL_SANDBOX_URL';
+const PROVISION_TIMEOUT_MS = 15_000;
+const DESTROY_TIMEOUT_MS = 5_000;
+
+/** In-process registry of sandbox ids → provisioner URL for destroySandbox(). */
+const _sandboxRegistry = new Map();
+
+/**
+ * Returns true when EITHER the `vercel` CLI is on PATH OR
+ * `IJFW_VERCEL_SANDBOX_URL` env var is set.
+ *
+ * Cheap. Safe to call repeatedly (a few ms `which` shell-out worst case).
+ */
+export function hasVercelSandbox() {
+  if (process.env[SANDBOX_URL_ENV]) return true;
+  try {
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    const r = spawnSync(which, ['vercel'], { encoding: 'utf8', timeout: 2_000 });
+    if (r.status === 0 && r.stdout && r.stdout.trim()) return true;
+  } catch {
+    // graceful: missing `which`/`where` is the same as no CLI
+  }
+  return false;
+}
+
+/**
+ * Provision a sandbox preview for an HTML mockup. Returns
+ *   { iframeUrl, sandboxId }   on success
+ *   null                       when bridge unavailable OR any failure
+ *
+ * The function is never expected to throw. All errors are logged advisory
+ * to stderr so the user understands why fallback kicked in, then null is
+ * returned and the caller renders the static-srcdoc viewer.
+ *
+ * @param {{ html: string, name?: string }} args
+ * @returns {Promise<{iframeUrl: string, sandboxId: string} | null>}
+ */
+export async function createPreviewSandbox({ html, name } = {}) {
+  if (typeof html !== 'string' || !html.trim()) {
+    _advise('createPreviewSandbox: html missing -- skipping');
+    return null;
+  }
+  if (!hasVercelSandbox()) return null;
+
+  const safeName = String(name || 'mockup').replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 64) || 'mockup';
+  const sandboxId = `ijfw-${safeName}-${randomUUID().slice(0, 8)}`;
+
+  // Write the html to a temp file so the provisioner can read it.
+  let tmpFile = null;
+  try {
+    const dir = join(tmpdir(), 'ijfw-design-sandboxes');
+    mkdirSync(dir, { recursive: true });
+    tmpFile = join(dir, `${sandboxId}.html`);
+    writeFileSync(tmpFile, html, 'utf8');
+  } catch (err) {
+    _advise(`createPreviewSandbox: temp write failed -- ${err.message}`);
+    return null;
+  }
+
+  // Prefer the env-configured HTTP provisioner when present (test-friendly,
+  // matches how the vercel-sandbox MCP skill exposes its provisioning API).
+  const url = process.env[SANDBOX_URL_ENV];
+  if (url) {
+    const result = await _provisionViaHttp(url, { html, name: safeName, sandboxId });
+    if (result) {
+      _sandboxRegistry.set(sandboxId, { mode: 'http', url });
+      return result;
+    }
+    return null;
+  }
+
+  // Fall back to shell-out to `vercel sandbox` CLI. Best-effort: the CLI
+  // surface for vercel-sandbox is evolving; we accept any JSON line that
+  // contains a `url` field.
+  try {
+    const r = spawnSync('vercel', ['sandbox', 'create', '--file', tmpFile, '--name', sandboxId], {
+      encoding: 'utf8',
+      timeout: PROVISION_TIMEOUT_MS,
+    });
+    if (r.status !== 0) {
+      _advise(`createPreviewSandbox: vercel CLI exit ${r.status} -- falling back to static`);
+      return null;
+    }
+    const iframeUrl = _extractUrl(r.stdout);
+    if (!iframeUrl) {
+      _advise('createPreviewSandbox: vercel CLI produced no URL -- falling back to static');
+      return null;
+    }
+    _sandboxRegistry.set(sandboxId, { mode: 'cli' });
+    return { iframeUrl, sandboxId };
+  } catch (err) {
+    _advise(`createPreviewSandbox: CLI invocation failed -- ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Tear down a sandbox by id. Never throws. Best-effort.
+ */
+export async function destroySandbox(sandboxId) {
+  if (!sandboxId) return;
+  const entry = _sandboxRegistry.get(sandboxId);
+  if (!entry) return;
+  _sandboxRegistry.delete(sandboxId);
+
+  try {
+    if (entry.mode === 'http') {
+      await _httpRequest(
+        'DELETE',
+        `${entry.url.replace(/\/$/, '')}/sandboxes/${encodeURIComponent(sandboxId)}`,
+        null,
+        DESTROY_TIMEOUT_MS,
+      );
+      return;
+    }
+    if (entry.mode === 'cli') {
+      spawnSync('vercel', ['sandbox', 'delete', sandboxId], { encoding: 'utf8', timeout: DESTROY_TIMEOUT_MS });
+      return;
+    }
+  } catch (err) {
+    _advise(`destroySandbox(${sandboxId}): ${err.message}`);
+  }
+}
+
+// ---------- internals ----------
+
+async function _provisionViaHttp(baseUrl, { html, name, sandboxId }) {
+  try {
+    const payload = JSON.stringify({ html, name, sandboxId });
+    const res = await _httpRequest(
+      'POST',
+      `${baseUrl.replace(/\/$/, '')}/sandboxes`,
+      payload,
+      PROVISION_TIMEOUT_MS,
+    );
+    if (!res || res.status < 200 || res.status >= 300) {
+      _advise(`HTTP provisioner returned ${res ? res.status : 'no response'}`);
+      return null;
+    }
+    let body;
+    try { body = JSON.parse(res.body); } catch {
+      _advise('HTTP provisioner returned non-JSON');
+      return null;
+    }
+    const iframeUrl = body && (body.iframeUrl || body.url);
+    if (!iframeUrl) {
+      _advise('HTTP provisioner response missing url field');
+      return null;
+    }
+    return { iframeUrl: String(iframeUrl), sandboxId: String(body.sandboxId || sandboxId) };
+  } catch (err) {
+    _advise(`HTTP provisioner failed -- ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Minimal http(s) client using node:http / node:https. Avoids `fetch`
+ * because we want deterministic timeouts and zero-dep behavior on every
+ * supported Node version.
+ */
+function _httpRequest(method, url, body, timeoutMs) {
+  return new Promise((resolve) => {
+    try {
+      const parsed = new URL(url);
+      const mod = parsed.protocol === 'https:' ? https : http;
+      const opts = {
+        method,
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers: body
+          ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) }
+          : {},
+        timeout: timeoutMs,
+      };
+      const req = mod.request(opts, (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+        res.on('error', () => resolve(null));
+      });
+      req.on('error', () => resolve(null));
+      req.on('timeout', () => {
+        try { req.destroy(); } catch {}
+        resolve(null);
+      });
+      if (body) req.write(body);
+      req.end();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+function _extractUrl(text) {
+  if (!text) return null;
+  // JSON-encoded url field
+  const jsonMatch = String(text).match(/"(?:iframeUrl|url)"\s*:\s*"(https?:\/\/[^"\s]+)"/);
+  if (jsonMatch) return jsonMatch[1];
+  // Bare URL printed by the CLI
+  const bare = String(text).match(/(https?:\/\/[^\s"]+\.vercel\.app[^\s"]*)/);
+  return bare ? bare[1] : null;
+}
+
+function _advise(msg) {
+  try {
+    process.stderr.write(`[ijfw design] ${msg}\n`);
+  } catch {
+    // never throw from advisory log
+  }
+}
+
+// Exported for tests
+export const __internals = { _extractUrl, _sandboxRegistry, SANDBOX_URL_ENV };

package/src/design-companion.js

@@ -6,6 +6,7 @@
 import { EventEmitter } from 'node:events';
 import { existsSync, readdirSync, statSync, watch } from 'node:fs';
 import { join } from 'node:path';
+import { createPreviewSandbox as defaultCreatePreviewSandbox } from './design/iframe-bridge.js';
 
 export const PLACEHOLDER_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -52,6 +53,149 @@ export function getNewestFile(contentDir) {
   return newest;
 }
 
+/**
+ * HTML-escape helper for the viewer codegen. Mirrors the audit-H3.1
+ * dashboard `esc()` -- escapes ampersand, angle brackets, double-quote, AND
+ * single-quote so output is safe inside single- or double-quoted attributes.
+ */
+export function escHtml(s) {
+  if (s === null || s === undefined) return '';
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Build a tabbed viewer for a list of HTML mockups.
+ *
+ * Each mockup may carry an optional `iframeUrl` (provisioned via the
+ * `vercel:vercel-sandbox` peer skill). When the URL is present the viewer
+ * renders a live `<iframe src="...">` running in an isolated Firecracker
+ * microVM. When absent, the viewer falls back to a static `<iframe srcdoc>`
+ * with the html inlined. Either way the iframe carries
+ * `sandbox="allow-scripts"` to prevent top-window escape (v1.5.0 Trident r19
+ * dropped allow-same-origin; the combination is a documented MDN sandbox
+ * escape — JS still runs in the mockup but the embedded document can't reach
+ * window.parent to remove its own sandbox attribute).
+ *
+ * All user-controlled strings (mockup name, iframe url) flow through
+ * `escHtml()` -- the same pattern dashboard `esc()` uses post-audit-H3.1.
+ *
+ * @param {{ mockups: Array<{name: string, html?: string, iframeUrl?: string|null}>, title?: string }} args
+ * @returns {string} HTML document for the viewer.
+ */
+export function buildMockupViewer({ mockups = [], title = 'IJFW Design Mockups' } = {}) {
+  const items = Array.isArray(mockups) ? mockups : [];
+  const safeTitle = escHtml(title);
+
+  const tabs = items
+    .map((m, i) => {
+      const name = escHtml(m && m.name ? m.name : `mockup-${i + 1}`);
+      return `<button class="tab" data-i="${i}" ${i === 0 ? 'aria-selected="true"' : ''}>${name}</button>`;
+    })
+    .join('');
+
+  const panes = items
+    .map((m, i) => {
+      const name = escHtml(m && m.name ? m.name : `mockup-${i + 1}`);
+      const isLive = m && typeof m.iframeUrl === 'string' && m.iframeUrl;
+      // v1.5.0 Trident r19 fix: drop allow-same-origin. With both allow-scripts
+      // AND allow-same-origin set, the embedded document can programmatically
+      // remove the sandbox attribute via window.parent.document (MDN sandbox
+      // escape). allow-scripts alone keeps the mockup dynamic while preventing
+      // any cross-origin reach into the host viewer.
+      const inner = isLive
+        ? `<iframe class="preview" src="${escHtml(m.iframeUrl)}" title="${name}" sandbox="allow-scripts" loading="lazy"></iframe>`
+        : `<iframe class="preview" srcdoc="${escHtml(m && m.html ? m.html : '<!doctype html><meta charset=utf-8><p>(no preview)</p>')}" title="${name}" sandbox="allow-scripts" loading="lazy"></iframe>`;
+      const badge = isLive
+        ? '<span class="badge live" title="Provisioned via vercel:vercel-sandbox">LIVE</span>'
+        : '<span class="badge static" title="Static srcdoc preview -- install vercel CLI or set IJFW_VERCEL_SANDBOX_URL for live sandbox">STATIC</span>';
+      return `<section class="pane" data-i="${i}" ${i === 0 ? '' : 'hidden'}>
+  <header class="phead">${name} ${badge}</header>
+  ${inner}
+</section>`;
+    })
+    .join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${safeTitle}</title>
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:#0f172a;color:#e2e8f0;font-family:system-ui,-apple-system,sans-serif;min-height:100vh;display:flex;flex-direction:column}
+  .tabs{display:flex;flex-wrap:wrap;gap:4px;padding:8px;background:#1e293b;border-bottom:1px solid #334155}
+  .tab{background:#334155;color:#e2e8f0;border:1px solid #475569;border-radius:6px;padding:6px 12px;cursor:pointer;font-size:13px}
+  .tab[aria-selected="true"]{background:#0369a1;border-color:#0ea5e9}
+  .pane{flex:1;display:flex;flex-direction:column;min-height:0}
+  .phead{padding:6px 12px;background:#0f172a;border-bottom:1px solid #1e293b;font-size:12px;color:#94a3b8;display:flex;gap:8px;align-items:center}
+  .badge{font-size:10px;font-weight:600;padding:2px 6px;border-radius:4px;letter-spacing:.04em}
+  .badge.live{background:#15803d;color:#fff}
+  .badge.static{background:#475569;color:#cbd5e1}
+  .preview{flex:1;width:100%;border:0;background:#fff;min-height:400px}
+</style>
+</head>
+<body>
+<nav class="tabs" role="tablist">${tabs || '<span style="color:#64748b;padding:6px 12px">No mockups yet.</span>'}</nav>
+${panes}
+<script>
+(function(){
+  var tabs = document.querySelectorAll('.tab');
+  var panes = document.querySelectorAll('.pane');
+  tabs.forEach(function(t){
+    t.addEventListener('click', function(){
+      var i = t.getAttribute('data-i');
+      tabs.forEach(function(x){ x.setAttribute('aria-selected', x === t ? 'true' : 'false'); });
+      panes.forEach(function(p){
+        if (p.getAttribute('data-i') === i) p.removeAttribute('hidden'); else p.setAttribute('hidden','');
+      });
+    });
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Provision per-mockup iframes via the vercel-sandbox bridge when available,
+ * then render the tabbed viewer. Falls back to static `<iframe srcdoc>` for
+ * any mockup whose provisioning failed (or for all of them if the bridge
+ * is unavailable).
+ *
+ * @param {object}  args
+ * @param {Array<{name: string, html: string}>} args.mockups  Mockup inputs.
+ * @param {Function} [args.createSandbox]  Override for the bridge (test seam).
+ *                                          Should match the createPreviewSandbox signature.
+ * @param {string}  [args.title]
+ * @returns {Promise<{html: string, sandboxIds: string[]}>}
+ */
+export async function renderMockupViewerWithBridge({ mockups = [], createSandbox, title } = {}) {
+  const fn = typeof createSandbox === 'function' ? createSandbox : defaultCreatePreviewSandbox;
+  const enriched = [];
+  const sandboxIds = [];
+  for (const m of mockups) {
+    let iframeUrl = null;
+    try {
+      const r = await fn({ html: m.html, name: m.name });
+      if (r && r.iframeUrl) {
+        iframeUrl = r.iframeUrl;
+        if (r.sandboxId) sandboxIds.push(r.sandboxId);
+      }
+    } catch {
+      // bridge promised never to throw; this catch is defense-in-depth.
+      iframeUrl = null;
+    }
+    enriched.push({ name: m.name, html: m.html, iframeUrl });
+  }
+  return { html: buildMockupViewer({ mockups: enriched, title }), sandboxIds };
+}
+
 /**
  * Watches contentDir for new/changed .html files.
  * Returns an EventEmitter that emits 'new-content' (with the file path) on change.

package/src/dispatch/checkpoint-cli.js

@@ -0,0 +1,97 @@
+/**
+ * dispatch/checkpoint-cli.js — IJFW v1.5.0 / S1 subagent checkpoint CLI.
+ *
+ * Frozen export contract (v1.4.3 dispatch module convention):
+ *   export const handlers = { '<subcommand>': async (args, ctx) => ({ ok, output?, error? }) };
+ *   export const subcommandHelp = { '<subcommand>': 'one-line description' };
+ *
+ * Subcommands owned by this module:
+ *   - checkpoint <waveId> <subId> <jsonPayload>
+ *
+ * Writes via mcp-server/src/orchestrator/subagent-telemetry.js (W11-A0).
+ * Used by implementer subagents to persist progress before the Claude Code
+ * harness ~20-tool / 60s wall-clock cap fires (v1.5.0 S1 — closes 8/13
+ * truncation pattern from v1.4.4 Wave 10 + v1.5.0 research).
+ *
+ * Wire-up into extension.js is handled by orchestrator post-Wave-11-A.
+ */
+
+import { recordCheckpoint } from '../orchestrator/subagent-telemetry.js';
+
+function tokenize(args) {
+  if (Array.isArray(args)) return args.filter((x) => x !== undefined && x !== null);
+  if (typeof args !== 'string') return [];
+  // Checkpoint args are: <waveId> <subId> <jsonPayload>.
+  // The JSON payload may contain spaces — split into at most 3 tokens so the
+  // payload survives intact regardless of internal whitespace.
+  const trimmed = args.trim();
+  if (!trimmed) return [];
+  const firstSpace = trimmed.indexOf(' ');
+  if (firstSpace === -1) return [trimmed];
+  const secondSpace = trimmed.indexOf(' ', firstSpace + 1);
+  if (secondSpace === -1) return [trimmed.slice(0, firstSpace), trimmed.slice(firstSpace + 1)];
+  return [
+    trimmed.slice(0, firstSpace),
+    trimmed.slice(firstSpace + 1, secondSpace),
+    trimmed.slice(secondSpace + 1),
+  ];
+}
+
+async function handleCheckpoint(args, ctx) {
+  const tokens = tokenize(args);
+  const [waveId, subId, payloadJson] = tokens;
+  if (!waveId || !subId || !payloadJson) {
+    return {
+      ok: false,
+      error: 'Usage: ijfw checkpoint <waveId> <subId> <jsonPayload>',
+    };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(payloadJson);
+  } catch (err) {
+    return {
+      ok: false,
+      error: `ijfw checkpoint: invalid JSON payload — ${err.message}`,
+    };
+  }
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    return {
+      ok: false,
+      error: 'ijfw checkpoint: JSON payload must be a JSON object (not array/null/scalar)',
+    };
+  }
+
+  const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+
+  // v1.5.0-major S01: log the effective root (parent vs worktree) to stderr for
+  // debugging worktree-mode checkpoint visibility issues.
+  const effectiveRoot = process.env.IJFW_PARENT_PROJECT_ROOT ?? projectRoot;
+  try {
+    process.stderr.write(
+      `ijfw checkpoint: writing to ${effectiveRoot}/.ijfw/wave-${waveId}/\n`,
+    );
+  } catch {
+    // stderr write failure must never break the checkpoint path
+  }
+
+  try {
+    await recordCheckpoint(waveId, subId, payload, projectRoot);
+    return { ok: true, output: `ok: wrote checkpoint for ${waveId}/${subId}` };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `ijfw checkpoint: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+}
+
+export const handlers = Object.freeze({
+  checkpoint: handleCheckpoint,
+});
+
+export const subcommandHelp = Object.freeze({
+  checkpoint:
+    'checkpoint <waveId> <subId> <jsonPayload> — record a subagent checkpoint (v1.5.0 S1)',
+});

package/src/dispatch/colon-syntax.js

@@ -47,6 +47,11 @@ import { dirname, join } from 'path';
 // so the user-facing spelling 'domain-manifest:<op>' (matching the error
 // message and CLI surface) parses + routes uniformly. The set entry is the
 // hyphenated form so copy-paste from the error string Just Works.
+// v1.5.0 (T12): added 'state' — the state-SDK CLI face. Routes
+// `state:<verb> <json-payload>` straight into orchestrator/state-sdk.js
+// `query(verb, payload, ctx)`. This is the external-tooling surface for the
+// state-SDK; the JS module is the in-process surface and the MCP tool is the
+// remote surface (contract §0).
 const RUN_NAMESPACES = new Set([
   'compute',
   'index',
@@ -55,6 +60,7 @@ const RUN_NAMESPACES = new Set([
   'override',
   'extension',
   'domain-manifest',
+  'state',
 ]);
 const SEARCH_NAMESPACES = new Set(['compute', 'graph']);
 
@@ -166,13 +172,87 @@ export async function dispatchRun(parsed, ctx = {}) {
     const m = await import('./domain-manifest.js');
     return m.domainManifestDispatch({ command: parsed.command, args: parsed.args, projectRoot });
   }
+  if (parsed.namespace === 'state') {
+    return dispatchState(parsed, { projectRoot, sessionId });
+  }
 
   return {
     ok: false,
-    error: 'Unknown ijfw_run sub-command. Supported: compute:python, compute:js, index:<source>, detect:project_type, graph:traverse, override:<op>, extension:<op>, domain-manifest:<op>',
+    error: 'Unknown ijfw_run sub-command. Supported: compute:python, compute:js, index:<source>, detect:project_type, graph:traverse, override:<op>, extension:<op>, domain-manifest:<op>, state:<verb>',
   };
 }
 
+// --- state:<verb> dispatch -------------------------------------------------
+//
+// T12: external tooling reaches the state-SDK via the CLI colon-namespace.
+// `state:<verb> [json-payload]` parses the payload as JSON, then calls
+// orchestrator/state-sdk.js `query(verb, payload, ctx)`. The verb name is the
+// part after `state:` (e.g. `workflow.get`, `wave.advance`). The payload
+// defaults to `{}` when no args are supplied — read-only verbs like
+// `workflow.get` work with an empty payload.
+//
+// Errors come back as `{ ok: false, error, code }` so callers (cli-run.js,
+// shell hooks) can JSON.parse the stdout uniformly. Unknown verbs throw
+// inside `query()` and the throw is caught + surfaced with `code: 'UNKNOWN_VERB'`.
+async function dispatchState(parsed, { projectRoot, sessionId }) {
+  const verb = parsed.command;
+  if (!verb) {
+    return { ok: false, error: 'state:<verb> requires a verb after the colon.', code: 'NO_VERB' };
+  }
+
+  // Parse the JSON payload. Empty args -> `{}`. The colon-syntax parser
+  // already strips a single matching outer quote pair so callers can use
+  // either `state:foo '{"k":"v"}'` (shell-style) or `state:foo {"k":"v"}`
+  // (already-stripped) and reach the same handler.
+  const raw = String(parsed.args || '').trim();
+  let payload = {};
+  if (raw.length > 0) {
+    try {
+      payload = JSON.parse(raw);
+    } catch (err) {
+      return {
+        ok: false,
+        error: `state:${verb} payload is not valid JSON: ${err && err.message ? err.message : String(err)}`,
+        code: 'INVALID_JSON',
+      };
+    }
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+      return {
+        ok: false,
+        error: `state:${verb} payload must be a JSON object, got ${Array.isArray(payload) ? 'array' : typeof payload}.`,
+        code: 'INVALID_JSON',
+      };
+    }
+  }
+
+  // Lazy-import the SDK so this module stays cheap for the non-state
+  // dispatch paths (e.g. compute:python) and so a state-sdk init error
+  // surfaces as a structured ok:false instead of a top-level module crash.
+  let query;
+  try {
+    ({ query } = await import('../orchestrator/state-sdk.js'));
+  } catch (err) {
+    return {
+      ok: false,
+      error: `state:${verb} could not load state-sdk: ${err && err.message ? err.message : String(err)}`,
+      code: 'SDK_LOAD',
+    };
+  }
+
+  try {
+    const result = await query(verb, payload, { projectRoot, sessionId });
+    return result;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    const isUnknownVerb = /unknown verb/i.test(msg);
+    return {
+      ok: false,
+      error: `state:${verb} did not complete: ${msg}`,
+      code: isUnknownVerb ? 'UNKNOWN_VERB' : (err && err.code) || 'ERROR',
+    };
+  }
+}
+
 async function dispatchCompute(parsed, { projectRoot, sessionId /*, provenance unused for compute runs */ }) {
   const cmd = parsed.command;
   if (cmd !== 'js' && cmd !== 'python') {

package/src/dispatch/extension.js

@@ -17,6 +17,26 @@
  *                             current project's platform dirs. Fired by the
  *                             session-start hook so org/user-scoped extensions
  *                             become available in every project session.
+ *
+ * TODO(v1.5.0-major S01 — IJFW_PARENT_PROJECT_ROOT env passthrough):
+ *   The Agent({ isolation: 'worktree' }) spawn path lives in the Claude Code
+ *   harness (Task tool / SDK), NOT in this MCP server's dispatch flow. When the
+ *   harness eventually exposes a hook for env passthrough on worktree dispatch,
+ *   the dispatcher MUST set:
+ *
+ *     IJFW_PARENT_PROJECT_ROOT=<absolute path to the orchestrator's projectRoot>
+ *
+ *   so that the subagent's `ijfw checkpoint` writes land in the PARENT project's
+ *   .ijfw/wave-<id>/ instead of the disposable worktree's .ijfw/. Until that
+ *   harness hook exists, the contract is documented in
+ *   `mcp-server/src/orchestrator/checkpoint-contract.md` ("Worktree isolation
+ *   drain protocol") and the orchestrator MUST run `ijfw worktree-drain
+ *   <waveId> <worktreePath>` BEFORE `git worktree remove` as a belt-and-
+ *   suspenders fallback (see dispatch/wave-cli.js worktree-drain handler).
+ *
+ *   Subagent-side: any agent template that may run in worktree isolation should
+ *   read `process.env.IJFW_PARENT_PROJECT_ROOT` (already honored transparently
+ *   by orchestrator/subagent-telemetry.js record/read/list).
  */
 
 import {
@@ -613,11 +633,14 @@ async function cmdDeactivate() {
 let _v143Handlers = null;
 async function loadV143Handlers() {
   if (_v143Handlers !== null) return _v143Handlers;
-  const [registry, signer, quota, active] = await Promise.all([
+  const [registry, signer, quota, active, wave, checkpoint, worktree] = await Promise.all([
     import('./registry-cli.js'),
     import('./signer-cli.js'),
     import('./quota-cli.js'),
     import('./active-cli.js'),
+    import('./wave-cli.js'),       // v1.4.4 N9 — wave-status / wave-list
+    import('./checkpoint-cli.js'), // v1.5.0 W11-A1 — ijfw checkpoint (S1)
+    import('./worktree-cli.js'),   // v1.5.0 W11-A2 — ijfw worktree provision (S2)
   ]);
   _v143Handlers = Object.assign(
     Object.create(null),
@@ -625,6 +648,9 @@ async function loadV143Handlers() {
     signer.handlers || {},
     quota.handlers || {},
     active.handlers || {},
+    wave.handlers || {},
+    checkpoint.handlers || {},
+    worktree.handlers || {},
   );
   return _v143Handlers;
 }

package/src/dispatch/registry-cli.js

@@ -28,6 +28,8 @@ import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir as osHomedir } from 'node:os';
 import { createPublicKey } from 'node:crypto';
+// v1.5.0 audit-LOW-update-#13: shared tmp-suffix helper.
+import { tmpSuffix } from '../lib/tmp-suffix.js';
 
 import {
   loadRegistrySources,
@@ -70,7 +72,8 @@ async function readRegistriesFile(ctx) {
 async function writeRegistriesFile(ctx, doc) {
   const path = registriesConfigPath(ctx);
   await mkdir(join(homedir(ctx), '.ijfw'), { recursive: true });
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  // v1.5.0 audit-LOW-update-#13: consolidate tmp-suffix shape via helper.
+  const tmp = `${path}.tmp.${tmpSuffix()}`;
   await writeFile(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
   const { rename } = await import('node:fs/promises');
   await rename(tmp, path);