@yuzc-001/grasp 0.6.6

package/src/cli/auto-configure.js

@@ -0,0 +1,116 @@
+/**
+ * Auto-configure Grasp into detected AI clients.
+ * Supported: Claude Code, Codex CLI, Cursor
+ *
+ * OpenClaw is an agent gateway (not an MCP client) — not applicable here.
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { homedir, platform } from 'os';
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+
+const GRASP_MCP_JSON = { command: 'npx', args: ['-y', '@yuzc-001/grasp'] };
+const env = process.env;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function hasCommand(cmd) {
+  try {
+    execSync(platform() === 'win32' ? `where ${cmd}` : `which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+async function writeMcpJson(filePath) {
+  await mkdir(join(filePath, '..'), { recursive: true });
+  let config = {};
+  try { config = JSON.parse(await readFile(filePath, 'utf8')); } catch { /* new file */ }
+  config.mcpServers ??= {};
+  if (JSON.stringify(config.mcpServers.grasp) === JSON.stringify(GRASP_MCP_JSON)) {
+    return 'already-configured';
+  }
+  config.mcpServers.grasp = GRASP_MCP_JSON;
+  await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  return 'written';
+}
+
+async function writeCodexToml(filePath) {
+  await mkdir(join(filePath, '..'), { recursive: true });
+  let content = '';
+  try { content = await readFile(filePath, 'utf8'); } catch { /* new file */ }
+  if (content.includes('[mcp_servers.grasp]')) return 'already-configured';
+  const entry = '\n[mcp_servers.grasp]\ntype    = "stdio"\ncommand = "npx"\nargs    = ["-y", "@yuzc-001/grasp"]\n';
+  await writeFile(filePath, content + entry, 'utf8');
+  return 'written';
+}
+
+// ─── Client definitions ──────────────────────────────────────────────────────
+
+const CLIENTS = [
+
+  // Claude Code CLI
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    installed: () => hasCommand('claude'),
+    configure: async () => {
+      try {
+        const out = execSync('claude mcp list', {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (out.includes('grasp:')) return 'already-configured';
+      } catch { /* no entries yet */ }
+      try {
+    execSync('claude mcp add grasp -- npx -y @yuzc-001/grasp', { stdio: 'ignore' });
+        return 'written';
+      } catch { return 'failed'; }
+    },
+  },
+
+  // Codex CLI
+  {
+    id: 'codex',
+    label: 'Codex CLI',
+    installed: () => hasCommand('codex'),
+    configure: async () => writeCodexToml(join(homedir(), '.codex', 'config.toml')),
+  },
+
+  // Cursor
+  {
+    id: 'cursor',
+    label: 'Cursor',
+    installed: () => {
+      if (hasCommand('cursor')) return true;
+      if (platform() === 'win32')
+        return existsSync(join(env.LOCALAPPDATA ?? '', 'Programs', 'cursor', 'Cursor.exe'));
+      if (platform() === 'darwin') return existsSync('/Applications/Cursor.app');
+      return false;
+    },
+    configure: async () => writeMcpJson(join(homedir(), '.cursor', 'mcp.json')),
+  },
+
+];
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function detectClients() {
+  return CLIENTS.filter(c => c.installed()).map(c => c.id);
+}
+
+export async function autoConfigureAll(clientIds) {
+  const results = [];
+  for (const id of clientIds) {
+    const client = CLIENTS.find(c => c.id === id);
+    if (!client) continue;
+    try {
+      const result = await client.configure();
+      results.push({ id, label: client.label, result });
+    } catch (err) {
+      results.push({ id, label: client.label, result: 'failed', error: err.message });
+    }
+  }
+  return results;
+}

package/src/cli/cmd-connect.js

@@ -0,0 +1,148 @@
+import { spawn } from 'child_process';
+import { join } from 'path';
+import { homedir, platform } from 'os';
+import { readConfig, writeConfig } from './config.js';
+import { detectChromePath } from './detect-chrome.js';
+import { detectClients, autoConfigureAll } from './auto-configure.js';
+import { readBrowserInstance } from '../runtime/browser-instance.js';
+
+const STEP_OK   = '[ok]';
+const STEP_WAIT = '[..]';
+const STEP_FAIL = '[!!]';
+
+async function launchChrome(chromePath, cdpUrl) {
+  const port = new URL(cdpUrl).port || '9222';
+  const userDataDir = join(homedir(), 'chrome-grasp');
+
+  spawn(chromePath, [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${userDataDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--start-maximized',
+  ], { detached: true, stdio: 'ignore' }).unref();
+
+  // Wait up to 8s
+  for (let i = 0; i < 16; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    const info = await readBrowserInstance(cdpUrl, { timeout: 800 });
+    if (info) return info;
+  }
+  return null;
+}
+
+export async function runConnect() {
+  const config = await readConfig();
+  const cdpUrl = process.env.CHROME_CDP_URL || config.cdpUrl;
+  const userDataDir = join(homedir(), 'chrome-grasp');
+
+  console.log('');
+  console.log('  Grasp Runtime Setup');
+  console.log('  ' + '─'.repeat(44));
+  console.log('  Bring a Chrome CDP session into the runtime.');
+  console.log('  One URL, one best path.');
+  console.log('');
+
+  // Step 1: detect Chrome
+  const chromePath = detectChromePath();
+  if (chromePath) {
+    console.log(`  ${STEP_OK} Chrome found`);
+    console.log(`       ${chromePath}`);
+  } else {
+    console.log(`  ${STEP_FAIL} Chrome not found`);
+    console.log('');
+    console.log('  Install Google Chrome and try again:');
+    console.log('  https://www.google.com/chrome/');
+    console.log('');
+    process.exit(1);
+  }
+
+  // Step 2: check or launch Chrome with CDP
+  console.log('');
+  console.log(`  ${STEP_WAIT} Ensuring browser runtime at ${cdpUrl} ...`);
+  let chromeInfo = await readBrowserInstance(cdpUrl);
+  let launchedDedicatedProfile = false;
+
+  if (!chromeInfo) {
+    console.log(`  ${STEP_WAIT} Chrome not running, launching dedicated profile...`);
+    chromeInfo = await launchChrome(chromePath, cdpUrl);
+    launchedDedicatedProfile = chromeInfo !== null;
+  }
+
+  if (!chromeInfo) {
+    console.log(`  ${STEP_FAIL} Failed to bring the browser runtime online`);
+    console.log('');
+    console.log('  Try running manually:');
+    if (platform() === 'win32') {
+      console.log('    start-chrome.bat');
+    } else {
+      console.log(`    "${chromePath}" --remote-debugging-port=9222 --user-data-dir=$HOME/chrome-grasp`);
+    }
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log(`  ${STEP_OK} Browser runtime ready  (${chromeInfo.browser ?? 'unknown'})`);
+  console.log(`       Profile: ${userDataDir}`);
+  console.log(`       Instance: ${chromeInfo.display === 'headless' ? 'headless browser' : chromeInfo.display === 'windowed' ? 'windowed browser' : 'unknown browser mode'}`);
+  if (launchedDedicatedProfile) {
+    console.log('       Scope: dedicated chrome-grasp profile, not an arbitrary existing browser session');
+  }
+  if (chromeInfo.warning) {
+    console.log(`       Warning: ${chromeInfo.warning}`);
+  }
+
+  // Step 3: save cdpUrl to config
+  await writeConfig({ cdpUrl });
+
+  // Step 4: get active tab
+  try {
+    const tabsRes = await fetch(`${cdpUrl}/json`, { signal: AbortSignal.timeout(1500) });
+    const tabs = await tabsRes.json();
+    const tab = tabs.find(t => t.type === 'page' && t.url && !t.url.startsWith('chrome://'));
+    if (tab) {
+      console.log(`  ${STEP_OK} Current page: ${tab.title?.slice(0, 50) || tab.url}`);
+    }
+  } catch { /* ignore */ }
+
+  // Step 5: auto-configure AI clients
+  console.log('');
+  console.log(`  ${STEP_WAIT} Connecting AI clients...`);
+  const clients = detectClients();
+
+  if (clients.length === 0) {
+    console.log(`  ${STEP_FAIL} No AI clients found`);
+    console.log('');
+    console.log('  Add Grasp manually to your AI client config:');
+      console.log('    { "mcpServers": { "grasp": { "command": "npx", "args": ["-y", "@yuzc-001/grasp"] } } }');
+  } else {
+    const results = await autoConfigureAll(clients);
+    for (const { label, result } of results) {
+      if (result === 'written') {
+        console.log(`  ${STEP_OK} ${label}  — config written`);
+      } else if (result === 'already-configured') {
+        console.log(`  ${STEP_OK} ${label}  — already configured`);
+      } else {
+        console.log(`  ${STEP_FAIL} ${label}  — failed, add manually`);
+      }
+    }
+
+    const needsRestart = results
+      .filter(r => r.result === 'written')
+      .map(r => r.label);
+
+    if (needsRestart.length > 0) {
+      console.log('');
+      console.log(`  Restart ${needsRestart.join(', ')} to apply changes.`);
+    }
+  }
+
+  console.log('');
+  console.log('  ' + '─'.repeat(44));
+  console.log('  Runtime ready. First win:');
+  console.log('    1. Tell your AI: "call get_status"');
+  console.log('    2. Then: "use entry(url, intent) on a real page"');
+  console.log('    3. Then: "inspect, then extract or continue"');
+  console.log('    4. Then: "explain_route or grasp explain"');
+  console.log('');
+}

package/src/cli/cmd-explain.js

@@ -0,0 +1,42 @@
+import { readLatestRouteDecision } from '../server/audit.js';
+
+export function formatRouteExplanation(route) {
+  if (!route) {
+    return [
+      '',
+      '  No route decision recorded yet.',
+      '  Run entry(url, intent) first, then ask Grasp to explain the route.',
+      '',
+    ];
+  }
+
+  const fallback = route.fallback_chain?.length
+    ? route.fallback_chain.join(' -> ')
+    : 'none';
+  const triggers = route.evidence?.triggers?.length
+    ? route.evidence.triggers.join(', ')
+    : 'none';
+
+  return [
+    '',
+    '  Grasp Route Explanation',
+    `  ${'─'.repeat(44)}`,
+    `  URL        ${route.url ?? 'unknown'}`,
+    `  Intent     ${route.intent ?? 'unknown'}`,
+    `  Status     ${route.status ?? 'unknown'}`,
+    `  Mode       ${route.selected_mode ?? 'unknown'}`,
+    `  Confidence ${route.confidence ?? 'unknown'}`,
+    `  Risk       ${route.risk_level ?? 'unknown'}`,
+    `  Human      ${route.requires_human ? 'yes' : 'no'}`,
+    `  Next       ${route.next_step ?? 'unknown'}`,
+    `  Fallback   ${fallback}`,
+    `  Failure    ${route.failure_type ?? 'none'}`,
+    `  Because    ${triggers}`,
+    '',
+  ];
+}
+
+export async function runExplain() {
+  const route = await readLatestRouteDecision();
+  formatRouteExplanation(route).forEach((line) => console.log(line));
+}

package/src/cli/cmd-logs.js

@@ -0,0 +1,55 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const LOG_PATH = join(homedir(), '.grasp', 'audit.log');
+
+async function readLines(n) {
+  try {
+    const content = await readFile(LOG_PATH, 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+    return lines.slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+export async function runLogs(args) {
+  let lines = 50;
+  let follow = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--lines' || args[i] === '-n') && args[i + 1]) {
+      lines = parseInt(args[++i], 10) || 50;
+    } else if (args[i] === '--follow' || args[i] === '-f') {
+      follow = true;
+    }
+  }
+
+  const entries = await readLines(lines);
+  if (entries.length === 0) {
+    console.log('No log entries yet.');
+    if (!follow) return;
+  } else {
+    entries.forEach(l => console.log(l));
+  }
+
+  if (!follow) return;
+
+  // Follow mode: poll every 500ms, print new lines
+  console.log('--- following (Ctrl+C to stop) ---');
+  let lastCount = entries.length;
+
+  setInterval(async () => {
+    try {
+      const content = await readFile(LOG_PATH, 'utf8');
+      const all = content.split('\n').filter(Boolean);
+      if (all.length > lastCount) {
+        all.slice(lastCount).forEach(l => console.log(l));
+        lastCount = all.length;
+      }
+    } catch {
+      // Log file removed or inaccessible — keep waiting
+    }
+  }, 500);
+}

package/src/cli/cmd-status.js

@@ -0,0 +1,119 @@
+import { readConfig } from './config.js';
+import { detectChromePath, startChromeHint } from './detect-chrome.js';
+import { readRuntimeTruth } from '../server/runtime-status.js';
+import { readLatestRouteDecision, readLogs } from '../server/audit.js';
+import { isSafeModeEnabled } from '../server/state.js';
+import { readBrowserInstance } from '../runtime/browser-instance.js';
+
+async function getActiveChromeTab(cdpUrl) {
+  try {
+    const res = await fetch(`${cdpUrl}/json`, { signal: AbortSignal.timeout(1500) });
+    const tabs = await res.json();
+    return tabs.find(t =>
+      t.type === 'page' &&
+      t.url &&
+      !t.url.startsWith('chrome://') &&
+      !t.url.startsWith('about:')
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatConnectionLabel(connected, runtimeTruth) {
+  if (connected) return 'ready';
+
+  // Backward compatibility for legacy runtime-status snapshots/tests.
+  if (runtimeTruth?.state === 'CDP_UNREACHABLE') return 'browser unreachable';
+  if (runtimeTruth?.state) return 'disconnected';
+
+  if (runtimeTruth?.cdp?.state === 'unreachable') return 'browser unreachable';
+  if (runtimeTruth?.server?.state && runtimeTruth.server.state !== 'idle') return 'disconnected';
+  return 'browser unreachable';
+}
+
+export function formatLatestRouteSummary(route) {
+  if (!route?.selected_mode) return null;
+  const nextStep = route.next_step ?? 'unknown';
+  const intent = route.intent ?? 'unknown';
+  return `${route.selected_mode} -> ${nextStep} (intent: ${intent})`;
+}
+
+export function formatInstanceLabel(instance) {
+  if (instance?.display === 'headless') return 'headless browser';
+  if (instance?.display === 'windowed') return 'windowed browser';
+  return 'unknown browser mode';
+}
+
+export async function runStatus() {
+  const config = await readConfig();
+  const cdpUrl = process.env.CHROME_CDP_URL || config.cdpUrl;
+  const runtimeTruth = await readRuntimeTruth();
+  const safeMode = isSafeModeEnabled();
+  const safeModeNote = safeMode === config.safeMode ? '' : ` (config: ${config.safeMode ? 'on' : 'off'})`;
+
+  const sep = '─'.repeat(44);
+  console.log('');
+  console.log('  Grasp Runtime Status');
+  console.log(`  ${sep}`);
+
+  const instance = await readBrowserInstance(cdpUrl);
+  const connected = instance !== null;
+
+  const statusLabel = formatConnectionLabel(connected, runtimeTruth);
+  console.log(`  Runtime    ${statusLabel}`);
+  console.log(`  Endpoint   ${cdpUrl}`);
+  if (!connected && runtimeTruth?.server?.lastError) {
+    console.log(`             Last error: ${runtimeTruth.server.lastError}`);
+  }
+  if (runtimeTruth?.updatedAt) {
+    const updatedAt = new Date(runtimeTruth.updatedAt).toLocaleString();
+    console.log(`             Last seen: ${updatedAt}`);
+  }
+  console.log(`  Browser    ${connected ? 'running  ' + (instance.browser ?? 'unknown') : 'not reachable'}`);
+  if (connected) {
+    console.log(`  Instance   ${formatInstanceLabel(instance)}`);
+    if (instance.warning) {
+      console.log(`             Warning: ${instance.warning}`);
+    }
+  }
+  console.log('  Profile    chrome-grasp');
+  console.log(`  Safe mode  ${safeMode ? 'on' : 'off'}${safeModeNote}`);
+  const latestRoute = await readLatestRouteDecision();
+  const latestRouteSummary = formatLatestRouteSummary(latestRoute);
+  if (latestRouteSummary) {
+    console.log(`  Last route ${latestRouteSummary}`);
+  }
+
+  if (connected) {
+      const tab = await getActiveChromeTab(cdpUrl);
+      if (tab) {
+        const title = tab.title?.slice(0, 50) || '(no title)';
+        const url = tab.url?.slice(0, 70) || '';
+        console.log(`  Current page ${title}`);
+        console.log(`             ${url}`);
+      }
+  } else {
+    const chromePath = detectChromePath();
+    console.log('');
+    if (chromePath) {
+      console.log('  Chrome found at:');
+      console.log(`    ${chromePath}`);
+      console.log('');
+      console.log('  Bring the runtime back:');
+      console.log(`    ${startChromeHint(cdpUrl)}`);
+    } else {
+      console.log('  Chrome not found. Install Google Chrome, then run:');
+      console.log(`    ${startChromeHint(cdpUrl)}`);
+    }
+  }
+
+  const logs = await readLogs(3);
+  if (logs.length > 0) {
+    console.log('');
+    console.log('  Recent activity');
+    logs.forEach((l) => console.log(`    ${l}`));
+  }
+
+  console.log('');
+}

package/src/cli/config.js

@@ -0,0 +1,27 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const CONFIG_DIR = join(homedir(), '.grasp');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+const DEFAULTS = {
+  cdpUrl: 'http://localhost:9222',
+  safeMode: true,
+};
+
+export async function readConfig() {
+  try {
+    const raw = await readFile(CONFIG_PATH, 'utf8');
+    return { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export async function writeConfig(updates) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  const current = await readConfig();
+  const merged = { ...current, ...updates };
+  await writeFile(CONFIG_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}

package/src/cli/detect-chrome.js

@@ -0,0 +1,58 @@
+import { existsSync } from 'fs';
+import { platform } from 'process';
+import { join } from 'path';
+
+const WIN_PATHS = [
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  join(process.env.LOCALAPPDATA ?? '', 'Google\\Chrome\\Application\\chrome.exe'),
+  join(process.env.LOCALAPPDATA ?? '', 'Google\\Chrome Beta\\Application\\chrome.exe'),
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+];
+
+const MAC_PATHS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+];
+
+const LINUX_PATHS = [
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+  '/snap/bin/chromium',
+];
+
+/**
+ * Returns the path to the first found Chrome/Chromium executable, or null.
+ */
+export function detectChromePath() {
+  const paths = platform === 'win32' ? WIN_PATHS
+    : platform === 'darwin' ? MAC_PATHS
+    : LINUX_PATHS;
+  return paths.find(p => p && existsSync(p)) ?? null;
+}
+
+/**
+ * Returns a platform-appropriate command to start Chrome with CDP enabled.
+ */
+export function startChromeHint(cdpUrl = 'http://localhost:9222') {
+  const port = new URL(cdpUrl).port || '9222';
+  const chromePath = detectChromePath();
+
+  if (platform === 'win32') {
+    return chromePath
+      ? `"${chromePath}" --remote-debugging-port=${port} --user-data-dir="%USERPROFILE%\\chrome-grasp"`
+      : `start-chrome.bat`;
+  }
+  if (platform === 'darwin') {
+    return chromePath
+      ? `"${chromePath}" --remote-debugging-port=${port} --user-data-dir=/tmp/chrome-grasp`
+      : `open -a "Google Chrome" --args --remote-debugging-port=${port}`;
+  }
+  return chromePath
+    ? `"${chromePath}" --remote-debugging-port=${port} --user-data-dir=/tmp/chrome-grasp`
+    : `google-chrome --remote-debugging-port=${port}`;
+}

package/src/grasp/handoff/events.js

@@ -0,0 +1,67 @@
+import { createHandoffState, mergeHandoffState } from './state.js';
+
+export function requestHandoff(current, reason, note = null, anchors = {}) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'handoff_required',
+    reason,
+    note,
+    requestedAt: Date.now(),
+    evidence: null,
+    expected_url_contains: anchors.expected_url_contains ?? null,
+    expected_page_role: anchors.expected_page_role ?? null,
+    expected_selector: anchors.expected_selector ?? null,
+    continuation_goal: anchors.continuation_goal ?? null,
+    expected_hint_label: anchors.expected_hint_label ?? null,
+  });
+}
+
+export function markHandoffInProgress(current, note = null) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'handoff_in_progress',
+    note,
+  });
+}
+
+export function markAwaitingReacquisition(current, note = null) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'awaiting_reacquisition',
+    note,
+  });
+}
+
+export function markResumedUnverified(current, evidence = null, note = null) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'resumed_unverified',
+    evidence,
+    note,
+  });
+}
+
+export function markResumeVerified(current, evidence = null, note = null) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'resumed_verified',
+    evidence,
+    note,
+    verifiedAt: Date.now(),
+  });
+}
+
+export function clearHandoff(current) {
+  return mergeHandoffState(current ?? createHandoffState(), {
+    state: 'idle',
+    reason: null,
+    note: null,
+    requestedAt: null,
+    verifiedAt: null,
+    evidence: null,
+    expected_url_contains: null,
+    expected_page_role: null,
+    expected_selector: null,
+    continuation_goal: null,
+    expected_hint_label: null,
+    taskId: null,
+    siteKey: null,
+    sessionKey: null,
+    lastUrl: null,
+  });
+}

