@venturewild/workspace 0.1.0 → 0.1.1

package/server/bin/wild-workspace.mjs

@@ -1,95 +1,402 @@
-#!/usr/bin/env node
-// `wild-workspace` CLI entry — the bin field in package.json.
-// Forwards to server/src/index.mjs.
-
-import path from 'node:path';
-import url from 'node:url';
-import { createServer } from '../src/index.mjs';
-import { APP_VERSION } from '../src/config.mjs';
-
-const __filename = url.fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function printUsage() {
-  console.log(`wild-workspace v${APP_VERSION}
-
-Usage:
-  wild-workspace                  start the workspace server in the current directory
-  wild-workspace --port 5173      override port (default 5173)
-  wild-workspace --no-open        don't auto-open browser
-  wild-workspace --host 0.0.0.0   bind to all interfaces (for share-by-URL hosting)
-  wild-workspace install          register the bmo-sync daemon as a background service [v1.x]
-  wild-workspace share            (interactive helper) issue a viewer URL  [v1.x — use UI for now]
-  wild-workspace --help           this message
-  wild-workspace --version        print version
-
-Environment:
-  WILD_WORKSPACE_PORT, WILD_WORKSPACE_HOST,
-  WILD_WORKSPACE_DIR, WILD_WORKSPACE_DATA_DIR,
-  WILD_WORKSPACE_PARTNER_TOKEN, WILD_WORKSPACE_SHARE_SECRET,
-  WILD_WORKSPACE_NO_OPEN=1
-`);
-}
-
-function parseArgs(argv) {
-  const opts = {};
-  const positional = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--help' || arg === '-h') opts.help = true;
-    else if (arg === '--version' || arg === '-v') opts.version = true;
-    else if (arg === '--no-open') opts.openBrowser = false;
-    else if (arg === '--port') { opts.port = Number(argv[++i]); }
-    else if (arg === '--host') { opts.host = argv[++i]; }
-    else if (arg === '--workspace') { opts.workspaceDir = argv[++i]; }
-    else if (arg.startsWith('--')) {
-      // ignore unknown flags
-    } else {
-      positional.push(arg);
-    }
-  }
-  opts.positional = positional;
-  return opts;
-}
-
-async function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  if (opts.help) return printUsage();
-  if (opts.version) { console.log(APP_VERSION); return; }
-
-  if (opts.positional[0] === 'install') {
-    console.log('`wild-workspace install` is a v1.x feature (bmo-sync daemon).');
-    console.log('For now: run `wild-workspace` directly; sync is via OneDrive/bmo-sync separately.');
-    return;
-  }
-  if (opts.positional[0] === 'share') {
-    console.log('Use the in-app Share button to issue viewer URLs. CLI share command is v1.x.');
-    return;
-  }
-
-  const server = await createServer(opts);
-  const { config } = server;
-  console.log(`\n  wild-workspace v${APP_VERSION}`);
-  console.log(`  workspace : ${config.workspaceDir}`);
-  console.log(`  url       : http://${config.host}:${config.port}`);
-  console.log(`  agent     : ${server.getActiveAgent()?.label || '(none detected — install Claude Code: npm i -g @anthropic-ai/claude-code)'}\n`);
-
-  if (config.openBrowser) {
-    try {
-      const open = (await import('open')).default;
-      open(`http://${config.host}:${config.port}`);
-    } catch {}
-  }
-
-  process.on('SIGINT', async () => {
-    console.log('\nshutting down…');
-    await server.stop();
-    process.exit(0);
-  });
-  process.on('SIGTERM', async () => { await server.stop(); process.exit(0); });
-}
-
-main().catch((err) => {
-  console.error('wild-workspace failed:', err);
-  process.exit(1);
-});
+#!/usr/bin/env node
+// `wild-workspace` CLI entry — the bin field in package.json.
+// Starts the workspace server; also exposes a `daemon` subcommand for
+// inspecting / controlling the bmo-sync sync daemon.
+
+import path from 'node:path';
+import url from 'node:url';
+import { createServer } from '../src/index.mjs';
+import { APP_VERSION, buildConfig } from '../src/config.mjs';
+import { DaemonSupervisor } from '../src/daemon-supervisor.mjs';
+import { SyncControl } from '../src/sync.mjs';
+import {
+  decodeLoginPayload,
+  saveAccount,
+  loadAccount,
+  clearAccount,
+} from '../src/account.mjs';
+
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function printUsage() {
+  console.log(`wild-workspace v${APP_VERSION}
+
+Usage:
+  wild-workspace                  start the workspace server in the current directory
+  wild-workspace --port 5173      override port (default 5173)
+  wild-workspace --no-open        don't auto-open browser
+  wild-workspace --host 0.0.0.0   bind to all interfaces (for share-by-URL hosting)
+  wild-workspace daemon status                  is the bmo-sync daemon running?
+  wild-workspace daemon start                   start the sync daemon now
+  wild-workspace daemon stop                    stop the sync daemon
+  wild-workspace daemon conflicts list          list open conflicts
+  wild-workspace daemon conflicts show <wid> <path>     view one conflict
+  wild-workspace daemon conflicts resolve <wid> <path> <keep_mine|take_theirs>
+  wild-workspace login <payload>  bind this install to a slug
+                                  (paste the blob from workspace.venturewild.llc)
+  wild-workspace logout           clear the bound account (slug + token)
+  wild-workspace whoami           show the currently-bound account
+  wild-workspace rotate-token     mint a new account token; invalidates the old one
+  wild-workspace install          (info) how the sync daemon is managed
+  wild-workspace --help           this message
+  wild-workspace --version        print version
+
+The bmo-sync sync daemon starts automatically in the background when you run
+\`wild-workspace\`, and keeps running after you close the browser.
+
+Environment:
+  WILD_WORKSPACE_PORT, WILD_WORKSPACE_HOST,
+  WILD_WORKSPACE_DIR, WILD_WORKSPACE_DATA_DIR,
+  WILD_WORKSPACE_PARTNER_TOKEN, WILD_WORKSPACE_SHARE_SECRET,
+  WILD_WORKSPACE_NO_OPEN=1, WILD_WORKSPACE_DAEMON_AUTOSTART=0
+`);
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
+    else if (arg === '--no-open') opts.openBrowser = false;
+    else if (arg === '--port') { opts.port = Number(argv[++i]); }
+    else if (arg === '--host') { opts.host = argv[++i]; }
+    else if (arg === '--workspace') { opts.workspaceDir = argv[++i]; }
+    else if (arg.startsWith('--')) {
+      // ignore unknown flags
+    } else {
+      positional.push(arg);
+    }
+  }
+  opts.positional = positional;
+  return opts;
+}
+
+// `wild-workspace daemon [status|start|stop|conflicts ...]`
+async function runDaemonCommand(action = 'status', rest = []) {
+  const config = buildConfig({});
+  const sup = new DaemonSupervisor({
+    httpBase: config.daemonHttpUrl,
+    // b-ii: so `wild-workspace daemon start` also opens the proxy link.
+    accountToken: config.accountToken,
+    serverUrl: config.bmoSyncServerUrl,
+  });
+
+  if (action === 'conflicts') {
+    return runConflictsCommand(config, rest);
+  }
+  if (action === 'status') {
+    const s = await sup.status();
+    console.log(`bmo-sync daemon: ${s.running ? 'running' : 'stopped'}`);
+    console.log(`  api : ${s.httpBase}`);
+    if (s.pid) console.log(`  pid : ${s.pid}`);
+    console.log(`  log : ${s.logFile}`);
+    return;
+  }
+  if (action === 'start') {
+    const r = await sup.ensureRunning();
+    if (r.alreadyRunning) {
+      console.log('bmo-sync daemon: already running');
+    } else if (r.started) {
+      const healthy = await sup.waitForHealthy();
+      console.log(
+        healthy
+          ? `bmo-sync daemon: started (pid ${r.pid})`
+          : `bmo-sync daemon: launched (pid ${r.pid}) — not yet answering, check the log`,
+      );
+    } else if (r.error === 'daemon-binary-not-found') {
+      console.log('bmo-sync daemon: cannot start — the daemon binary is not installed.');
+      console.log('  build it from the bmo-sync workspace and place it under vendor/,');
+      console.log('  or install the @venturewild/workspace-daemon-<platform> package.');
+    } else {
+      console.log(`bmo-sync daemon: could not start — ${r.error}`);
+    }
+    return;
+  }
+  if (action === 'stop') {
+    const r = await sup.stop();
+    console.log(
+      r.stopped
+        ? `bmo-sync daemon: stopped (pid ${r.pid})`
+        : `bmo-sync daemon: not stopped — ${r.reason}`,
+    );
+    return;
+  }
+  console.log(`unknown daemon action: ${action}  (use status | start | stop | conflicts)`);
+}
+
+// `wild-workspace daemon conflicts [list|show <wid> <path>|resolve <wid> <path> <action>]`
+async function runConflictsCommand(config, args) {
+  const sync = new SyncControl({
+    daemonHttpUrl: config.daemonHttpUrl,
+    bmoSyncServerUrl: config.bmoSyncServerUrl,
+  });
+  const sub = (args[0] || 'list').toLowerCase();
+  if (sub === 'list' || !sub) {
+    const conflicts = await sync.listConflicts();
+    if (!conflicts.length) {
+      console.log('no open conflicts');
+      return;
+    }
+    console.log(`open conflicts: ${conflicts.length}`);
+    for (const c of conflicts) {
+      const detected = new Date((c.detectedAt || 0) * 1000).toISOString();
+      console.log(`  [${c.workspaceId}] ${c.path}`);
+      console.log(`    resolution     : ${c.resolution}`);
+      console.log(`    detected_at    : ${detected}`);
+      if (c.peerBackOfficePath) {
+        console.log(`    peer_bytes_at  : ${c.peerBackOfficePath}`);
+      }
+      if (c.mineSha256) console.log(`    mine_sha256    : ${c.mineSha256}`);
+      if (c.theirsSha256) console.log(`    theirs_sha256  : ${c.theirsSha256}`);
+    }
+    return;
+  }
+  if (sub === 'show') {
+    const wid = args[1];
+    const path = args[2];
+    if (!wid || !path) {
+      console.log('usage: wild-workspace daemon conflicts show <workspace_id> <path>');
+      return;
+    }
+    const view = await sync.viewConflict(wid, path);
+    if (!view) {
+      console.log(`no open conflict for ${wid}:${path}`);
+      return;
+    }
+    console.log(JSON.stringify(view, null, 2));
+    return;
+  }
+  if (sub === 'resolve') {
+    const wid = args[1];
+    const path = args[2];
+    const action = args[3];
+    if (!wid || !path || !action) {
+      console.log(
+        'usage: wild-workspace daemon conflicts resolve <workspace_id> <path> <keep_mine|take_theirs>',
+      );
+      return;
+    }
+    try {
+      await sync.resolveConflict(wid, path, action);
+      console.log(`resolved: ${wid}:${path} (${action})`);
+    } catch (e) {
+      console.error(`resolve failed: ${e.message || e}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  console.log(
+    `unknown conflicts subcommand: ${sub}  (use list | show <wid> <path> | resolve <wid> <path> <action>)`,
+  );
+}
+
+// `wild-workspace login <base64url-payload>` — bind this install to a slug.
+// The payload comes from workspace.venturewild.llc on signup. It's an opaque
+// blob the user copies once; we decode + persist + print a friendly summary.
+async function runLoginCommand(args) {
+  if (!args.length) {
+    console.error('usage: wild-workspace login <payload>');
+    console.error('');
+    console.error('The payload is the blob you copied from workspace.venturewild.llc');
+    console.error('after claiming your slug. Run that signup, then come back here.');
+    process.exitCode = 1;
+    return;
+  }
+  // Trim the obvious "wild-workspace login " prefix in case the user pasted
+  // the whole command line, and surrounding quotes if a shell preserved them.
+  let payload = args.join(' ').trim();
+  payload = payload.replace(/^wild-workspace\s+login\s+/i, '').trim();
+  payload = payload.replace(/^['"]|['"]$/g, '');
+  let parsed;
+  try {
+    parsed = decodeLoginPayload(payload);
+  } catch (e) {
+    console.error(`Couldn't decode the login payload: ${e.message || e}`);
+    process.exitCode = 1;
+    return;
+  }
+  const config = buildConfig({});
+  let saved;
+  try {
+    saved = saveAccount(config.dataDir, parsed);
+  } catch (e) {
+    console.error(`Couldn't save account to ${config.dataDir}: ${e.message || e}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`✓ logged in as ${saved.email}`);
+  console.log(`  slug      : ${saved.slug}`);
+  console.log(`  url       : https://${saved.slug}.venturewild.llc  (once the tunnel is configured)`);
+  console.log(`  saved to  : ${config.dataDir}/account.json`);
+  console.log('');
+  console.log('Run `wild-workspace` in any folder to start your workspace.');
+}
+
+async function runLogoutCommand() {
+  const config = buildConfig({});
+  const before = loadAccount(config.dataDir);
+  const removed = clearAccount(config.dataDir);
+  if (!removed && !before) {
+    console.log('not logged in.');
+    return;
+  }
+  console.log(`logged out — cleared ${before?.email || 'account'} from ${config.dataDir}.`);
+}
+
+async function runRotateTokenCommand() {
+  const config = buildConfig({});
+  const account = loadAccount(config.dataDir);
+  if (!account) {
+    console.log('not logged in. Nothing to rotate.');
+    console.log('Run `wild-workspace login <payload>` after claiming a slug.');
+    process.exitCode = 1;
+    return;
+  }
+  const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/account/rotate-token`;
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${account.accountToken}` },
+    });
+  } catch (e) {
+    console.error(`Couldn't reach ${config.bmoSyncServerUrl}: ${e.message || e}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (!resp.ok) {
+    let body;
+    try { body = await resp.text(); } catch { body = ''; }
+    console.error(`Rotate failed (HTTP ${resp.status}): ${body.slice(0, 200)}`);
+    process.exitCode = 1;
+    return;
+  }
+  let payload;
+  try {
+    payload = await resp.json();
+  } catch (e) {
+    console.error(`Server returned non-JSON: ${e.message || e}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!payload || !payload.account_token) {
+    console.error('Server response missing account_token. Aborting.');
+    process.exitCode = 1;
+    return;
+  }
+  const updated = {
+    ...account,
+    accountToken: payload.account_token,
+    loggedInAt: Date.now(),
+  };
+  try {
+    saveAccount(config.dataDir, updated);
+  } catch (e) {
+    console.error(`Got new token but failed to persist it: ${e.message || e}`);
+    console.error(`New token (save manually): ${payload.account_token}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('✓ token rotated.');
+  console.log(`  slug      : ${updated.slug}`);
+  console.log(`  saved to  : ${config.dataDir}/account.json`);
+  console.log('');
+  console.log('Your daemon will reconnect with the new token automatically');
+  console.log('on its next restart. Run `wild-workspace daemon stop && wild-workspace`');
+  console.log('to force an immediate reconnect.');
+}
+
+async function runWhoamiCommand() {
+  const config = buildConfig({});
+  const account = loadAccount(config.dataDir);
+  if (!account) {
+    console.log('not logged in.');
+    console.log('Run `wild-workspace login <payload>` after claiming a slug at workspace.venturewild.llc.');
+    return;
+  }
+  console.log(`logged in as ${account.email}`);
+  console.log(`  slug      : ${account.slug}`);
+  console.log(`  accountId : ${account.accountId}`);
+  if (account.displayName) console.log(`  name      : ${account.displayName}`);
+  console.log(`  loggedIn  : ${new Date(account.loggedInAt).toISOString()}`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return printUsage();
+  if (opts.version) { console.log(APP_VERSION); return; }
+
+  if (opts.positional[0] === 'daemon') {
+    return runDaemonCommand(opts.positional[1], opts.positional.slice(2));
+  }
+
+  if (opts.positional[0] === 'login') {
+    return runLoginCommand(opts.positional.slice(1));
+  }
+  if (opts.positional[0] === 'logout') {
+    return runLogoutCommand();
+  }
+  if (opts.positional[0] === 'whoami') {
+    return runWhoamiCommand();
+  }
+  if (opts.positional[0] === 'rotate-token') {
+    return runRotateTokenCommand();
+  }
+
+  if (opts.positional[0] === 'install') {
+    console.log('wild-workspace manages the bmo-sync sync daemon for you.');
+    console.log('');
+    console.log('It starts automatically in the background whenever you run');
+    console.log('`wild-workspace`, and keeps running after you close the browser —');
+    console.log('so there is no separate install step.');
+    console.log('');
+    console.log('  wild-workspace daemon status   check whether it is running');
+    console.log('  wild-workspace daemon stop     stop it');
+    return;
+  }
+  if (opts.positional[0] === 'share') {
+    console.log('Use the in-app Share button to issue viewer URLs. CLI share command is v1.x.');
+    return;
+  }
+
+  const server = await createServer(opts);
+  const { config } = server;
+  console.log(`\n  wild-workspace v${APP_VERSION}`);
+  console.log(`  workspace : ${config.workspaceDir}`);
+  console.log(`  url       : http://${config.host}:${config.port}`);
+  console.log(`  agent     : ${server.getActiveAgent()?.label || '(none detected — install Claude Code: npm i -g @anthropic-ai/claude-code)'}`);
+
+  // Report how the sync daemon's autostart went (best-effort — never fatal).
+  try {
+    const d = await server.daemonReady;
+    if (d.alreadyRunning) console.log('  sync      : bmo-sync daemon already running');
+    else if (d.started) console.log(`  sync      : bmo-sync daemon started (pid ${d.pid})`);
+    else if (d.skipped) console.log('  sync      : daemon autostart disabled');
+    else if (d.error === 'daemon-binary-not-found')
+      console.log('  sync      : daemon binary not installed — sync is off (see `wild-workspace daemon`)');
+    else if (d.error) console.log(`  sync      : daemon did not start — ${d.error}`);
+  } catch {}
+  console.log('');
+
+  if (config.openBrowser) {
+    try {
+      const open = (await import('open')).default;
+      open(`http://${config.host}:${config.port}`);
+    } catch {}
+  }
+
+  process.on('SIGINT', async () => {
+    console.log('\nshutting down…');
+    await server.stop();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => { await server.stop(); process.exit(0); });
+}
+
+main().catch((err) => {
+  console.error('wild-workspace failed:', err);
+  process.exit(1);
+});

package/server/src/account.mjs

@@ -0,0 +1,114 @@
+// Per-install bmo-sync account — the user's identity in the wild-* ecosystem.
+//
+// Distinct from `agent-identity.mjs` (which holds the agent's name/tone/color)
+// and from `secrets.mjs` (per-install partner/share tokens). An account binds
+// this installation to:
+//   - a `slug` (the `<slug>.venturewild.llc` namespace, claimed at signup)
+//   - an `email` (human identification — NOT used as a password)
+//   - an `accountId` (uuid)
+//   - an `accountToken` (long-random secret that proves ownership to
+//     `sync.venturewild.llc`; never sent to the browser)
+//
+// Persisted at `<dataDir>/account.json` (mode 0600). Absence means the user
+// has not run `wild-workspace login` yet; the server still works in localhost
+// mode but `<slug>.venturewild.llc` isn't configured.
+//
+// Login flow:
+//   1. User registers at `workspace.venturewild.llc` (landing).
+//   2. Landing displays a single opaque payload (base64url-encoded JSON).
+//   3. User runs `wild-workspace login <payload>`.
+//   4. We decode + persist here.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FILE = 'account.json';
+
+function accountPath(dataDir) {
+  return path.join(dataDir, FILE);
+}
+
+export function loadAccount(dataDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(accountPath(dataDir), 'utf8'));
+    return sanitize(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function sanitize(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const slug = typeof raw.slug === 'string' ? raw.slug.trim().toLowerCase() : '';
+  const email = typeof raw.email === 'string' ? raw.email.trim().toLowerCase() : '';
+  const accountId = typeof raw.accountId === 'string' ? raw.accountId.trim() : '';
+  const accountToken = typeof raw.accountToken === 'string' ? raw.accountToken.trim() : '';
+  if (!slug || !email || !accountId || !accountToken) return null;
+  return {
+    slug,
+    email,
+    accountId,
+    accountToken,
+    displayName: typeof raw.displayName === 'string' ? raw.displayName : null,
+    loggedInAt: Number(raw.loggedInAt) || Date.now(),
+  };
+}
+
+export function saveAccount(dataDir, account) {
+  const merged = sanitize({ loggedInAt: Date.now(), ...account });
+  if (!merged) throw new Error('account-invalid');
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(accountPath(dataDir), JSON.stringify(merged, null, 2), {
+    mode: 0o600,
+  });
+  return merged;
+}
+
+export function clearAccount(dataDir) {
+  try {
+    fs.unlinkSync(accountPath(dataDir));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Parse a single opaque token-blob the user pastes from the landing page.
+// The landing emits base64url(JSON({slug,email,accountId,token,displayName?})).
+// We accept either base64url or raw JSON for forward-compat / curl debugging.
+export function decodeLoginPayload(input) {
+  const raw = String(input || '').trim();
+  if (!raw) throw new Error('Empty login payload — paste the blob from your signup page.');
+  // 1. Try base64url decode.
+  const tryBase64 = () => {
+    let b = raw.replace(/-/g, '+').replace(/_/g, '/');
+    while (b.length % 4 !== 0) b += '=';
+    return Buffer.from(b, 'base64').toString('utf8');
+  };
+  // 2. Try raw JSON (if it starts with `{`).
+  let jsonText;
+  if (raw[0] === '{') {
+    jsonText = raw;
+  } else {
+    try {
+      jsonText = tryBase64();
+    } catch {
+      throw new Error('Login payload is not base64url-encoded JSON.');
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    throw new Error('Login payload decoded but is not valid JSON.');
+  }
+  // Accept both `token` (what the landing emits) and `accountToken`.
+  if (parsed.token && !parsed.accountToken) parsed.accountToken = parsed.token;
+  if (!parsed.slug || !parsed.email || !parsed.accountId || !parsed.accountToken) {
+    throw new Error(
+      'Login payload is missing one or more required fields ' +
+        '(slug, email, accountId, token). Re-copy from the signup page?',
+    );
+  }
+  return parsed;
+}

package/server/src/agent-identity.mjs

@@ -0,0 +1,65 @@
+// Agent identity — the user-given name, voice/tone, and accent color the agent
+// adopts during onboarding (see docs/onboarding-flow-plan in memory). Persisted
+// to <dataDir>/agent-identity.json so it survives restarts. Absence of this
+// file is how the server detects "first run" and triggers the onboarding UI.
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+const FILE = 'agent-identity.json';
+
+export const TONES = Object.freeze(['concise', 'playful', 'formal', 'dry']);
+
+function identityPath(dataDir) {
+  return path.join(dataDir, FILE);
+}
+
+export function loadIdentity(dataDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(identityPath(dataDir), 'utf8'));
+    return sanitize(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function sanitize(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const name = typeof raw.name === 'string' ? raw.name.trim().slice(0, 40) : '';
+  if (!name) return null;
+  const tone = TONES.includes(raw.tone) ? raw.tone : 'concise';
+  const color =
+    typeof raw.color === 'string' && /^#[0-9a-fA-F]{6}$/.test(raw.color)
+      ? raw.color
+      : '#22d3ee';
+  return {
+    name,
+    tone,
+    color,
+    createdAt: Number(raw.createdAt) || Date.now(),
+    onboardedAt: raw.onboardedAt ? Number(raw.onboardedAt) : null,
+    workspaceFirstSeen: raw.workspaceFirstSeen || null,
+    connectedServices: Array.isArray(raw.connectedServices)
+      ? raw.connectedServices.filter((s) => typeof s === 'string')
+      : [],
+  };
+}
+
+export function saveIdentity(dataDir, partial) {
+  const existing = loadIdentity(dataDir) || {};
+  const merged = sanitize({
+    createdAt: Date.now(),
+    ...existing,
+    ...partial,
+  });
+  if (!merged) throw new Error('identity-requires-name');
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(identityPath(dataDir), JSON.stringify(merged, null, 2));
+  return merged;
+}
+
+export function markOnboarded(dataDir) {
+  const existing = loadIdentity(dataDir);
+  if (!existing) throw new Error('identity-not-set');
+  return saveIdentity(dataDir, { onboardedAt: Date.now() });
+}