@opticell/workflow-companion 0.0.0-stage → 1.5.0

package/index.js

@@ -0,0 +1,1175 @@
+#!/usr/bin/env node
+// WorkFlow MCP server — lets Claude Desktop, Claude Code or any MCP client
+// drive WorkFlow through the Agent Bridge. Speaks MCP (JSON-RPC 2.0) over
+// stdio. Plain Node, no dependencies, one file — it ships inside the app and
+// is written into the bridge folder as tools/index.js, and packed into
+// WorkFlow.mcpb for one-click install in Claude Desktop.
+//
+// Reads come from snapshot.json (the app's own export, rewritten after every
+// save). Writes are JSON command files dropped into inbox/; the app applies
+// them and answers with a receipt in outbox/. Nothing here touches the
+// database, and the app's Settings toggles and Command History govern every
+// write exactly as they do for the command line.
+//
+// Where the bridge is, in order: $WF_BRIDGE (baked into the bundle at export),
+// the app's location.json pointer, the app's container.
+//
+// iCloud mode (5.2) — the WorkFlow companion, published to npm as
+// @opticell/workflow-companion for Claude on Windows or Linux. Same tools,
+// but commands and receipts travel as records in the user's own private
+// iCloud (zone AgentBridge) and WorkFlow on their Mac applies them. The Mac
+// is the only applier; this never writes WorkFlow's own records. Chosen with
+// --cloud, WF_MODE=cloud, or automatically off the Mac. `setup` signs in.
+
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_INFO = { name: "workflow", version: "1.5.0" };
+// Who the agent is in WorkFlow: the assignee its queue follows, the @name
+// that calls it, the signature on what it writes. On the Mac it's Claude.
+// A companion goes by the name chosen at setup (default "Companion"), so a
+// task can be meant for the server's Claude rather than the Mac's.
+let AGENT = { name: "Claude", authorID: "agent.claude" };
+
+// ------------------------------------------------------------------ bridge
+
+function containerRoot() {
+  return path.join(os.homedir(), "Library/Containers/mac.TeamDZX.worflow/Data/Library/Application Support/AgentBridge");
+}
+
+function bridgeRoot() {
+  if (process.env.WF_BRIDGE) return process.env.WF_BRIDGE;
+  try {
+    const pointer = JSON.parse(fs.readFileSync(path.join(containerRoot(), "location.json"), "utf8"));
+    if (pointer.root && fs.existsSync(pointer.root)) return pointer.root;
+  } catch (_) { /* no pointer: the bridge is still inside the container */ }
+  return containerRoot();
+}
+
+const ROOT = bridgeRoot();
+const P = {
+  snapshot: path.join(ROOT, "snapshot.json"),
+  state: path.join(ROOT, "state.json"),
+  inbox: path.join(ROOT, "inbox"),
+  outbox: path.join(ROOT, "outbox"),
+  attachments: path.join(ROOT, "attachments"),
+};
+
+function readJSON(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch (_) { return fallback; }
+}
+
+function snapshot() {
+  if (CLOUD) {
+    if (!cloudSnap) throw new Error("No snapshot in iCloud yet. Switch the companion on in WorkFlow: WorkFlow → Settings → Windows Companion → Answer the Companion (iPhone, iPad), or Settings → Agent Bridge → Cloud Bridge (Mac).");
+    return cloudSnap;
+  }
+  const s = readJSON(P.snapshot, null);
+  if (!s) throw new Error(`No snapshot at ${P.snapshot}. Is WorkFlow running with Settings → Agent Bridge switched on?`);
+  return s;
+}
+
+function state() { return readJSON(P.state, {}); }
+
+// A command file is written atomically (temp + rename) so the app never sees
+// a half-written file. Then wait for the receipt the app writes.
+// `keepEmpty` names fields where "" is meaningful (clear the notes, unassign).
+// Pass as waitMs for a short wait in iCloud mode (setup's name registration).
+// Any other value means the full wait there: the folder bridge answers in
+// milliseconds, iCloud in seconds to minutes, so the folder timeouts the
+// tools pass don't carry over.
+const QUICK_WAIT = -1;
+
+async function send(op, fields, waitMs = 8000, keepEmpty = []) {
+  const id = `mcp-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const command = Object.assign({ id, op }, prune(fields, keepEmpty));
+  if (CLOUD) {
+    const clash = blockingClash();
+    if (clash) {
+      const fix = process.env.WF_AGENT_NAME !== undefined
+        ? "Change it in Claude Desktop → Settings → Extensions → WorkFlow Companion → Name in WorkFlow."
+        : `Run "workflow-companion setup --name <another>", or add --takeover if this computer replaces ${clash.host}.`;
+      throw new Error(`Not sent: "${AGENT.name}" is also the name of Claude on ${clash.host}, so both computers would act on @${AGENT.name}. ${fix}`);
+    }
+    return cloud.send(Object.assign(command, { agentName: AGENT.name }), waitMs === QUICK_WAIT);
+  }
+  if (waitMs === QUICK_WAIT) waitMs = 5000;
+  if (!fs.existsSync(P.inbox)) throw new Error(`No inbox at ${P.inbox}. Is the Agent Bridge switched on?`);
+  const final = path.join(P.inbox, `${id}.json`);
+  const temp = path.join(P.inbox, `.${id}.json.tmp`);
+  fs.writeFileSync(temp, JSON.stringify(command, null, 2));
+  fs.renameSync(temp, final);
+  const receiptPath = path.join(P.outbox, `${id}.json`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(receiptPath)) {
+      const r = readJSON(receiptPath, null);
+      if (r) return r;
+    }
+    await delay(120);
+  }
+  return { status: "pending", message: `No receipt within ${waitMs / 1000}s — the app may be closed or the bridge off. The command stays in inbox/ and is applied when the app next looks.` };
+}
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function prune(obj, keepEmpty = []) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v !== undefined && v !== null && (v !== "" || keepEmpty.includes(k))) out[k] = v;
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ iCloud
+
+// Companion settings. "worflow" (no k) is the container's real name.
+const COMPANION = {
+  container: "iCloud.TeamDZX.worflow.app",
+  env: "production",
+  zone: "AgentBridge",
+  // The hosted Apple sign-in page. The API token below is registered to this
+  // origin in CloudKit Console, and Apple checks the Origin header on every
+  // call, so the companion sends it too (a browser safeguard, not a secret).
+  signInURL: "https://companion.opticell-limited.com",
+  origin: "https://companion.opticell-limited.com",
+  // Production API token (CloudKit Console → Tokens & Keys). Not a secret:
+  // it only lets a signed-in user reach their own data. Set at release.
+  apiToken: "3442e21322e2ef2fb54c45c5af82b66f198b01a0cf4e02fe34318781dc4375f7",
+  home: path.join(os.homedir(), ".workflow-companion"),
+};
+const CP = {
+  config: path.join(COMPANION.home, "config.json"),
+  token: path.join(COMPANION.home, "token.txt"),
+  lock: path.join(COMPANION.home, "token.lock"),
+  snapshot: path.join(COMPANION.home, "snapshot.json"),
+  pending: path.join(COMPANION.home, "pending.json"),
+};
+
+const argv = process.argv.slice(2);
+const CLOUD = argv.includes("--cloud") || process.env.WF_MODE === "cloud" ||
+  (!argv.includes("--folder") && process.env.WF_MODE !== "folder" && !process.env.WF_BRIDGE &&
+    (process.platform !== "darwin" || (fs.existsSync(CP.config) && !fs.existsSync(ROOT))));
+
+const DEFAULT_COMPANION_NAME = "Companion";
+function agentFor(name) {
+  const clean = String(name || "").trim().replace(/^@/, "") || DEFAULT_COMPANION_NAME;
+  return { name: clean, authorID: "agent." + clean.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") };
+}
+// Names must survive as an @mention and a CloudKit-safe id.
+function validAgentName(name) { return /^[A-Za-z][A-Za-z0-9_-]{0,23}$/.test(String(name || "").trim()) && !/^claude$/i.test(String(name).trim()); }
+// Claude Desktop sets the name in the extension's settings (WF_AGENT_NAME);
+// the command line sets it at setup. An unusable name falls back to the default.
+if (CLOUD) {
+  const fromDesktop = (process.env.WF_AGENT_NAME || "").trim();
+  const chosen = fromDesktop && !fromDesktop.startsWith("${") ? fromDesktop : (readJSON(CP.config, {}) || {}).agentName;
+  AGENT = agentFor(validAgentName(chosen) ? chosen : DEFAULT_COMPANION_NAME);
+}
+
+let cloudSnap = null;     // the Mac's snapshot, as last downloaded
+let cloudStatus = null;   // heartbeats: { mac, mobile } (an iPhone or iPad can answer too)
+let cloudLoadedAt = 0;
+
+class SignInNeeded extends Error {}
+
+function saveAtomic(file, text) {
+  fs.mkdirSync(COMPANION.home, { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+// Claude Desktop has no terminal step: the extension's "Sign-in token"
+// setting (kept by Claude Desktop, marked sensitive) arrives as
+// WF_SIGNIN_TOKEN. A token not seen before is taken in once; from then on the
+// rotating copy on disk is the live one. Pasting a fresh token into the
+// setting is how a lapsed sign-in is renewed.
+function importDesktopToken() {
+  const given = (process.env.WF_SIGNIN_TOKEN || "").replace(/\s+/g, "");
+  if (!given || given.startsWith("${")) return;
+  const seen = require("crypto").createHash("sha256").update(given).digest("hex");
+  const prior = readJSON(CP.config, null);
+  if (prior && prior.importedTokenSHA === seen && fs.existsSync(CP.token)) return;
+  const apiToken = (prior && prior.apiToken) || COMPANION.apiToken;
+  saveAtomic(CP.config, JSON.stringify({ container: COMPANION.container, env: (prior && prior.env) || COMPANION.env, apiToken,
+    origin: (prior && prior.origin) || COMPANION.origin, agentName: prior && prior.agentName,
+    since: new Date().toISOString(), importedTokenSHA: seen }, null, 2));
+  saveAtomic(CP.token, given);
+  try { fs.unlinkSync(CP.snapshot); } catch (_) {}
+}
+
+function companionConfig() {
+  importDesktopToken();
+  const cfg = readJSON(CP.config, null);
+  if (!cfg || !fs.existsSync(CP.token)) throw new SignInNeeded(signInHelp("This computer isn't signed in to iCloud for WorkFlow yet."));
+  return cfg;
+}
+
+function signInHelp(why) {
+  if (process.env.WF_SIGNIN_TOKEN !== undefined) {
+    return `${why}\nSign in at ${COMPANION.signInURL} with the Apple Account WorkFlow uses on your iPhone or Mac, then paste the token it shows into Claude Desktop → Settings → Extensions → WorkFlow Companion → Sign-in token.`;
+  }
+  return `${why}\nIn a terminal on this computer, run:\n  npx -y @opticell/workflow-companion setup\nand sign in with the Apple Account WorkFlow uses on your iPhone or Mac.`;
+}
+
+const cloud = (() => {
+  // One request at a time, across every companion process on this computer.
+  // Apple answers each call with a new web auth token that replaces the old
+  // one: two requests in flight would each get a successor and one would be
+  // lost. In-process calls queue on `chain`; other processes wait on the lock
+  // file, and the token is re-read from disk once the lock is held.
+  let chain = Promise.resolve();
+  const serial = fn => { const run = chain.then(fn, fn); chain = run.catch(() => {}); return run; };
+
+  function lockHolderAlive(text) {
+    const pid = parseInt(text, 10);
+    if (!pid) return false;
+    try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+  }
+
+  async function withLock(fn) {
+    fs.mkdirSync(COMPANION.home, { recursive: true });
+    const deadline = Date.now() + 30000;
+    for (;;) {
+      try {
+        const fd = fs.openSync(CP.lock, "wx");
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        break;
+      } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        let holder = "";
+        try { holder = fs.readFileSync(CP.lock, "utf8"); } catch (_) { continue; }
+        let age = 0;
+        try { age = Date.now() - fs.statSync(CP.lock).mtimeMs; } catch (_) { continue; }
+        // A holder that died, or one stuck far longer than any request takes.
+        if (!lockHolderAlive(holder) || age > 120000) { try { fs.unlinkSync(CP.lock); } catch (_) {} continue; }
+        if (Date.now() > deadline) throw new Error(`Another WorkFlow companion (process ${holder}) has held the iCloud sign-in for ${Math.round(age / 1000)}s. Try again shortly.`);
+        await delay(150);
+      }
+    }
+    try { return await fn(); } finally { try { fs.unlinkSync(CP.lock); } catch (_) {} }
+  }
+
+  // One CloudKit Web Services call. The successor token is saved before
+  // anything else happens with the answer - errors included.
+  function call(endpoint, body) {
+    return serial(() => withLock(async () => {
+      const cfg = companionConfig();
+      const token = fs.readFileSync(CP.token, "utf8").trim();
+      const base = `https://api.apple-cloudkit.com/database/1/${encodeURIComponent(cfg.container || COMPANION.container)}/${cfg.env || COMPANION.env}`;
+      const q = `ckAPIToken=${encodeURIComponent(cfg.apiToken)}&ckWebAuthToken=${encodeURIComponent(token)}`;
+      let res;
+      try {
+        res = await fetch(`${base}/${endpoint}?${q}`, {
+          method: body ? "POST" : "GET",
+          headers: Object.assign({ Origin: cfg.origin || COMPANION.origin }, body ? { "Content-Type": "application/json" } : {}),
+          body: body ? JSON.stringify(body) : undefined,
+        });
+      } catch (e) {
+        throw new Error(`Can't reach iCloud (${(e.cause && e.cause.code) || e.message}). Check this computer's internet connection.`);
+      }
+      const next = res.headers.get("x-apple-cloudkit-web-auth-token");
+      if (next && next !== token) saveAtomic(CP.token, next);
+      const json = await res.json().catch(() => ({}));
+      if (res.status === 401 || res.status === 421 || json.serverErrorCode === "AUTHENTICATION_REQUIRED") {
+        throw new SignInNeeded(signInHelp(`The iCloud sign-in has ended (HTTP ${res.status}).`));
+      }
+      if (!res.ok) throw Object.assign(new Error(`iCloud refused ${endpoint}: ${json.reason || res.statusText} (${json.serverErrorCode || res.status})`), { code: json.serverErrorCode });
+      return json;
+    }));
+  }
+
+  const zoneID = { zoneName: COMPANION.zone };
+
+  function recordError(r) {
+    if (!r || !r.serverErrorCode) return null;
+    if (r.serverErrorCode === "ZONE_NOT_FOUND") return new Error("The companion isn't switched on in WorkFlow yet: WorkFlow → Settings → Windows Companion → Answer the Companion (iPhone, iPad), or Settings → Agent Bridge → Cloud Bridge (Mac). It sets up the iCloud side the first time it runs.");
+    return Object.assign(new Error(`iCloud: ${r.reason || r.serverErrorCode} (${r.serverErrorCode})`), { code: r.serverErrorCode });
+  }
+
+  // Records by name; a missing one comes back as null.
+  async function lookup(names) {
+    const out = await call("private/records/lookup", { zoneID, records: names.map(recordName => ({ recordName })) });
+    const byName = {};
+    for (const [i, r] of (out.records || []).entries()) {
+      if (r.serverErrorCode === "NOT_FOUND") { byName[names[i]] = null; continue; }
+      const err = recordError(r);
+      if (err) throw err;
+      byName[r.recordName] = r;
+    }
+    return byName;
+  }
+
+  const field = (r, k) => r && r.fields && r.fields[k] ? r.fields[k].value : undefined;
+
+  // The Mac's heartbeat and its latest snapshot, in one lookup. The snapshot
+  // is downloaded only when its hash changes; a read burst within a few
+  // seconds reuses what's here.
+  async function load(force = false) {
+    if (!force && cloudSnap && Date.now() - cloudLoadedAt < 5000) return;
+    const got = await lookup(["snapshot", "status", "status-mobile"]);
+    const beat = r => r ? { aliveAt: field(r, "aliveAt"), appVersion: field(r, "appVersion"),
+      device: field(r, "device"), pollSeconds: field(r, "pollSeconds") } : null;
+    cloudStatus = { mac: beat(got.status), mobile: beat(got["status-mobile"]) };
+    const rec = got.snapshot;
+    cloudLoadedAt = Date.now();
+    if (!rec) return;
+    const sha = field(rec, "sha");
+    const cached = cloudSnap || readJSON(CP.snapshot, null);
+    if (cached && cached._sha === sha) { cloudSnap = cached; return; }
+    const asset = field(rec, "snapshot");
+    if (!asset || !asset.downloadURL) throw new Error("The snapshot in iCloud has no file attached.");
+    const res = await fetch(asset.downloadURL.replace("${f}", "snapshot.json"));
+    if (!res.ok) throw new Error(`Couldn't download the snapshot (HTTP ${res.status}).`);
+    const snap = await res.json();
+    snap._sha = sha;
+    cloudSnap = snap;
+    saveAtomic(CP.snapshot, JSON.stringify(snap));
+  }
+
+  // Who answers: the Mac while it's awake (it stands the iPhone down), else
+  // an iPhone or iPad. One line per device that has ever checked in.
+  const MAC_FRESH_MIN = 10;
+  const minsAgo = b => Math.round((Date.now() - b.aliveAt) / 60000);
+  const agoText = m => m < 1 ? "just now" : m < 90 ? `${m} min ago` : m < 48 * 60 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} days ago`;
+
+  function macLine() {
+    const mac = cloudStatus && cloudStatus.mac && cloudStatus.mac.aliveAt ? cloudStatus.mac : null;
+    const mobile = cloudStatus && cloudStatus.mobile && cloudStatus.mobile.aliveAt ? cloudStatus.mobile : null;
+    if (!mac && !mobile) return "no Mac, iPhone or iPad has answered yet — switch on Cloud Bridge (Mac) or Answer the Companion (iPhone, iPad) in WorkFlow's Settings";
+    const parts = [];
+    if (mac) {
+      const m = minsAgo(mac);
+      parts.push(`WorkFlow ${mac.appVersion || "?"} on ${mac.device || "the Mac"}, last seen ${agoText(m)}${m > MAC_FRESH_MIN ? " (asleep, or WorkFlow is closed)" : " — answering"}`);
+    }
+    if (mobile) {
+      const m = minsAgo(mobile);
+      const standingBy = mac && minsAgo(mac) <= MAC_FRESH_MIN;
+      parts.push(`WorkFlow ${mobile.appVersion || "?"} on ${mobile.device || "an iPhone"}, last seen ${agoText(m)}${standingBy ? " (standing by while the Mac answers)" : " — answers when iOS next wakes WorkFlow, usually within minutes, or when it's opened"}`);
+    }
+    return parts.join("; ");
+  }
+
+  // Commands that went out without a receipt in time. Each process keeps
+  // its own list (pending-<pid>.json) and collects only its own receipts, so
+  // two Claude sessions never take each other's. A list left by a process
+  // that has since exited is adopted by whichever one looks next; receipts
+  // found that way, or too late, go to late.json for workflow_state.
+  const pendingFile = pid => path.join(COMPANION.home, `pending-${pid}.json`);
+  const own = () => readJSON(pendingFile(process.pid), []);
+  const setOwn = rows => rows.length ? saveAtomic(pendingFile(process.pid), JSON.stringify(rows.slice(-50)))
+    : (() => { try { fs.unlinkSync(pendingFile(process.pid)); } catch (_) {} })();
+  function orphans() {
+    let files = [];
+    try { files = fs.readdirSync(COMPANION.home).filter(f => /^pending-\d+\.json$/.test(f)); } catch (_) {}
+    const out = [];
+    for (const f of files) {
+      const pid = f.slice(8, -5);
+      if (pid === String(process.pid) || lockHolderAlive(pid)) continue;
+      for (const row of readJSON(path.join(COMPANION.home, f), [])) out.push(Object.assign({ file: f }, row));
+    }
+    return out;
+  }
+  const pending = () => own().concat(orphans());
+
+  // Under the lock: other processes append to the same files.
+  const locked = fn => serial(() => withLock(async () => fn()));
+
+  async function collect(current) {
+    const mine = own(), adopted = orphans();
+    const rows = [{ name: current }].concat(mine.filter(p => p.name !== current), adopted).slice(0, 20);
+    const got = await lookup(rows.map(p => `receipt-${p.name}`));
+    const found = {};
+    for (const p of rows) { const r = got[`receipt-${p.name}`]; if (r) found[p.name] = readJSONText(field(r, "payload")); }
+    const done = Object.keys(found);
+    if (!done.length) return null;
+    await call("private/records/modify", { zoneID, operations: done.map(n => ({ operationType: "forceDelete", record: { recordName: `receipt-${n}` } })) });
+    setOwn(own().filter(p => !found[p.name]));
+    const lateRows = mine.concat(adopted).filter(p => p.name !== current && found[p.name]);
+    await locked(() => {
+      for (const f of new Set(adopted.map(p => p.file))) {
+        const left = readJSON(path.join(COMPANION.home, f), []).filter(p => !found[p.name]);
+        if (left.length) saveAtomic(path.join(COMPANION.home, f), JSON.stringify(left));
+        else try { fs.unlinkSync(path.join(COMPANION.home, f)); } catch (_) {}
+      }
+      if (lateRows.length) saveAtomic(path.join(COMPANION.home, "late.json"), JSON.stringify(
+        readJSON(path.join(COMPANION.home, "late.json"), []).concat(lateRows.map(p => ({ op: p.op, at: p.at, receipt: found[p.name] }))).slice(-50)));
+    });
+    return found[current] || null;
+  }
+
+  // Late receipts, handed over once.
+  function takeLate() {
+    return locked(() => {
+      const file = path.join(COMPANION.home, "late.json");
+      const rows = readJSON(file, []);
+      try { fs.unlinkSync(file); } catch (_) {}
+      return rows;
+    });
+  }
+
+  async function send(command, quick = false) {
+    const name = command.id;
+    const out = await call("private/records/modify", { zoneID, operations: [{ operationType: "create", record: {
+      recordType: "BridgeCommand", recordName: name,
+      fields: {
+        payload: { value: JSON.stringify(command), type: "STRING" },
+        source: { value: `companion@${os.hostname()}`, type: "STRING" },
+        createdAt: { value: Date.now(), type: "TIMESTAMP" },
+      },
+    } }] });
+    const err = recordError((out.records || [])[0]);
+    if (err) throw err;
+    setOwn(own().concat({ name, op: command.op, at: new Date().toISOString() }));
+    // A push usually brings the Mac within seconds; failing that it looks
+    // every 15 s. Check often at first, then wait out a little over two rounds.
+    const schedule = quick ? [2000, 3000, 5000] : [2000, 2000, 2000, 2000, 2000, 5000, 5000, 5000, 5000, 5000, 5000];
+    for (const wait of schedule) {
+      await delay(wait);
+      const receipt = await collect(name);
+      if (receipt) { cloudLoadedAt = 0; return receipt; }
+    }
+    await load(true).catch(() => {});
+    return { status: "pending", message: `Sent to iCloud, but WorkFlow hasn't answered within ${Math.round(schedule.reduce((a, b) => a + b) / 1000)} s (${macLine()}). The command waits safely in iCloud and runs when WorkFlow next looks; its receipt shows in workflow_state.` };
+  }
+
+  return { call, lookup, load, send, macLine, pending, takeLate, collect, field };
+})();
+
+// The companions WorkFlow knows, from the hidden task the applying device
+// keeps (5.2). Another computer already answering to a name makes the name
+// unusable here: both would act on the same @mention.
+function companionRoster() {
+  const holder = (cloudSnap && cloudSnap.tasks || []).find(t => t.title === "⚙︎ Agent companions");
+  try { return JSON.parse(holder && holder.pinnedNote || "[]"); } catch (_) { return []; }
+}
+
+function nameClash(name) {
+  const me = os.hostname();
+  return companionRoster().find(e => String(e.name).toLowerCase() === String(name).toLowerCase() && e.host && e.host !== me) || null;
+}
+
+// Checked before every command, so a name set in Claude Desktop's settings
+// (which never runs setup) is held to the same rule. A clash stops counting
+// once the other computer has been silent for two weeks (replaced or gone),
+// or when setup --takeover recorded that this computer replaces it.
+const CLASH_WINDOW_MS = 14 * 24 * 3600 * 1000;
+function blockingClash() {
+  const clash = nameClash(AGENT.name);
+  if (!clash) return null;
+  if (clash.seen && Date.now() - new Date(clash.seen) > CLASH_WINDOW_MS) return null;
+  if ((readJSON(CP.config, {}) || {}).takeoverFrom === clash.host) return null;
+  return clash;
+}
+
+function readJSONText(text) { try { return JSON.parse(text); } catch (_) { return { status: "applied", message: String(text || "") }; } }
+
+// ------------------------------------------------------------------ lookup
+
+function findIn(rows, needle, label) {
+  const n = String(needle).trim().toLowerCase();
+  let hit = rows.find(r => String(r.id).toLowerCase() === n);
+  if (hit) return hit;
+  const exact = rows.filter(r => (r.title || "").toLowerCase() === n);
+  if (exact.length === 1) return exact[0];
+  const partial = rows.filter(r => (r.title || "").toLowerCase().includes(n));
+  if (partial.length === 1) return partial[0];
+  if (partial.length > 1) throw new Error(`"${needle}" matches ${partial.length} ${label}s: ${partial.slice(0, 5).map(r => `“${r.title}”`).join(", ")} — be more specific.`);
+  throw new Error(`No ${label} matches "${needle}".`);
+}
+
+function findTask(needle, includeHidden = true) {
+  const rows = snapshot().tasks.filter(t => includeHidden || !t.isHidden);
+  return findIn(rows, needle, "task");
+}
+
+function findDocument(needle) {
+  const docs = snapshot().documents;
+  if (!docs) throw new Error("No documents in the snapshot — this needs WorkFlow 5.0 with the bridge on.");
+  const n = String(needle).trim().toLowerCase();
+  const hit = docs.find(d => d.id.toLowerCase() === n || (d.versions || []).some(v => v.id.toLowerCase() === n))
+    || docs.find(d => (d.number || "").toLowerCase() === n)
+    || docs.find(d => (d.name || "").toLowerCase() === n);
+  if (hit) return hit;
+  const partial = docs.filter(d => (d.name || "").toLowerCase().includes(n));
+  if (partial.length === 1) return partial[0];
+  if (partial.length > 1) throw new Error(`"${needle}" matches ${partial.length} documents: ${partial.slice(0, 5).map(d => `${d.number} “${d.name}”`).join(", ")} — use a WF-number.`);
+  throw new Error(`No document matches "${needle}".`);
+}
+
+function documentLine(d) {
+  const where = d.task || (d.inWorkspace ? `workspace ${d.project}` : "note");
+  return `${d.number} v${d.version}  ${d.name}${d.type ? `  [${d.type}]` : ""}${d.status ? `  (${d.status})` : ""}  — ${where}${d.folder ? ` / ${d.folder}` : ""}`;
+}
+
+function stageFile(file) {
+  if (CLOUD) throw new Error("Files can't be sent through iCloud yet — attach it in WorkFlow itself, or put its text in a comment or note.");
+  const src = path.resolve(file.replace(/^~/, os.homedir()));
+  if (!fs.existsSync(src)) throw new Error(`no such file: ${src}`);
+  fs.mkdirSync(P.attachments, { recursive: true });
+  const staged = path.join(P.attachments, path.basename(src));
+  if (path.resolve(staged) !== src) fs.copyFileSync(src, staged);
+  return path.basename(src);
+}
+
+function findNote(needle) {
+  return findIn(snapshot().notes || [], needle, "note");
+}
+
+function local(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return isNaN(d) ? iso : d.toLocaleString("en-GB", { dateStyle: "medium", timeStyle: "short" });
+}
+
+// ------------------------------------------------------------------ views
+
+function taskLine(t) {
+  const due = t.dueDate ? ` due ${local(t.dueDate).split(",")[0]}` : "";
+  const proj = t.project ? ` [${t.project}]` : "";
+  const who = t.assignee ? ` → ${t.assignee}` : "";
+  return `${t.status.padEnd(12)} ${t.title}${proj}${due}${who}`;
+}
+
+function showTask(t) {
+  const lines = [`${t.title}  (${t.status}, ${t.priority})`, `id ${t.id}`];
+  if (t.project) lines.push(`project: ${t.project}`);
+  if (t.assignee) lines.push(`assignee: ${t.assignee}`);
+  if (t.dueDate) lines.push(`due: ${local(t.dueDate)}`);
+  if (t.tags && t.tags.length) lines.push(`tags: ${t.tags.join(", ")}`);
+  if (t.pinnedNote) lines.push(`status: ${t.pinnedNote}`);
+  if (t.notes) lines.push("", t.notes);
+  if (t.subtasks && t.subtasks.length) {
+    lines.push("");
+    for (const s of t.subtasks) lines.push(`  [${s.isCompleted ? "x" : " "}] ${s.title}`);
+  }
+  const comments = t.comments || [];
+  lines.push("", `${comments.length} comment(s):`);
+  for (const c of comments) lines.push("", `  ${c.author} · ${local(c.timestamp)}`, `    ${(c.text || "").replace(/\n/g, "\n    ")}`);
+  return lines.join("\n");
+}
+
+// "@Name" addressed to this agent, as a whole word.
+function mentionsMe(text) {
+  const name = AGENT.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^A-Za-z0-9_])@${name}(?![A-Za-z0-9_])`, "i").test(text || "");
+}
+
+// A task counts as addressed to this agent when one of its last three
+// comments, written by a person, says @Name. Never in a shared project:
+// a collaborator can write into those threads, so a mention there is not
+// the owner asking (the same rule as the Mac's wake trigger).
+function addressedToMe(t, sharedProjects) {
+  if (t.project && sharedProjects.has(t.project)) return false;
+  return (t.comments || []).slice(-3).some(c => !String(c.authorID || "").startsWith("agent.") && mentionsMe(c.text));
+}
+
+function showNote(n) {
+  const lines = [n.title || "(untitled)", `id ${n.id}`];
+  if (n.isPinned) lines.push("pinned");
+  if (n.isArchived) lines.push("archived");
+  if (n.convertedTargetName) lines.push(`converted → ${n.convertedTargetName}`);
+  lines.push(`updated: ${local(n.updatedAt)}`, "", n.body || "");
+  return lines.join("\n");
+}
+
+function receiptText(r) {
+  const tag = r.status === "applied" ? "[ok]" : `[${r.status}]`;
+  const extra = [r.taskID && `task ${r.taskID}`, r.noteID && `note ${r.noteID}`, r.projectID && `project ${r.projectID}`].filter(Boolean);
+  return `${tag} ${r.message || ""}${extra.length ? "\n       " + extra.join("  ") : ""}`;
+}
+
+// ------------------------------------------------------------------ tools
+
+const TOOLS = [
+  {
+    name: "workflow_state",
+    description: "Whether the Agent Bridge is running, where it lives, and the app version. Use this first if anything else fails.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => {
+      if (CLOUD) return cloudStateText();
+      const s = state();
+      const snap = readJSON(P.snapshot, null);
+      return [
+        `bridge      ${ROOT}`,
+        `enabled     ${s.enabled === undefined ? "unknown (no state.json)" : s.enabled}`,
+        `app         ${s.appVersion || "?"} (${s.build || "?"})`,
+        `wake        ${s.wakeEnabled ? "on" : "off"}`,
+        `snapshot    ${snap ? `${snap.tasks.length} tasks, ${(snap.notes || []).length} notes, generated ${local(snap.generatedAt)}` : "none yet"}`,
+      ].join("\n");
+    },
+  },
+  {
+    name: "workflow_list_tasks",
+    description: "List tasks with status, priority, project and due date.",
+    inputSchema: { type: "object", properties: { all: { type: "boolean", description: "Include hidden and completed tasks" } } },
+    handler: a => {
+      const rows = snapshot().tasks.filter(t => a.all || (!t.isHidden && t.status !== "Completed"));
+      return rows.length ? rows.map(taskLine).join("\n") : "no tasks";
+    },
+  },
+  {
+    name: "workflow_get_task",
+    description: "One task in full, with its checklist and comment thread. Accepts a task id or a fragment of its title.",
+    inputSchema: { type: "object", properties: { task: { type: "string" } }, required: ["task"] },
+    handler: a => showTask(findTask(a.task)),
+  },
+  {
+    name: "workflow_queue",
+    description: `Your inbox as "${AGENT.name}": tasks assigned to ${AGENT.name}, tasks whose recent comments say @${AGENT.name}, and notes that say @${AGENT.name} — each with why it's here, its status line, checklist and latest comment. Work meant for another agent (such as ${AGENT.name === "Claude" ? "a companion" : "Claude on the Mac"}) is not yours.`,
+    inputSchema: { type: "object", properties: {} },
+    handler: () => {
+      const snap = snapshot();
+      const shared = new Set((snap.projects || []).filter(p => p.isShared).map(p => p.name));
+      const mine = t => (t.assignee || "").toLowerCase() === AGENT.name.toLowerCase();
+      const rows = snap.tasks.filter(t => t.status !== "Completed" && !t.isHidden && (mine(t) || addressedToMe(t, shared)));
+      const notes = (snap.notes || []).filter(n => !n.isArchived && !n.convertedAt && mentionsMe(`${n.title || ""}\n${n.body || ""}`));
+      if (!rows.length && !notes.length) return "queue empty";
+      const out = rows.map(t => {
+        const last = (t.comments || []).slice(-1)[0];
+        const open = (t.subtasks || []).filter(s => !s.isCompleted).length;
+        const why = mine(t) ? `assigned to ${AGENT.name}` : `@${AGENT.name} in a comment`;
+        return [`${t.title} [${t.project || "—"}]  id ${t.id}  (${why})`, t.pinnedNote ? `  status: ${t.pinnedNote}` : null, open ? `  ${open} open subtask(s)` : null, last ? `  last: ${last.author}: ${last.text.slice(0, 160)}` : null].filter(Boolean).join("\n");
+      });
+      for (const n of notes) out.push(`note: ${n.title || "(untitled)"}  id ${n.id}  (@${AGENT.name} in the note — answer with workflow_reply_note)`);
+      return out.join("\n\n");
+    },
+  },
+  {
+    name: "workflow_poll_comments",
+    description: "Comments the user has written recently, ignoring the agent's own. Defaults to the last 24 hours.",
+    inputSchema: { type: "object", properties: { since: { type: "string", description: "ISO-8601" } } },
+    handler: a => {
+      const since = a.since ? new Date(a.since) : new Date(Date.now() - 86400000);
+      const out = [];
+      for (const t of snapshot().tasks) for (const c of t.comments || []) {
+        if (c.authorID === AGENT.authorID) continue;
+        // Other agents' comments are theirs to follow up, not requests.
+        if (String(c.authorID || "").startsWith("agent.") && !mentionsMe(c.text)) continue;
+        if (new Date(c.timestamp) > since) out.push(`${local(c.timestamp)}  [${t.title}]  ${c.author}: ${c.text}`);
+      }
+      return out.length ? out.join("\n") : "nothing new";
+    },
+  },
+  {
+    name: "workflow_create_task",
+    description: `Create a task. Set assignee to "${AGENT.name}" to put it in your own queue.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string" }, project: { type: "string" }, notes: { type: "string" },
+        due: { type: "string", description: "ISO-8601 or yyyy-MM-dd" },
+        priority: { type: "string", enum: ["High", "Medium", "Low"] },
+        status: { type: "string", description: "To Do / In Progress / Completed" },
+        assignee: { type: "string" }, status_note: { type: "string", description: "Seeds the pinned status line" },
+        tags: { type: "array", items: { type: "string" } }, subtasks: { type: "array", items: { type: "string" } },
+        comment: { type: "string", description: "An opening comment on the new task" },
+      },
+      required: ["title"],
+    },
+    handler: async a => receiptText(await send("create_task", { title: a.title, project: a.project, notes: a.notes, dueDate: a.due, priority: a.priority, status: a.status, assignee: a.assignee, pinnedNote: a.status_note, tags: a.tags, subtasks: a.subtasks, text: a.comment })),
+  },
+  {
+    name: "workflow_comment",
+    description: "Post a comment on a task, authored as the agent. This is how you reply to the user — it reaches their phone as a notification.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, text: { type: "string" }, mentions: { type: "array", items: { type: "string" } } }, required: ["task", "text"] },
+    handler: async a => receiptText(await send("add_comment", { taskID: findTask(a.task).id, text: a.text, mentions: a.mentions })),
+  },
+  {
+    name: "workflow_set_status_line",
+    description: "Set a task's pinned note — the one-line 'where this stands' shown above its comments. Overwrite it as work progresses rather than commenting each time.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, text: { type: "string" } }, required: ["task", "text"] },
+    handler: async a => receiptText(await send("update_task", { taskID: findTask(a.task).id, pinnedNote: a.text })),
+  },
+  {
+    name: "workflow_check_subtasks",
+    description: "Tick subtasks off a task (or untick them), so progress on a long job is visible on the task's own row.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, subtasks: { type: "array", items: { type: "string" } }, uncheck: { type: "boolean" } }, required: ["task", "subtasks"] },
+    handler: async a => receiptText(await send("update_task", Object.assign({ taskID: findTask(a.task).id }, a.uncheck ? { uncheckSubtasks: a.subtasks } : { checkSubtasks: a.subtasks }))),
+  },
+  {
+    name: "workflow_add_subtasks",
+    description: "Add subtasks to an existing task's checklist.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, subtasks: { type: "array", items: { type: "string" } } }, required: ["task", "subtasks"] },
+    handler: async a => receiptText(await send("update_task", { taskID: findTask(a.task).id, addSubtasks: a.subtasks })),
+  },
+  {
+    name: "workflow_update_task",
+    description: "Change an existing task. Only the fields you pass are touched. 'notes' REPLACES the notes; prefer 'append_notes', which adds to the end and keeps the user's formatting. 'add_tags'/'remove_tags' edit tags one at a time without dropping ones the user added.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "id or title" },
+        title: { type: "string" },
+        notes: { type: "string", description: "replaces the notes; empty string clears them" },
+        append_notes: { type: "string", description: "added to the end of the notes" },
+        due: { type: "string", description: "ISO-8601 or yyyy-MM-dd" },
+        no_due_date: { type: "boolean", description: "true removes the due date" },
+        priority: { type: "string", enum: ["High", "Medium", "Low"] },
+        status: { type: "string", description: "To Do / In Progress / Completed" },
+        assignee: { type: "string", description: "empty string unassigns" },
+        project: { type: "string", description: "empty string removes it from its project" },
+        add_tags: { type: "array", items: { type: "string" } },
+        remove_tags: { type: "array", items: { type: "string" } },
+        in_my_day: { type: "boolean" },
+      },
+      required: ["task"],
+    },
+    handler: async a => receiptText(await send("update_task", {
+      taskID: findTask(a.task).id, title: a.title, notes: a.notes, appendNotes: a.append_notes,
+      dueDate: a.due, hasDueDate: a.no_due_date ? false : undefined, priority: a.priority, status: a.status,
+      assignee: a.assignee, project: a.project, addTags: a.add_tags, removeTags: a.remove_tags, isInMyDay: a.in_my_day,
+    }, 8000, ["notes", "assignee", "project"])),
+  },
+  {
+    name: "workflow_remove_subtasks",
+    description: "Delete rows from a task's checklist. Each entry must be an exact title or a fragment only one row contains; anything ambiguous is left alone.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, subtasks: { type: "array", items: { type: "string" } } }, required: ["task", "subtasks"] },
+    handler: async a => receiptText(await send("update_task", { taskID: findTask(a.task).id, removeSubtasks: a.subtasks })),
+  },
+  {
+    name: "workflow_draft_email",
+    description: "Prepare an email a task asks for. It is attached to the task as a draft the user checks and sends with Review & Send; nothing is sent from here. Refused unless the user has set Settings → Agent Bridge → Email to Draft Only or Can Send.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string" },
+        to: { type: "array", items: { type: "string" }, description: "bare addresses, no display names" },
+        cc: { type: "array", items: { type: "string" } },
+        subject: { type: "string" }, body: { type: "string", description: "plain text" },
+      },
+      required: ["task", "to", "subject", "body"],
+    },
+    handler: async a => receiptText(await send("draft_email", { taskID: findTask(a.task).id, emailTo: a.to, emailCc: a.cc, emailSubject: a.subject, emailBody: a.body })),
+  },
+  {
+    name: "workflow_rename_subtask",
+    description: "Retitle one subtask in place, keeping its tick state — for correcting a row's wording (a version line on an index, say) without adding a duplicate.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, from: { type: "string", description: "current title, exact or a fragment it contains" }, to: { type: "string" } }, required: ["task", "from", "to"] },
+    handler: async a => receiptText(await send("update_task", { taskID: findTask(a.task).id, renameSubtasks: [{ from: a.from, to: a.to }] })),
+  },
+  {
+    name: "workflow_complete_task",
+    description: "Mark a task complete.",
+    inputSchema: { type: "object", properties: { task: { type: "string" } }, required: ["task"] },
+    handler: async a => receiptText(await send("complete_task", { taskID: findTask(a.task).id })),
+  },
+  {
+    name: "workflow_create_project",
+    description: "Create a project, or update an existing one of the same name.",
+    inputSchema: { type: "object", properties: { name: { type: "string" }, icon: { type: "string", description: "SF Symbol name" }, color: { type: "string", description: "#RRGGBB" }, description: { type: "string" },
+      status: { type: "string", enum: ["planning", "active", "onHold", "done"] },
+      start: { type: "string", description: "planned start yyyy-MM-dd, or 'none' to clear" },
+      target: { type: "string", description: "target date yyyy-MM-dd, or 'none' to clear" } }, required: ["name"] },
+    handler: async a => receiptText(await send("create_project", { name: a.name, icon: a.icon, colorHex: a.color, projectDescription: a.description,
+      projectStatus: a.status, startDate: a.start === "none" ? undefined : a.start, targetDate: a.target === "none" ? undefined : a.target,
+      clearStartDate: a.start === "none" ? true : undefined, clearTargetDate: a.target === "none" ? true : undefined })),
+  },
+  {
+    name: "workflow_list_notes",
+    description: `The Notepad. A '*' marks notes addressed to you (containing @${AGENT.name}).`,
+    inputSchema: { type: "object", properties: { all: { type: "boolean", description: "Include archived notes" } } },
+    handler: a => {
+      const rows = (snapshot().notes || []).filter(n => a.all || !n.isArchived);
+      if (!rows.length) return "no notes";
+      return rows.map(n => `${mentionsMe(`${n.title || ""}\n${n.body || ""}`) ? "*" : " "} ${(n.title || "(untitled)").padEnd(40)}  ${local(n.updatedAt)}  id ${n.id}`).join("\n");
+    },
+  },
+  {
+    name: "workflow_get_note",
+    description: "One note in full.",
+    inputSchema: { type: "object", properties: { note: { type: "string" } }, required: ["note"] },
+    handler: a => showNote(findNote(a.note)),
+  },
+  {
+    name: "workflow_create_note",
+    description: "File a note in the Notepad. Where output that isn't work belongs — a summary, a finding, a set of options. Use a task instead for anything that needs doing.",
+    inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" }, color: { type: "string", description: "#RRGGBB" }, pin: { type: "boolean" } }, required: ["title"] },
+    handler: async a => receiptText(await send("create_note", { title: a.title, notes: a.body, colorHex: a.color, isPinned: a.pin })),
+  },
+  {
+    name: "workflow_reply_note",
+    description: "Answer a Notepad note inside the note itself: appends a signed, dated reply without changing what the user wrote. Notes have no comment thread, so this is how a note gets an answer on the user's phone.",
+    inputSchema: { type: "object", properties: { note: { type: "string" }, text: { type: "string" }, pin: { type: "boolean" } }, required: ["note", "text"] },
+    handler: async a => receiptText(await send("update_note", { noteID: findNote(a.note).id, appendText: a.text, isPinned: a.pin })),
+  },
+  {
+    name: "workflow_convert_note",
+    description: "Promote a note into a task, keeping the note and linking the two. Converting is what takes a note out of the inbox.",
+    inputSchema: { type: "object", properties: { note: { type: "string" }, project: { type: "string" }, title: { type: "string" }, priority: { type: "string", enum: ["High", "Medium", "Low"] }, due: { type: "string" }, assignee: { type: "string" }, subtasks: { type: "array", items: { type: "string" } } }, required: ["note"] },
+    handler: async a => receiptText(await send("convert_note", { noteID: findNote(a.note).id, project: a.project, title: a.title, priority: a.priority, dueDate: a.due, assignee: a.assignee, subtasks: a.subtasks })),
+  },
+  {
+    name: "workflow_attach_file",
+    description: "Attach a local file to a task (a report, a document, an image). The file is copied into the bridge folder and consumed by the app.",
+    inputSchema: { type: "object", properties: { task: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" }, name: { type: "string", description: "Display name; defaults to the filename" } }, required: ["task", "file"] },
+    handler: async a => {
+      const name = stageFile(a.file);
+      return receiptText(await send("attach_file", { taskID: findTask(a.task).id, fileName: name, displayName: a.name }, 15000));
+    },
+  },
+  {
+    name: "workflow_list_projects",
+    description: "The portfolio: every project's status, planned dates, progress and health (overdue / atRisk / idle / onTrack / planning / onHold / done) with the reason, as the Projects tab shows it.",
+    inputSchema: { type: "object", properties: { all: { type: "boolean", description: "include archived" } } },
+    handler: a => {
+      const rows = (snapshot().projects || []).filter(p => a.all || !p.isArchived);
+      if (rows.length && rows[0].health === undefined) throw new Error("This needs WorkFlow 5.1 with the bridge on.");
+      return rows.map(p => `${p.health.padEnd(9)} ${String(p.status).padEnd(9)} ${String(Math.round(p.progress * 100)).padStart(3)}%  ${p.name}${p.targetDate ? `  target ${p.targetDate.slice(0, 10)}` : ""}  — ${p.healthReason}`).join("\n") || "no projects";
+    },
+  },
+  {
+    name: "workflow_list_documents",
+    description: "List or search documents — every file on a task, on a note, or filed in a project's workspace. The query matches names, document numbers (WF-4F2A91), profiles and the text inside PDFs, scans and text files.",
+    inputSchema: { type: "object", properties: {
+      query: { type: "string" }, project: { type: "string" }, type: { type: "string" }, status: { type: "string" },
+      limit: { type: "number", description: "default 40" } } },
+    handler: a => {
+      const docs = snapshot().documents;
+      if (!docs) throw new Error("No documents in the snapshot — this needs WorkFlow 5.0 with the bridge on.");
+      const q = (a.query || "").toLowerCase();
+      const eq = (x, y) => !y || (x || "").toLowerCase() === y.toLowerCase();
+      const rows = docs.filter(d => eq(d.project, a.project) && eq(d.type, a.type) && eq(d.status, a.status) &&
+        (!q || ["number", "name", "type", "status", "author", "description", "folder", "project", "task", "text"]
+          .some(k => (d[k] || "").toLowerCase().includes(q))))
+        .sort((x, y) => (y.updatedAt || "").localeCompare(x.updatedAt || ""));
+      if (!rows.length) return "no documents match";
+      return rows.slice(0, a.limit || 40).map(documentLine).join("\n");
+    },
+  },
+  {
+    name: "workflow_get_document",
+    description: "One document in full: profile, folder, every version with its comment, and the start of its text.",
+    inputSchema: { type: "object", properties: { document: { type: "string", description: "WF-number, id or file name" } }, required: ["document"] },
+    handler: a => JSON.stringify(findDocument(a.document), null, 2),
+  },
+  {
+    name: "workflow_update_document",
+    description: "Change a document's profile or folder. Profile fields apply to every version; 'name' renames the current file. Folders nest with '/', and '' unfiles.",
+    inputSchema: { type: "object", properties: {
+      document: { type: "string" }, name: { type: "string" },
+      type: { type: "string", description: "Contract, Agreement, Invoice, Quote, Receipt, Letter, Email, Report, Proposal, Minutes, Specification, Drawing, Photo, Form, Policy, Other — or your own" },
+      status: { type: "string", description: "Draft, In Review, Final, Signed, Superseded" },
+      author: { type: "string" }, description: { type: "string" }, folder: { type: "string" } }, required: ["document"] },
+    handler: async a => receiptText(await send("update_document", { documentID: findDocument(a.document).id, documentName: a.name,
+      docType: a.type, docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder },
+      8000, ["docType", "docStatus", "docAuthor", "docSummary", "docFolder"])),
+  },
+  {
+    name: "workflow_file_document",
+    description: "File a local file straight into a project's workspace (not onto a task), with an optional profile and folder.",
+    inputSchema: { type: "object", properties: {
+      project: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      name: { type: "string" }, type: { type: "string" }, status: { type: "string" }, author: { type: "string" },
+      description: { type: "string" }, folder: { type: "string" } }, required: ["project", "file"] },
+    handler: async a => {
+      const name = stageFile(a.file);
+      return receiptText(await send("attach_file", { project: a.project, fileName: name, displayName: a.name, docType: a.type,
+        docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder }, 15000));
+    },
+  },
+  {
+    name: "workflow_add_document_version",
+    description: "Upload a new version of a document. The current file is kept in its history; the profile and folder carry over.",
+    inputSchema: { type: "object", properties: {
+      document: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      comment: { type: "string", description: "What changed" } }, required: ["document", "file"] },
+    handler: async a => {
+      const id = findDocument(a.document).id;
+      const name = stageFile(a.file);
+      return receiptText(await send("add_document_version", { documentID: id, fileName: name, versionComment: a.comment }, 15000));
+    },
+  },
+  {
+    name: "workflow_ping",
+    description: "Confirm the app is watching the bridge (round-trips one command).",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => receiptText(await send("ping", {}, 5000)),
+  },
+];
+
+const TOOLS_BY_NAME = Object.fromEntries(TOOLS.map(t => [t.name, t]));
+const publicTools = () => TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+
+// ------------------------------------------------------------------ protocol
+
+async function handle(request) {
+  const { method, id } = request;
+  const ok = result => ({ jsonrpc: "2.0", id, result });
+  const err = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+  if (method === "initialize") return ok({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
+  if (method === "ping") return ok({});
+  if (method === "tools/list") return ok({ tools: publicTools() });
+  if (method === "tools/call") {
+    const params = request.params || {};
+    const tool = TOOLS_BY_NAME[params.name];
+    if (!tool) return err(-32602, `Unknown tool: ${params.name}`);
+    const args = params.arguments || {};
+    for (const req of (tool.inputSchema.required || [])) if (args[req] === undefined) return err(-32602, `Missing required argument: ${req}`);
+    try {
+      // In iCloud mode every tool reads the Mac's latest snapshot first
+      // (task lookups need it too); workflow_state reports on its own.
+      if (CLOUD && tool.name !== "workflow_state" && tool.name !== "workflow_ping") await cloud.load();
+      return ok({ content: [{ type: "text", text: String(await tool.handler(args)) }], isError: false });
+    } catch (e) {
+      return ok({ content: [{ type: "text", text: `${e.message || e}` }], isError: true });
+    }
+  }
+  if (method && method.startsWith("notifications/")) return null;
+  return err(-32601, `Method not found: ${method}`);
+}
+
+// Requests are answered in the order they arrive.
+function serve() {
+  let buffer = "";
+  let chain = Promise.resolve();
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", chunk => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let request;
+      try { request = JSON.parse(line); } catch (_) { continue; }
+      chain = chain.then(() => handle(request)).then(response => {
+        if (response) process.stdout.write(JSON.stringify(response) + "\n");
+      }, e => process.stderr.write(`workflow: ${e.stack || e}\n`));
+    }
+  });
+  // No process.exit(): on Windows it can abort Node while sockets are still
+  // closing (0xC0000409). Finish what's queued and let the loop drain.
+  process.stdin.on("end", () => { chain.then(() => { process.exitCode = 0; }); });
+  // Apple ends a sign-in left unused for somewhere between 9 and 14 hours
+  // (measured 28-29 Sep). Every call renews it, so while Claude has this
+  // running it touches iCloud every two hours; the scheduled keep-alive that
+  // setup installs covers the hours when it isn't running.
+  if (CLOUD) setInterval(() => { keepAlive().catch(() => {}); }, KEEPALIVE_EVERY_MS).unref();
+}
+
+async function cloudStateText() {
+  const cfg = readJSON(CP.config, null);
+  const lines = [`mode        iCloud (WorkFlow companion ${SERVER_INFO.version}), ${cfg ? cfg.env : COMPANION.env}`];
+  if (!cfg) return lines.concat("", signInHelp("Not signed in yet.")).join("\n");
+  let tokenAge = "";
+  try { tokenAge = local(fs.statSync(CP.token).mtime.toISOString()); } catch (_) {}
+  lines.push(`signed in   yes — token last renewed ${tokenAge}`);
+  let lastKeepAlive = "";
+  try { lastKeepAlive = fs.readFileSync(KEEPALIVE_LOG, "utf8").trim().split("\n").pop(); } catch (_) {}
+  if (lastKeepAlive) lines.push(`keep-alive  last run ${lastKeepAlive}`);
+  lines.push(`name        ${AGENT.name} — assign tasks to "${AGENT.name}", or write @${AGENT.name} in a comment or note`);
+  try {
+    await cloud.load(true);
+    lines.push(`answering   ${cloud.macLine()}`);
+    lines.push(`snapshot    ${cloudSnap ? `${cloudSnap.tasks.length} tasks, ${(cloudSnap.notes || []).length} notes, generated ${local(cloudSnap.generatedAt)}` : "none yet — is the companion switched on in WorkFlow's Settings (Windows Companion on iPhone and iPad, Cloud Bridge on a Mac)?"}`);
+    const clash = cloudSnap ? nameClash(AGENT.name) : null;
+    if (clash) lines.push(`WARNING     ${clash.host} also answers to "${AGENT.name}": both would act on @${AGENT.name}. Run setup with another --name.`);
+  } catch (e) {
+    lines.push(`iCloud      ${e.message}`);
+  }
+  try {
+    // Look once for receipts still owed, then report what came in late.
+    if (cloud.pending().length) await cloud.collect("");
+    for (const l of await cloud.takeLate()) lines.push(`late        ${l.op} (sent ${local(l.at)}): ${receiptText(l.receipt)}`);
+  } catch (_) { /* reported above if iCloud is unreachable */ }
+  const waiting = cloud.pending();
+  if (waiting.length) lines.push(`waiting     ${waiting.length} command(s) sent without a receipt yet: ${waiting.map(p => p.op).join(", ")}`);
+  return lines.join("\n");
+}
+
+// ------------------------------------------------------------------ command line
+
+function arg(name) { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : undefined; }
+
+function ask(question) {
+  const rl = require("readline").createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer.trim()); }));
+}
+
+// Signs this computer in. The hosted page does the Apple sign-in and shows a
+// token; it's pasted here (or passed with --web-token) and kept in
+// ~/.workflow-companion, readable by this user only. The token is a password
+// to the user's iCloud data for WorkFlow: it never goes in a chat.
+async function setup() {
+  const prior = readJSON(CP.config, {}) || {};
+  const apiToken = arg("api-token") || prior.apiToken || COMPANION.apiToken;
+  if (!apiToken) { console.error("No API token is built into this version. Pass --api-token."); return 2; }
+  let webToken = arg("web-token");
+  if (!webToken) {
+    console.log(`WorkFlow companion — sign in\n\n1. Open ${COMPANION.signInURL} (opening it in your browser now).\n2. Sign in with the Apple Account WorkFlow uses on your iPhone or Mac.\n3. Copy the token the page shows and paste it here.\n`);
+    if (!argv.includes("--no-browser")) openBrowser(COMPANION.signInURL);
+    webToken = await ask("Token: ");
+  }
+  if (!webToken) { console.error("No token given; nothing changed."); return 2; }
+  // The name this computer's Claude goes by in WorkFlow. Assign a task to it,
+  // or write @name in a comment or note, to hand work to this machine.
+  let agentName = arg("name") || prior.agentName;
+  if (!agentName) {
+    const answer = argv.includes("--web-token") ? "" : await ask(`\nWhat should Claude on this computer be called in WorkFlow? Tasks for it are assigned to this name,\nor mention @name. Not "Claude", which is the Mac's. [${DEFAULT_COMPANION_NAME}]: `);
+    agentName = answer || DEFAULT_COMPANION_NAME;
+  }
+  agentName = agentName.trim().replace(/^@/, "");
+  if (!validAgentName(agentName)) { console.error(`"${agentName}" won't work as a name: one word: a letter first, then letters, digits, - or _, up to 24 characters, and not "Claude".`); return 2; }
+  saveAtomic(CP.config, JSON.stringify({ container: COMPANION.container, env: arg("env") || prior.env || COMPANION.env, apiToken,
+    // The name is written only once it has passed the clash check below.
+    origin: arg("origin") || prior.origin || COMPANION.origin, agentName: prior.agentName, since: new Date().toISOString() }, null, 2));
+  saveAtomic(CP.token, webToken.replace(/\s+/g, ""));
+  try { fs.unlinkSync(CP.snapshot); } catch (_) {}
+  try {
+    await cloud.call("public/users/caller");
+    console.log("\nSigned in. Saved to " + COMPANION.home);
+  } catch (e) {
+    console.error(`\nThat token didn't work: ${e.message.split("\n")[0]}\nSign in again and copy a fresh token.`);
+    return 1;
+  }
+  // One name, one computer: two machines answering to the same name would
+  // both act on the same @mention.
+  try { await cloud.load(true); } catch (_) { /* no snapshot yet: nothing to clash with */ }
+  for (let clash = nameClash(agentName); clash && !argv.includes("--takeover"); clash = nameClash(agentName)) {
+    const when = clash.seen ? local(clash.seen) : "some time ago";
+    console.error(`\n"${agentName}" is already Claude on ${clash.host} (last heard from ${when}). Two computers with one name would both act on @${agentName}.`);
+    if (argv.includes("--web-token") || argv.includes("--name")) {
+      console.error(`Run setup again with another --name, or with --takeover if this computer replaces ${clash.host}.`);
+      return 2;
+    }
+    const next = (await ask("Another name for this computer: ")).replace(/^@/, "").trim();
+    if (!validAgentName(next)) { console.error(`"${next}" won't work as a name: one word, a letter first, up to 24 characters, not "Claude".`); return 2; }
+    agentName = next;
+  }
+  const saved = readJSON(CP.config, {});
+  saved.agentName = agentName;
+  const replaced = nameClash(agentName);
+  if (replaced) saved.takeoverFrom = replaced.host; else delete saved.takeoverFrom;
+  saveAtomic(CP.config, JSON.stringify(saved, null, 2));
+  AGENT = agentFor(agentName);
+  // Claim the name now rather than at the first real command, so a second
+  // computer set up in the meantime sees it's taken. A ping is harmless;
+  // if the Mac or iPhone is asleep it registers the name when it wakes.
+  console.log(`\nRegistering "${agentName}" with WorkFlow…`);
+  try {
+    const r = await send("ping", {}, QUICK_WAIT);
+    console.log(r.status === "pending" ? "  Queued: it registers when your Mac or iPhone next opens WorkFlow." : `  Done: WorkFlow knows this computer as "${agentName}".`);
+  } catch (e) {
+    console.log(`  Not yet: ${e.message.split("\n")[0]}`);
+  }
+  console.log("\n" + (await cloudStateText()).split("\n").slice(1).join("\n"));
+  if (argv.includes("--no-schedule") || process.env.WF_NO_SCHEDULE) {
+    console.log(`\nNo keep-alive scheduled. An unused sign-in ends after 9 to 14 hours; run "workflow-companion keepalive" more often than that.`);
+  } else {
+    console.log(`\nKeep-alive: ${installSchedule()}. It keeps the sign-in from lapsing while Claude isn't running.`);
+  }
+  console.log(`\nNow add it to Claude Code:\n  claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion`);
+  return 0;
+}
+
+function openBrowser(url) {
+  const { spawn } = require("child_process");
+  const [cmd, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref(); } catch (_) { /* the URL is printed anyway */ }
+}
+
+// ------------------------------------------------------------------ keep-alive
+
+const KEEPALIVE_EVERY_MS = 2 * 3600 * 1000;
+const SCHEDULE_HOURS = 3;
+const KEEPALIVE_LOG = path.join(COMPANION.home, "keepalive.log");
+const TASK_NAME = "WorkFlow Companion keep-alive";
+
+// One cheap call, which renews the sign-in. Logged (last 50 lines) so a
+// lapse can be dated.
+async function keepAlive() {
+  const at = new Date().toISOString();
+  try {
+    await cloud.call("public/users/caller");
+    logKeepAlive(`${at} ok`);
+    return 0;
+  } catch (e) {
+    logKeepAlive(`${at} ${e instanceof SignInNeeded ? "SIGN-IN ENDED" : "failed"}: ${String(e.message).split("\n")[0]}`);
+    return 1;
+  }
+}
+
+function logKeepAlive(line) {
+  let lines = [];
+  try { lines = fs.readFileSync(KEEPALIVE_LOG, "utf8").trim().split("\n"); } catch (_) {}
+  try { fs.mkdirSync(COMPANION.home, { recursive: true }); fs.writeFileSync(KEEPALIVE_LOG, lines.concat(line).slice(-50).join("\n") + "\n"); } catch (_) {}
+}
+
+// Installs the keep-alive as a scheduled job every few hours, running a copy
+// of this file kept in ~/.workflow-companion (npx's cache can be cleared, so
+// its path can't be scheduled). Windows: Task Scheduler, through wscript so no
+// console window flashes up. Elsewhere: the user's crontab.
+function installSchedule() {
+  const { spawnSync } = require("child_process");
+  const script = path.join(COMPANION.home, "workflow-companion.js");
+  fs.mkdirSync(COMPANION.home, { recursive: true });
+  fs.copyFileSync(__filename, script);
+  const node = process.execPath;
+  if (process.platform === "win32") {
+    const vbs = path.join(COMPANION.home, "keepalive.vbs");
+    const q = x => `""${x}""`;
+    fs.writeFileSync(vbs, `CreateObject("WScript.Shell").Run "${q(node)} ${q(script)} keepalive", 0, False\r\n`);
+    const r = spawnSync("schtasks", ["/Create", "/F", "/SC", "HOURLY", "/MO", String(SCHEDULE_HOURS), "/TN", TASK_NAME,
+      "/TR", `wscript.exe "${vbs}"`], { encoding: "utf8" });
+    return r.status === 0 ? `Task Scheduler: "${TASK_NAME}", every ${SCHEDULE_HOURS} hours` : `couldn't add the scheduled task: ${(r.stderr || r.stdout || "").trim()}`;
+  }
+  const line = `17 */${SCHEDULE_HOURS} * * * "${node}" "${script}" keepalive >/dev/null 2>&1 # workflow-companion keepalive`;
+  const current = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+  const kept = (current.status === 0 ? current.stdout : "").split("\n").filter(l => l.trim() && !l.includes("workflow-companion keepalive"));
+  const r = spawnSync("crontab", ["-"], { input: kept.concat(line).join("\n") + "\n", encoding: "utf8" });
+  return r.status === 0 ? `cron, every ${SCHEDULE_HOURS} hours` : `couldn't add the cron job: ${(r.stderr || "").trim()}`;
+}
+
+function removeSchedule() {
+  const { spawnSync } = require("child_process");
+  if (process.platform === "win32") {
+    spawnSync("schtasks", ["/Delete", "/F", "/TN", TASK_NAME], { encoding: "utf8" });
+  } else {
+    const current = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+    if (current.status === 0 && current.stdout.includes("workflow-companion keepalive")) {
+      const kept = current.stdout.split("\n").filter(l => l.trim() && !l.includes("workflow-companion keepalive"));
+      spawnSync("crontab", ["-"], { input: kept.join("\n") + (kept.length ? "\n" : ""), encoding: "utf8" });
+    }
+  }
+  for (const f of ["workflow-companion.js", "keepalive.vbs", "keepalive.log"]) try { fs.unlinkSync(path.join(COMPANION.home, f)); } catch (_) {}
+}
+
+function printConfig() {
+  if (CLOUD) {
+    process.stdout.write(`Claude Code:\n  claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion\n\nClaude Desktop → Settings → Developer → Edit Config, add:\n${JSON.stringify({ mcpServers: { workflow: { command: "npx", args: ["-y", "@opticell/workflow-companion"] } } }, null, 2)}\n`);
+    return;
+  }
+  const cfg = { mcpServers: { workflow: { command: "node", args: [__filename], env: { WF_BRIDGE: ROOT } } } };
+  process.stdout.write("Claude Desktop → Settings → Developer → Edit Config, add:\n" + JSON.stringify(cfg, null, 2) + "\n\nClaude Code:\n  claude mcp add workflow -e WF_BRIDGE=\"" + ROOT + "\" -- node \"" + __filename + "\"\n");
+}
+
+const verb = argv.find(a => !a.startsWith("--"));
+const HELP = `WorkFlow companion ${SERVER_INFO.version}
+
+  workflow-companion            run the MCP server (what Claude starts)
+  workflow-companion setup      sign this computer in to iCloud for WorkFlow (--name, --takeover, --no-browser)
+  workflow-companion status     which device answers, how fresh is the snapshot
+  workflow-companion keepalive  renew the sign-in (what the scheduled job runs)
+  workflow-companion signout    forget the sign-in on this computer
+  workflow-companion --print-config
+
+Needs WorkFlow 5.2+ on an iPhone, iPad or Mac, with the companion switched on in its Settings.
+`;
+
+if (argv.includes("--print-config")) printConfig();
+else if (argv.includes("--help") || verb === "help") process.stdout.write(HELP);
+else if (verb === "setup") setup().then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });
+else if (verb === "status") cloudStateText().then(t => console.log(t), e => { console.error(e.message || e); process.exitCode = 1; });
+else if (verb === "keepalive") keepAlive().then(c => { process.exitCode = c; });
+else if (verb === "signout") {
+  removeSchedule();
+  for (const f of Object.values(CP)) try { fs.unlinkSync(f); } catch (_) {}
+  console.log(`Signed out: removed the token, the settings and the keep-alive from ${COMPANION.home}.`);
+} else serve();