package/src/grasp/handoff/persist.js

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import { createHandoffState, mergeHandoffState } from './state.js';
+
+export const HANDOFF_STATE_PATH =
+  process.env.GRASP_HANDOFF_STATE_PATH ??
+  join(homedir(), '.grasp', 'handoff-state.json');
+
+export function attachHandoffTaskMetadata(handoff = {}, source = {}) {
+  return {
+    ...handoff,
+    taskId: source.taskId ?? handoff.taskId ?? null,
+    siteKey: source.siteKey ?? handoff.siteKey ?? null,
+    sessionKey: source.sessionKey ?? handoff.sessionKey ?? null,
+    lastUrl: source.lastUrl ?? handoff.lastUrl ?? null,
+  };
+}
+
+async function ensureDir() {
+  await mkdir(dirname(HANDOFF_STATE_PATH), { recursive: true });
+}
+
+export async function writeHandoffState(snapshot) {
+  try {
+    await ensureDir();
+    const state = attachHandoffTaskMetadata(
+      mergeHandoffState(createHandoffState(), snapshot),
+      snapshot
+    );
+    await writeFile(HANDOFF_STATE_PATH, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  } catch {
+    // best effort
+  }
+}
+
+export async function readHandoffState() {
+  try {
+    const raw = await readFile(HANDOFF_STATE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return attachHandoffTaskMetadata(
+      mergeHandoffState(createHandoffState(), parsed),
+      parsed
+    );
+  } catch {
+    return createHandoffState();
+  }
+}