tryharness 0.7.4 → 0.7.7

package/lib/mcp-stdio.mjs

@@ -13,7 +13,7 @@ let chain = Promise.resolve();
 const LOCAL_TOOLS = [
   {
     name: "list_tasks",
-    description: "List open work on this machine's Harness task board: tasks posted by the user or by other agents (Harness, Claude Code, Codex, Pi, OpenCode, Grok Bot) for this agent or for anyone. Tasks you posted for Bankr, Quotient or Muse live in Harness, not here: read one with get_task and its id. A task for a coding agent with a folder may run on its own (the user's standing permission or a goal); otherwise claim a task before working on it.",
+    description: "List open work on this machine's Harness task board: tasks posted by the user or by other agents (Harness, Claude Code, Codex, Pi, OpenCode, Grok Bot) for this agent or for anyone. Tasks you posted for Bankr, Quotient or Muse live in Harness, not here: read one with get_task and its id. A task for a coding agent with a folder may run on its own (the user's standing permission or a goal); otherwise claim a task before working on it. When work you asked for has finished, failed or come back with a question since your last call, it comes back under finished: read it with get_task and tell the user.",
     inputSchema: {
       type: "object",
       properties: { status: { type: "string", enum: ["open", "claimed", "needs_input", "done", "failed"] }, all: { type: "boolean", description: "include every task on the board, finished ones too" } },
@@ -33,7 +33,7 @@ const LOCAL_TOOLS = [
       properties: {
         objective: { type: "string", description: "one line, in the user's words" },
         brief: { type: "string" },
-        target_agent: { type: "string", description: "claude-code, codex, pi, opencode, grok-bot or harness on this machine; bankr, quotient or muse in Harness; omit for any agent" },
+        target_agent: { type: "string", description: "claude-code, codex, pi, opencode, grok-bot, openclaw, hermes or harness on this machine; bankr, quotient or muse in Harness; omit for any agent" },
         target_agents: { type: "array", items: { type: "string" }, description: "several agents at once: one task with a part for each, closed with every result when the last part finishes" },
         parent_id: { type: "string", description: "the board task this one continues" },
         run_workspace: { type: "string", description: "the absolute directory a coding agent runs this task in, non-interactively, once the user authorizes it; the run's result and session come back on the task. Left out, a task for a coding agent runs in the folder you are working in" },
@@ -91,20 +91,43 @@ const LOCAL_TOOLS = [
   },
   {
     name: "post_to_room",
-    description: "Post in a goal's room for the whole team: a finding, partial work, a question or what you did. Mention @agent (for example @codex, @claude, @harness) to wake that teammate. Post results and sources, not secrets: anything that looks like a key is held. For work someone else should do, post_task with parent_id set to the goal id.",
-    inputSchema: { type: "object", properties: { id: { type: "string", description: "the goal id" }, text: { type: "string" }, share_with_guests: { type: "boolean", description: "also send it to the goal's invited guests (other people's agents); only what is fine for them to see" } }, required: ["id", "text"], additionalProperties: false },
+    description: "Post in a goal's room for the whole team: a finding, partial work, a question or what you did. To ask another agent for help, put its name in ask (claude-code, codex, pi, opencode, grok-bot, openclaw, hermes, bankr, quotient, muse, or harness to have the thread coordinated), say exactly what you need, then stop: you are woken again when it answers you by name. When you answer someone who asked you, name them (@codex) and they are woken. Any other @name, like a thanks, wakes no one. Post results and sources, not secrets: anything that looks like a key is held. For work someone else should do, post_task with parent_id set to the goal id.",
+    inputSchema: { type: "object", properties: { id: { type: "string", description: "the goal id" }, text: { type: "string" }, ask: { type: "array", items: { type: "string" }, description: "the agents you are asking for something; each is woken" }, share_with_guests: { type: "boolean", description: "also send it to the goal's invited guests (other people's agents); only what is fine for them to see" } }, required: ["id", "text"], additionalProperties: false },
   },
   {
     name: "search_room",
     description: "Search a goal's room by meaning before starting work, so you build on what teammates already found instead of repeating it.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "the goal id" }, query: { type: "string" } }, required: ["id", "query"], additionalProperties: false },
+  },  {
+    name: "search_swarm",
+    description: "Search the shared memory of the user's agents: everything any agent wrote in any thread (findings, answers, questions, results) and the user's coding sessions on this computer. Use it before starting work to build on what another agent already did, and when you need to know how something was done before.",
+    inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"], additionalProperties: false },
+  },
+  {
+    name: "list_agents",
+    description: "The user's other agents you can ask, what each is for, and how each answers (some start at once, some are woken, some only pick work up later). Use it to pick a name before post_task or start_thread instead of guessing one.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "start_thread",
+    description: "Start a shared thread with one or more of the user's agents, named with @ in the message (for example \"@codex @grok-bot compare the two parsers\"). The thread carries your words, not the user's: nothing in it runs until the user starts it. Answers arrive in the thread; read it with read_room and add to it with post_to_room. Give a folder only when the work concerns one.",
+    inputSchema: { type: "object", properties: { text: { type: "string" }, folder: { type: "string", description: "absolute folder the coding agents work in; never guessed" } }, required: ["text"], additionalProperties: false },
+  },
+  {
+    name: "stop_thread",
+    description: "Stop the runs in a thread you started. The user can resume it.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
   },
 ];
 
 const BOARD_CALLS = {
+  list_agents: () => ({ command: "board.swarm.agents" }),
+  start_thread: (args) => ({ command: "board.swarm.start", text: args.text, folder: args.folder }),
+  stop_thread: (args) => ({ command: "board.swarm.stop", id: String(args.id || "") }),
   read_room: (args) => ({ command: "board.room.read", id: String(args.id || ""), since: args.since }),
-  post_to_room: (args) => ({ command: "board.room.post", id: String(args.id || ""), text: args.text, shareWithGuests: args.share_with_guests === true }),
+  post_to_room: (args) => ({ command: "board.room.post", id: String(args.id || ""), text: args.text, ask: Array.isArray(args.ask) ? args.ask : [], shareWithGuests: args.share_with_guests === true }),
   search_room: (args) => ({ command: "board.room.search", id: String(args.id || ""), query: args.query }),
+  search_swarm: (args) => ({ command: "board.swarm.search", query: args.query }),
   search_task_context: (args) => ({ command: "board.context.search", id: String(args.id || ""), query: args.query, limit: args.limit }),
   add_task_context: (args) => ({ command: "board.context.add", id: String(args.id || ""), kind: args.kind, text: args.text, source: args.source }),
   read_thread: (args) => ({ command: "board.thread.read", id: String(args.id || "") }),
@@ -126,7 +149,7 @@ async function localCall(request) {
   const name = request.params?.name;
   const args = request.params?.arguments || {};
   try {
-    const result = await daemonRequest({ ...BOARD_CALLS[name](args), agent }, ["search_task_context", "search_room"].includes(name) ? 20_000 : 5_000);
+    const result = await daemonRequest({ ...BOARD_CALLS[name](args), agent }, ["search_task_context", "search_room", "search_swarm"].includes(name) ? 20_000 : 5_000);
     return {
       jsonrpc: "2.0",
       id: request.id,

package/lib/members.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "members": [
+    { "id": "harness", "name": "Harness", "aliases": [], "road": "server", "home": "cloud", "runs": "server", "target": true, "wake": "run",
+      "about": "coordinates the thread and asks the person when only they can decide" },
+    { "id": "claude-code", "name": "Claude Code", "aliases": ["claude code"], "road": "local", "home": "machine", "runs": "machine", "target": true, "wake": "run",
+      "about": "reads and changes code in the thread's folder, runs commands and tests" },
+    { "id": "codex", "name": "Codex", "aliases": [], "road": "local", "home": "machine", "runs": "machine", "target": true, "wake": "run",
+      "about": "reads and changes code in the thread's folder, runs commands and tests" },
+    { "id": "pi", "name": "Pi", "aliases": [], "road": "local", "home": "machine", "runs": "machine", "target": true, "wake": "run",
+      "about": "reads and changes code in the thread's folder and runs commands" },
+    { "id": "opencode", "name": "OpenCode", "aliases": ["open code"], "road": "local", "home": "machine", "runs": "machine", "target": true, "wake": "run",
+      "about": "reads and changes code in the thread's folder and runs commands" },
+    { "id": "grok-bot", "name": "Grok Bot", "aliases": ["grok", "grok bot"], "road": "hosted", "home": "machine", "runs": "self", "target": true, "wake": "email",
+      "about": "research on X and the web" },
+    { "id": "bankr", "name": "Bankr", "aliases": [], "road": "server", "home": "cloud", "runs": "server", "target": true, "wake": "run",
+      "about": "the person's crypto wallet and trading, always under the person's own approval and limits" },
+    { "id": "quotient", "name": "Quotient", "aliases": [], "road": "server", "home": "cloud", "runs": "server", "target": true, "wake": "run",
+      "about": "prediction markets research and positions, under the person's own approval and limits" },
+    { "id": "muse", "name": "Muse", "aliases": [], "road": "hosted", "home": "cloud", "runs": "self", "target": true, "wake": "schedule",
+      "about": "writing and creative drafts" },
+    { "id": "openclaw", "name": "OpenClaw", "aliases": ["open claw"], "road": "local", "home": "machine", "runs": "self", "target": true, "wake": "local-webhook",
+      "about": "the person's own assistant on this computer, with their chat apps and tools" },
+    { "id": "hermes", "name": "Hermes", "aliases": [], "road": "local", "home": "machine", "runs": "self", "target": true, "wake": "local-webhook",
+      "about": "the person's own assistant on this computer, with their chat apps and tools" },
+    { "id": "claude-app", "name": "Claude app", "aliases": ["claude ai"], "road": "hosted", "home": "cloud", "runs": "self", "target": false, "wake": "none",
+      "about": "the Claude chat app; can ask, cannot be woken" },
+    { "id": "chatgpt", "name": "ChatGPT", "aliases": ["chat gpt"], "road": "hosted", "home": "cloud", "runs": "self", "target": false, "wake": "none",
+      "about": "the ChatGPT app; can ask, cannot be woken" }
+  ]
+}

package/lib/members.mjs

@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+
+// The swarm's members, one entry each (members.json): who they are, which road they call in on, where their tasks
+// live (home), who runs their work (runs), whether others may hand them work (target) and how they are told work is
+// waiting (wake). The server reads the same file (src/shared/members.ts). A caller on this machine names itself
+// (--agent) and is taken at its word: anything running as the person could read a token kept for it, so none is
+// kept (owner, October 10). A call through Harness is never taken for a member on this machine (hostedCaller).
+const ROSTER = JSON.parse(readFileSync(new URL("./members.json", import.meta.url), "utf8"));
+
+export const ROSTER_VERSION = ROSTER.version;
+export const MEMBERS = ROSTER.members;
+const byId = new Map(MEMBERS.map((entry) => [entry.id, entry]));
+
+export const member = (id) => byId.get(String(id)) ?? null;
+export const ids = (keep = () => true) => MEMBERS.filter(keep).map((entry) => entry.id);
+/** Members others may hand work to, Harness included. */
+export const TARGETS = ids((entry) => entry.target);
+/** Coding agents the daemon runs on this machine. */
+export const MACHINE_RUNNERS = ids((entry) => entry.runs === "machine");
+/** Targets whose tasks live on Harness's server, not the machine (Harness itself excluded). */
+export const CLOUD_HOMED = ids((entry) => entry.target && entry.home === "cloud" && entry.id !== "harness");
+/** Targets asked by a task rather than started here: they run themselves or on the server. */
+export const ASKED_BY_TASK = ids((entry) => entry.target && entry.runs !== "machine" && entry.id !== "harness");
+export const nameOf = (id) => member(id)?.name ?? String(id);
+export const aboutOf = (id) => {
+  const entry = member(id);
+  return entry ? `${entry.name}: ${entry.about}` : String(id);
+};
+
+const plain = (value) => String(value || "").trim().toLowerCase().replace(/^@/, "").replace(/[\s_]+/g, " ");
+/**
+ * A name as people and agents write it, resolved to one member: an id, a display name or an alias, else the one
+ * member whose name it starts. A start shared by several ("claude": Claude Code and the Claude app) comes back
+ * ambiguous with the candidates, so the caller asks its person or picks. `extra` admits board names the roster does
+ * not list (a connector named by its person), matched exactly.
+ */
+export function resolveMember(name, { extra = [] } = {}) {
+  const wanted = plain(name);
+  if (!wanted) return { ok: false, candidates: [] };
+  const exact = MEMBERS.find((entry) => entry.id === wanted || plain(entry.name) === wanted || entry.aliases.some((alias) => plain(alias) === wanted));
+  if (exact) return { ok: true, id: exact.id };
+  if (extra.map(String).includes(wanted)) return { ok: true, id: wanted };
+  const words = wanted.split(" ");
+  const candidates = MEMBERS.filter((entry) => [entry.id.replace(/-/g, " "), plain(entry.name), ...entry.aliases.map(plain)]
+    .some((label) => words.every((word, index) => label.split(" ")[index]?.startsWith(word)))).map((entry) => entry.id);
+  return candidates.length === 1 ? { ok: true, id: candidates[0] } : { ok: false, candidates };
+}

package/lib/onboard.mjs

@@ -0,0 +1,131 @@
+import { spawnSync } from "node:child_process";
+import readline from "node:readline";
+import { detectLocalAgents, setupHermes, setupOpenClaw, localWakes } from "./wakes.mjs";
+
+// "Your swarm" in setup: every agent class with how Harness reaches it, the recommended way already chosen, the steps
+// numbered, and a real test at the end that passes only when the agent claims and reports a task. Also reachable on its
+// own as `npx tryharness agents`. Without a terminal to answer in, it only says what is set up and how to finish.
+
+const SETUP = { openclaw: setupOpenClaw, hermes: setupHermes };
+const LABEL = { openclaw: "OpenClaw", hermes: "Hermes", "grok-bot": "Grok Bot" };
+const MEASURED = "measured on a real Grok: about 23s by email, 17s by webhook";
+
+export function createPrompter({ input = process.stdin, output = process.stdout } = {}) {
+  const ask = (question, { hidden = false } = {}) => new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output, terminal: true });
+    if (hidden) rl._writeToOutput = (text) => { if (text.includes(question)) output.write(text); };
+    rl.question(question, (answer) => { rl.close(); if (hidden) output.write("\n"); resolve(answer.trim()); });
+  });
+  return { ask };
+}
+
+const copy = (text) => {
+  const tool = process.platform === "darwin" ? "pbcopy" : process.platform === "win32" ? "clip" : "xclip";
+  const result = spawnSync(tool, tool === "xclip" ? ["-selection", "clipboard"] : [], { input: text });
+  return result.status === 0;
+};
+
+/** Post a setup check for the agent and wait for its report: the same path real work takes. */
+export async function testAgent({ agent, daemonRequest, out = console.log, waitMs = 10 * 60_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  const posted = await daemonRequest({ command: "board.post", agent: "user", objective: "Setup check from Harness: reply ready", brief: "Harness is checking that it can wake you. Claim this task and report it done with the single word: ready. Do nothing else.", targetAgent: agent });
+  if (!posted?.ok) { out(`    ! the test task could not be posted: ${posted?.error || "no answer"}`); return false; }
+  const started = Date.now();
+  out(`    Test sent. Waiting for ${LABEL[agent] || agent} to answer (Ctrl-C stops waiting; the test task stays on your board).`);
+  while (Date.now() - started < waitMs) {
+    await sleep(2_000);
+    const task = (await daemonRequest({ command: "board.get", agent: "user", id: posted.task.id }).catch(() => null))?.task;
+    if (task?.status === "done") { out(`    ✓ ${LABEL[agent] || agent} answered in ${Math.round((Date.now() - started) / 1000)}s. Ready.`); return true; }
+    if (task && ["failed", "needs_input"].includes(task.status)) { out(`    ! ${LABEL[agent] || agent} answered but the task is ${task.status}: ${task.result || ""}`); return false; }
+  }
+  out(`    ! No answer after ${Math.round(waitMs / 60_000)} minutes. Check that the agent is running, then: npx tryharness agents test ${agent}`);
+  return false;
+}
+
+async function setupLocal({ entry, runtimeRoot, prompter, daemonRequest, out }) {
+  const name = LABEL[entry.agent];
+  if (localWakes()[entry.agent]) {
+    const health = (await daemonRequest({ command: "wake.local" }).catch(() => null))?.agents?.[entry.agent];
+    if (!health || health.answering) { out(`  ✓ ${name}: woken on this computer by its own webhook`); return; }
+    out(`  ! ${name}: not answering wakes (${health.lastFailure}). Check that it is running.`);
+    if (!prompter || /^n/i.test(await prompter.ask(`    Set ${name} up again? [Y/n] `))) { out(`    Later: npx tryharness agents setup ${entry.agent}`); return; }
+    const result = SETUP[entry.agent]({ runtimeRoot });
+    out(`    ${result.ok ? "✓" : "!"} ${result.detail}`);
+    if (result.ok) await testAgent({ agent: entry.agent, daemonRequest, out });
+    return;
+  }
+  if (!prompter) { out(`  ! ${name}: found. Set it up with: npx tryharness agents setup ${entry.agent}`); return; }
+  out(`  ${name} found. Harness wakes it with a webhook on this computer (recommended, nothing to copy).`);
+  out(`    This adds Harness to ${name}'s MCP servers and turns on its webhook with a key made here${entry.agent === "openclaw" ? ", then restarts its gateway" : ""}.`);
+  if (/^n/i.test(await prompter.ask(`    Set up ${name} now? [Y/n] `))) { out(`    Skipped. Later: npx tryharness agents setup ${entry.agent}`); return; }
+  const result = SETUP[entry.agent]({ runtimeRoot });
+  out(`    ${result.ok ? "✓" : "!"} ${result.detail}`);
+  if (result.ok) await testAgent({ agent: entry.agent, daemonRequest, out });
+}
+
+async function setupGrok({ prompter, daemonRequest, out, clipboard }) {
+  const listed = await daemonRequest({ command: "wake.server", input: { action: "list" } }).catch((error) => ({ ok: false, error: error.message }));
+  if (!listed.ok) { out(`  ! Grok Bot: Harness could not be reached (${listed.error}). Later: npx tryharness agents setup grok-bot`); return; }
+  const current = (listed.wakes || []).find((wake) => wake.agent === "grok-bot");
+  if (current) {
+    const how = current.channel === "email" ? `email at ${current.address}` : "its webhook";
+    if (current.answering) { out(`  ✓ Grok Bot: woken by ${how}`); return; }
+    out(`  ! Grok Bot: not answering wakes by ${how} (${current.last_failure}).`);
+    if (!prompter || /^n/i.test(await prompter.ask("    Set it up again? [Y/n] "))) { out("    Later: npx tryharness agents setup grok-bot"); return; }
+  }
+  if (!prompter) { out("  Grok Bot: not set up. Set it up with: npx tryharness agents setup grok-bot"); return; }
+  out(`  Grok Bot. How should Harness wake it? (${MEASURED})`);
+  out("    1) Email     nothing to copy back                          (recommended)");
+  out("    2) Webhook   a little faster; you paste its URL and key here");
+  out("    3) Not now");
+  const choice = (await prompter.ask("    Choose [1]: ")) || "1";
+  if (choice === "3") { out("    Skipped. Later: npx tryharness agents setup grok-bot"); return; }
+  const channel = choice === "2" ? "webhook" : "email";
+  const message = listed.messages?.["grok-bot"]?.[channel];
+  if (!message) { out("    ! Harness did not send the setup message; update tryharness and try again."); return; }
+  const copied = clipboard(message);
+  out(`    1. ${copied ? "This message is on your clipboard. Paste it into Grok:" : "Paste this message into Grok:"}`);
+  out(message.split("\n").map((line) => `       ${line}`).join("\n"));
+  out("    2. Grok opens Harness's approval page. Name the connection Grok Bot and approve.");
+  if (channel === "webhook") {
+    out("    3. In Grok, open Routines, then Harness wake, and copy its webhook URL and key.");
+    const address = await prompter.ask("       Webhook URL: ");
+    const key = await prompter.ask("       Key (hidden): ", { hidden: true });
+    const saved = await daemonRequest({ command: "wake.server", input: { action: "save", agent: "grok-bot", channel: "webhook", address, key } });
+    if (!saved.ok) { out(`    ! ${saved.error}. Try again: npx tryharness agents setup grok-bot`); return; }
+    out("    ✓ Saved. The key is stored sealed on Harness and is never shown again.");
+  } else {
+    out("    3. Grok registers its own address with Harness. Waiting for it (Ctrl-C stops waiting)...");
+    const registered = await waitFor(async () => ((await daemonRequest({ command: "wake.server", input: { action: "list" } }).catch(() => null))?.wakes || []).some((wake) => wake.agent === "grok-bot"));
+    if (!registered) { out("    Not registered yet. When Grok has done it: npx tryharness agents test grok-bot"); return; }
+    out("    ✓ Grok registered its address.");
+  }
+  await testAgent({ agent: "grok-bot", daemonRequest, out });
+}
+
+async function waitFor(check, waitMs = 10 * 60_000, everyMs = 3_000) {
+  const end = Date.now() + waitMs;
+  while (Date.now() < end) {
+    if (await check()) return true;
+    await new Promise((r) => setTimeout(r, everyMs));
+  }
+  return false;
+}
+
+/** The whole "Your swarm" step. `only` limits it to one agent (npx tryharness agents setup <agent>). */
+export async function setupSwarm({ runtimeRoot, states = [], daemonRequest, prompter = process.stdin.isTTY ? createPrompter() : null, out = console.log, only = null, clipboard = copy }) {
+  const want = (agent) => !only || only === agent;
+  out("\nYour swarm");
+  if (!only) {
+    out("  On this computer: Harness starts them when work is posted");
+    for (const state of states) out(`    ${!state.installed ? "–" : state.configured ? "✓" : "!"} ${state.agent}: ${state.detail}`);
+  }
+  const local = detectLocalAgents().filter((entry) => entry.found && want(entry.agent));
+  if (local.length) out("  Agent apps on this computer: woken by a webhook Harness sets up");
+  for (const entry of local) await setupLocal({ entry, runtimeRoot, prompter, daemonRequest, out });
+  if (only && LABEL[only] && only !== "grok-bot" && !local.length) out(`  ${LABEL[only]} was not found on this computer.`);
+  if (want("grok-bot")) {
+    out("  Cloud agents: woken by email or webhook");
+    await setupGrok({ prompter, daemonRequest, out, clipboard });
+  }
+  if (!only) out("  Built in: Bankr and Quotient run on Harness, nothing to set up");
+}

package/lib/paths.mjs

@@ -14,6 +14,7 @@ export const paths = {
   status: path.join(harnessHome, "daemon-status.json"),
   socket: process.platform === "win32" ? "\\\\.\\pipe\\tryharness-daemon" : path.join(harnessHome, "daemon.sock"),
   log: path.join(harnessHome, "daemon.log"),
+  phoneIdentity: path.join(harnessHome, "phone-identity.json"),
   runs: path.join(harnessHome, "runs"),
   runtime: path.join(harnessHome, "runtime"),
   models: path.join(harnessHome, "models"),

package/lib/phones.mjs

@@ -0,0 +1,152 @@
+import os from "node:os";
+import { randomBytes } from "node:crypto";
+import { b64u, channelKey, constantTimeEqual, loadOrCreateIdentity, MAX_SKEW_MS, open, pairProof, seal } from "./sealed.mjs";
+
+// The daemon's side of the person's own devices: pairing offers made on this machine (a QR code
+// for a phone, a link opened in a browser), and sealed calls from paired devices, opened here and
+// answered here. Harness only carries the envelopes.
+// A phone acts as the person ("user") within PHONE_COMMANDS. A browser is the Harness window on a
+// desk: it acts as the person or as Harness (the chat owner), within BROWSER_COMMANDS, and reads
+// the coding sessions and run records Harness used to read in the clear.
+
+const OFFER_TTL_MS = 10 * 60_000;
+const MAX_OFFERS = 5;
+// A message queued at Harness while this computer slept may arrive up to 7 days late; only decisions and posts may.
+const QUEUED_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const QUEUEABLE = new Set(["board.post", "board.run", "board.release", "board.answer", "board.remove", "board.thread.post", "board.thread.send", "board.thread.discard", "board.thread.end", "board.goal.stop",
+  "board.swarm.start", "board.swarm.post", "board.swarm.stop", "board.swarm.stop_all", "board.swarm.resume", "board.swarm.start_run"]);
+const ID = /^[A-Za-z0-9_-]{8,64}$/;
+const KEY = /^[A-Za-z0-9_-]{80,100}$/;
+const KINDS = new Set(["phone", "browser"]);
+const PHONE_COMMANDS = new Set([
+  "board.list", "board.get", "board.children", "board.agents", "board.post", "board.run", "board.release", "board.answer", "board.remove",
+  "board.thread.read", "board.thread.post", "board.thread.send", "board.thread.discard", "board.thread.auto", "board.thread.end",
+  "board.goal.list", "board.goal.get", "board.goal.stop", "board.room.read",
+  "board.swarm.list", "board.swarm.read", "board.swarm.start", "board.swarm.post", "board.swarm.stop", "board.swarm.stop_all", "board.swarm.resume", "board.swarm.folder", "board.swarm.coordinator",
+  "board.swarm.diff", "board.swarm.merge", "board.swarm.discard", "board.swarm.start_run",
+]);
+// What the chat owner does on the board, in Harness's name (was src/server/mcp/board.ts HARNESS_COMMANDS).
+const HARNESS_COMMANDS = new Set([
+  "board.list", "board.get", "board.post", "board.claim", "board.report", "board.answer", "board.thread.read", "board.thread.post", "board.standing.check",
+  "board.goal.create", "board.goal.get", "board.goal.list", "board.goal.finish", "board.room.read", "board.room.post", "board.room.search", "board.children", "board.agents",
+  "board.swarm.list", "board.swarm.read", "board.swarm.diff",
+]);
+const BROWSER_PERSON_COMMANDS = new Set([...PHONE_COMMANDS, "board.goal.resume", "board.standing", "board.standing.check", "board.standing.off"]);
+const BROWSER_READS = new Set(["sessions.search", "sessions.read", "sessions.raw", "tasks.status", "relay.request", "relay.open"]);
+
+export async function createPhoneDesk({ store, identityFile, boardCommand, reads = {}, version, onMessage = () => {}, machine = () => null }) {
+  const identity = await loadOrCreateIdentity(identityFile);
+  const offers = new Map();
+  const keys = new Map();
+  const hostname = os.hostname().slice(0, 64);
+
+  const sweep = () => {
+    const now = Date.now();
+    for (const [id, offer] of offers) if (offer.expiresAt < now) offers.delete(id);
+  };
+  const keyFor = async (device) => {
+    if (!keys.has(device.id)) keys.set(device.id, await channelKey(identity.privateKey, device.public_key, device.id));
+    return keys.get(device.id);
+  };
+
+  // What the QR code or link carries. The secret and the daemon's key never pass through Harness.
+  // The kind is fixed here, on the machine: a page cannot turn a phone's code into a browser's.
+  const offer = (origin, kind = "phone") => {
+    if (!KINDS.has(kind)) throw new Error(`unknown device kind ${kind}`);
+    sweep();
+    if (offers.size >= MAX_OFFERS) offers.delete(offers.keys().next().value);
+    const offerId = b64u(randomBytes(16));
+    const secret = b64u(randomBytes(32));
+    offers.set(offerId, { secret, kind, expiresAt: Date.now() + OFFER_TTL_MS });
+    const fragment = new URLSearchParams({ v: "1", o: offerId, s: secret, k: identity.publicKey, h: hostname });
+    const page = kind === "browser" ? "/link" : "/m/pair";
+    return { offerId, kind, expiresInSeconds: OFFER_TTL_MS / 1000, url: `${String(origin).replace(/\/$/, "")}${page}#${fragment}` };
+  };
+
+  const pair = async (input) => {
+    sweep();
+    const { offerId, deviceId, devicePublicKey, proof, requestId } = input;
+    if (![offerId, deviceId, requestId].every((value) => ID.test(String(value))) || !KEY.test(String(devicePublicKey))) return { ok: false, error: "invalid pairing request" };
+    const pending = offers.get(String(offerId));
+    // One attempt per code, right or wrong: a guessed proof burns the code.
+    offers.delete(String(offerId));
+    if (!pending) return { ok: false, error: "this pairing code expired or was already used; make a new one on the computer" };
+    if (!constantTimeEqual(proof, await pairProof(pending.secret, offerId, devicePublicKey, identity.publicKey))) return { ok: false, error: "the pairing proof did not match" };
+    if (store.getPhone(String(deviceId))) return { ok: false, error: "this device is already paired" };
+    const fallback = pending.kind === "browser" ? "Browser" : "Phone";
+    const label = String(input.label || fallback).replace(/[^\p{L}\p{N} ._'-]/gu, "").slice(0, 40) || fallback;
+    const device = store.addPhone({ id: String(deviceId), label, publicKey: String(devicePublicKey), kind: pending.kind });
+    return { ok: true, envelope: await seal(await keyFor(device), "d2p", device.id, String(requestId), { paired: true, hostname, label, kind: device.kind, version }) };
+  };
+
+  const call = async (envelope) => {
+    sweep();
+    if (!envelope || envelope.v !== 1 || !ID.test(String(envelope.deviceId)) || !ID.test(String(envelope.requestId)) || typeof envelope.iv !== "string" || typeof envelope.ct !== "string") {
+      return { ok: false, error: "invalid envelope" };
+    }
+    const device = store.getPhone(envelope.deviceId);
+    if (!device) return { ok: false, error: "unknown device", code: "unpaired" };
+    if (device.revoked_at) return { ok: false, error: "this device was disconnected from the computer", code: "revoked" };
+    const key = await keyFor(device);
+    let request;
+    try { request = await open(key, "p2d", envelope); } catch { return { ok: false, error: "the message could not be opened", code: "unreadable" }; }
+    const queued = request?.queued === true;
+    if (queued && !QUEUEABLE.has(String(request?.call?.command || ""))) return { ok: false, error: "only posts and decisions wait for the computer", code: "refused" };
+    const age = typeof request?.ts === "number" ? Date.now() - request.ts : Infinity;
+    if (queued ? age > QUEUED_MAX_AGE_MS || age < -MAX_SKEW_MS : Math.abs(age) > MAX_SKEW_MS) return { ok: false, error: "the message is too old or the device's clock is off", code: "stale" };
+    if (!store.firstPhoneRequest(device.id, String(envelope.requestId))) return { ok: false, error: "this message was already received", code: "replayed" };
+    store.touchPhone(device.id);
+    // Any message from a paired device keeps a Mac in Standby awake for the next hour (Lid-Closed Mode).
+    onMessage();
+    if (request.call?.command === "phone.forget") {
+      const forgotten = revoke(device.id);
+      return { ok: true, envelope: await seal(key, "d2p", device.id, envelope.requestId, { ok: forgotten.ok }) };
+    }
+    const result = await answer(request.call, device);
+    return { ok: true, envelope: await seal(key, "d2p", device.id, envelope.requestId, result) };
+  };
+
+  const settled = async (run) => {
+    try {
+      const result = run();
+      return result?.pending ? { ok: true, ...(await result.pending) } : result;
+    } catch (error) {
+      return { ok: false, error: `the board could not answer: ${error.message}` };
+    }
+  };
+
+  const answer = async (callInput, device) => {
+    const command = String(callInput?.command || "");
+    if (command === "phone.hello") return { ok: true, hostname, version, kind: device.kind };
+    if (device.kind === "browser") {
+      if (BROWSER_READS.has(command)) {
+        const read = reads[command];
+        if (!read) return { ok: false, error: `this computer cannot answer ${command}` };
+        try { return { ok: true, result: await read(callInput) }; } catch (error) { return { ok: false, error: error.message }; }
+      }
+      // The browser says whose call it is: the person's own action, or the chat owner's tool call.
+      const as = callInput.as === "harness" ? "harness" : "user";
+      if (!(as === "harness" ? HARNESS_COMMANDS : BROWSER_PERSON_COMMANDS).has(command)) return { ok: false, error: `a browser cannot call ${command || "that"} as ${as}` };
+      // Words another agent wrote that drove Harness's call ride as a taint the board keeps.
+      const writtenBy = Array.isArray(callInput.writtenBy) ? callInput.writtenBy.map(String).slice(0, 16) : [];
+      if (as === "harness" && command === "board.goal.create" && writtenBy.length) return { ok: false, error: "a goal is set only in a turn the owner started" };
+      const { as: _as, writtenBy: _written, provenance: _provenance, ...rest } = callInput;
+      return settled(() => boardCommand({ ...rest, command, agent: as, ...(writtenBy.length ? { provenance: { trust: "agent", chain: writtenBy } } : {}) }));
+    }
+    // Lid-Closed Mode's wake: no arguments, never queued, and it can only keep the Mac awake and say how it is.
+    if (command === "machine.wake") return { ok: true, machine: machine() };
+    if (!PHONE_COMMANDS.has(command)) return { ok: false, error: `a phone cannot call ${command || "that"}` };
+    // The phone is the person; whatever it names itself, it acts as "user".
+    return settled(() => boardCommand({ ...callInput, command, agent: "user", ...(command === "board.list" && callInput.all === undefined ? { all: true } : {}) }));
+  };
+
+  // Harness's bridge message: a pairing or a sealed call. Everything returned is safe to pass through Harness.
+  const handle = async (input) => (input?.kind === "pair" ? pair(input) : input?.kind === "call" ? call(input.envelope) : { ok: false, error: "unknown sealed request" });
+
+  const revoke = (id) => {
+    keys.delete(String(id));
+    return store.revokePhone(String(id));
+  };
+
+  return { offer, handle, revoke, list: () => store.phones(), publicKey: identity.publicKey, identity };
+}