@ijfw/memory-server 1.4.4 → 1.5.1

package/src/deploy-alerts.js

@@ -0,0 +1,150 @@
+/**
+ * deploy-alerts.js — v1.5.0 audit-MED-update-M8 (F-REL-2).
+ *
+ * When `extension-installer.installExtension` exits with `deploy_partial: true`,
+ * the failure detail used to be returned in the install reply only — the next
+ * prelude had no way to surface "you have a half-deployed extension somewhere".
+ *
+ * This module persists each partial deploy to a jsonl tail at
+ * `~/.ijfw/state/deploy-failures.jsonl` so the memory prelude (handlePrelude in
+ * `server.js`) can read the last N entries and emit a "Deploy alerts" line.
+ *
+ * File contract:
+ *   - JSONL, one record per line.
+ *   - Each record:
+ *       {
+ *         ts: ISO8601,
+ *         extension: <manifest.name>,
+ *         scope: 'project' | 'org' | 'user',
+ *         failures: Array<{platform, skillName, error}>,
+ *       }
+ *   - Soft cap: 200 lines. Older lines drop off via a one-shot trim on write.
+ *   - Append-only and atomic in the common case (single writeFile call); the
+ *     trim path rewrites the whole tail under the same atomic shape.
+ *   - Failure to write is non-fatal — alert path is best-effort observability.
+ *
+ * The reader is bounded at N=10 by default — short-tail "what's wrong right
+ * now" surfacing, not an audit log.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const ALERT_FILE_NAME = 'deploy-failures.jsonl';
+const MAX_LINES_ON_DISK = 200;
+const DEFAULT_READ_TAIL = 10;
+
+function statePath() {
+  return join(homedir(), '.ijfw', 'state');
+}
+
+export function deployFailuresPath() {
+  return join(statePath(), ALERT_FILE_NAME);
+}
+
+/**
+ * Record a partial-deploy event.
+ *
+ * @param {object} record
+ * @param {string} record.extension
+ * @param {'project'|'org'|'user'} record.scope
+ * @param {Array<{platform:string, skillName?:string, error:string}>} record.failures
+ * @returns {Promise<{ok:boolean, path?:string, error?:string}>}
+ */
+export async function recordDeployFailure(record) {
+  if (!record || typeof record !== 'object') {
+    return { ok: false, error: 'record must be an object' };
+  }
+  if (typeof record.extension !== 'string' || record.extension.length === 0) {
+    return { ok: false, error: 'extension is required' };
+  }
+  if (!Array.isArray(record.failures)) {
+    return { ok: false, error: 'failures must be an array' };
+  }
+
+  const entry = {
+    ts: new Date().toISOString(),
+    extension: record.extension,
+    scope: record.scope || 'project',
+    failures: record.failures.map((f) => ({
+      // v1.5.0 wire-W2.design-misc — was `typeof f && f.platform`, which is
+      // effectively `f.platform` because `typeof f` is always a truthy string
+      // (even for null/undefined). That meant a null entry in the failures
+      // array threw a TypeError instead of falling back to 'unknown'. The
+      // adjacent skillName + error fields already use the correct guard.
+      platform: f && f.platform ? String(f.platform) : 'unknown',
+      skillName: f && f.skillName ? String(f.skillName) : null,
+      error: f && f.error ? String(f.error).slice(0, 500) : 'unknown',
+    })),
+  };
+
+  const path = deployFailuresPath();
+  try {
+    await mkdir(statePath(), { recursive: true });
+    // Trim-on-overflow: if existing file already > cap, rewrite the tail.
+    let existing = '';
+    try {
+      existing = await readFile(path, 'utf8');
+    } catch {
+      existing = '';
+    }
+    const lines = existing ? existing.split('\n').filter((l) => l.trim()) : [];
+    lines.push(JSON.stringify(entry));
+    const trimmed = lines.slice(-MAX_LINES_ON_DISK);
+    await writeFile(path, trimmed.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Read the last N deploy-failure records (default 10). Returns oldest-first.
+ *
+ * @param {{limit?:number}} [opts]
+ * @returns {Promise<Array>}
+ */
+export async function readDeployFailures(opts = {}) {
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : DEFAULT_READ_TAIL;
+  let raw;
+  try {
+    raw = await readFile(deployFailuresPath(), 'utf8');
+  } catch {
+    return [];
+  }
+  const lines = raw.split('\n').filter((l) => l.trim());
+  const tail = lines.slice(-limit);
+  const out = [];
+  for (const line of tail) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    } catch {
+      // skip malformed line — don't fail the read
+    }
+  }
+  return out;
+}
+
+/**
+ * Render the last N entries as terse prelude lines. Empty array → empty string.
+ *
+ * @param {{limit?:number}} [opts]
+ * @returns {Promise<string>}
+ */
+export async function renderDeployAlertsForPrelude(opts = {}) {
+  const entries = await readDeployFailures(opts);
+  if (entries.length === 0) return '';
+  const lines = ['## Deploy alerts'];
+  for (const e of entries) {
+    const fcount = Array.isArray(e.failures) ? e.failures.length : 0;
+    const platforms = Array.isArray(e.failures)
+      ? Array.from(new Set(e.failures.map((f) => f.platform).filter(Boolean))).join(',')
+      : '';
+    const head = `- ${e.ts} — ${e.extension} (scope=${e.scope || 'project'}): ${fcount} failure${fcount === 1 ? '' : 's'}${platforms ? ` [${platforms}]` : ''}`;
+    lines.push(head);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

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)',
+});