tryharness 0.7.6 → 0.7.8

package/lib/live.mjs

@@ -0,0 +1,205 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { readJson } from "./files.mjs";
+import { historyRoots } from "./paths.mjs";
+import { PS } from "./nudge.mjs";
+import { stepsOf } from "./runner.mjs";
+import { t3Link, t3Thread } from "./places.mjs";
+
+// The person's own coding sessions running on this computer right now, each with the app it runs in: a terminal, an
+// editor or T3 Code, found by walking up the session's process tree to the first process inside an app bundle. A
+// session in T3 Code also gets the link that opens its thread there (T3's own prompt links, t3code://threads/…).
+// Only Claude Code and Codex: their hooks (nudge.mjs) are how a message from Harness reaches a session. Where each
+// session runs, and how it opens there again, is places.mjs.
+
+export const LIVE_AGENTS = ["claude-code", "codex"];
+const PLAIN_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** Every process: its parent, its terminal (/dev/ttys003, or null) and its executable, by pid. */
+export function processTable() {
+  const table = new Map();
+  if (process.platform === "win32") return table;
+  const ps = spawnSync(PS, ["-axo", "pid=,ppid=,tty=,comm="], { encoding: "utf8", maxBuffer: 16 << 20 });
+  for (const line of (ps.stdout || "").split("\n")) {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+    if (match) table.set(Number(match[1]), { ppid: Number(match[2]), tty: /^ttys?\d+$/.test(match[3]) ? `/dev/${match[3]}` : null, comm: match[4] });
+  }
+  return table;
+}
+
+/** True when a process runs inside tmux: a tmux server is among its ancestors. */
+function underTmux(table, pid) {
+  for (let current = pid, steps = 0; current > 1 && steps < 64; steps++) {
+    const row = table.get(current);
+    if (!row) return false;
+    if (/^tmux\b/.test(path.basename(row.comm))) return true;
+    current = row.ppid;
+  }
+  return false;
+}
+
+const run = (command, args) => spawnSync(command, args, { encoding: "utf8", timeout: 3_000 });
+
+/** The tmux pane showing a terminal, and the terminal (app and tty) a tmux client shows it in. */
+export function tmuxPlace(table, tty) {
+  const panes = run("tmux", ["list-panes", "-a", "-F", "#{pane_tty}\t#{session_name}\t#{session_name}:#{window_index}.#{pane_index}"]);
+  const pane = (panes.stdout || "").split("\n").map((line) => line.split("\t")).find(([paneTty]) => paneTty === tty);
+  if (!pane) return null;
+  const clients = run("tmux", ["list-clients", "-t", pane[1], "-F", "#{client_tty}\t#{client_pid}"]);
+  const [clientTty, clientPid] = (clients.stdout || "").split("\n").filter(Boolean).map((line) => line.split("\t"))[0] ?? [];
+  return { target: pane[2], client: clientPid ? { tty: clientTty || null, host: hostApp(table, Number(clientPid)) } : null };
+}
+
+/** The app a process runs in: the outermost app bundle on its way up to launchd, or null (tmux, ssh, a service). */
+export function hostApp(table, pid) {
+  for (let current = pid, steps = 0; current > 1 && steps < 64; steps++) {
+    const row = table.get(current);
+    if (!row) return null;
+    const bundle = row.comm.match(/^(\/.*?\.app)\/Contents\//)?.[1];
+    if (bundle) return { name: path.basename(bundle, ".app"), app: bundle };
+    current = row.ppid;
+  }
+  return null;
+}
+
+export function workingDirectories(pids) {
+  const found = new Map();
+  if (!pids.length) return found;
+  const lsof = spawnSync("lsof", ["-a", "-d", "cwd", "-Fpn", "-p", pids.join(",")], { encoding: "utf8" });
+  let pid = null;
+  for (const line of (lsof.stdout || "").split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1));
+    else if (line.startsWith("n") && pid) found.set(pid, line.slice(1));
+  }
+  return found;
+}
+
+/** The session a running agent process has open: Claude Code's own record of it, or Codex's newest session in its folder. */
+export function sessionOfProcess(agent, pid, recent = []) {
+  if (!Number.isInteger(pid) || pid <= 1) return null;
+  if (agent === "claude-code") {
+    const record = readJson(path.join(historyRoots("claude-code")[0], "..", "sessions", `${pid}.json`), null);
+    return record && PLAIN_ID.test(String(record.sessionId || "")) ? record.sessionId : null;
+  }
+  if (agent !== "codex") return null;
+  const cwd = workingDirectories([pid]).get(pid);
+  const session = cwd ? recent.find((row) => row.agent === "codex" && row.cwd === cwd) : null;
+  return String(session?.session_id || "").match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i)?.[0] ?? null;
+}
+
+/**
+ * The live sessions, newest first. `exclude` holds the pids of runs Harness started itself; `recent` is the session
+ * index (Codex keeps no per-process record, so its session is the newest indexed one in the process's folder).
+ */
+export function liveSessions({ exclude = new Set(), recent = [], table = processTable() } = {}) {
+  const sessions = [];
+  const records = path.join(historyRoots("claude-code")[0], "..", "sessions");
+  let files = [];
+  try { files = fs.readdirSync(records).filter((name) => name.endsWith(".json")); } catch {}
+  for (const name of files) {
+    const record = readJson(path.join(records, name), null);
+    if (!record?.pid || !table.has(record.pid) || exclude.has(record.pid) || !PLAIN_ID.test(String(record.sessionId || ""))) continue;
+    if (record.kind && record.kind !== "interactive") continue;
+    sessions.push({ agent: "claude-code", sessionId: record.sessionId, folder: record.cwd || null, pid: record.pid, entrypoint: record.entrypoint || null,
+      busy: record.status === "busy" ? true : record.status === "idle" ? false : null, at: Number(record.statusUpdatedAt || record.startedAt || 0) });
+  }
+  // A Codex process outside any terminal and app is Codex's own background server (its terminals share it), not a session.
+  const codex = [...table].filter(([pid, row]) => path.basename(row.comm) === "codex" && !exclude.has(pid) && (row.tty || hostApp(table, pid))).map(([pid]) => pid);
+  const cwds = workingDirectories(codex);
+  for (const pid of codex) {
+    const session = recent.find((row) => row.agent === "codex" && row.cwd && row.cwd === cwds.get(pid));
+    const id = String(session?.session_id || "").replace(/\.jsonl$/, "").match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i)?.[0];
+    if (id && !sessions.some((row) => row.sessionId === id)) sessions.push({ agent: "codex", sessionId: id, folder: session.cwd, pid, busy: null, at: Date.parse(session.started_at) || 0 });
+  }
+  return sessions.sort((a, b) => b.at - a.at).map((session) => {
+    const tty = table.get(session.pid)?.tty ?? null;
+    // Inside tmux the app is the terminal a tmux client shows the pane in.
+    const tmux = underTmux(table, session.pid) && tty ? tmuxPlace(table, tty) : null;
+    const host = tmux?.client?.host ?? hostApp(table, session.pid);
+    const t3 = host && /^T3 Code\b/.test(host.name) ? t3Link(t3Thread(session.sessionId)) : null;
+    return { ...session, tty, tmux: tmux?.target ?? null, host, t3 };
+  });
+}
+
+/**
+ * A running terminal session brought to the front on its own pane: its tmux pane, WezTerm pane or kitty window selected
+ * here (by the ids it started with, else by its terminal device), then its app on its tab (the app does that step:
+ * src-tauri agents.rs focus_session, by the tty).
+ */
+export function focusTerminal(session, place = null, table = processTable()) {
+  let tty = session.tty;
+  const tmux = tty && (session.tmux || place?.tmux) ? tmuxPlace(table, tty) : null;
+  if (tmux) {
+    run("tmux", ["select-window", "-t", tmux.target]);
+    run("tmux", ["select-pane", "-t", tmux.target]);
+    tty = tmux.client?.tty ?? null;
+  }
+  if (place?.wezterm || (session.host && /^WezTerm$/i.test(session.host.name))) {
+    let pane = place?.wezterm ?? null;
+    if (!pane) try { pane = JSON.parse(run("wezterm", ["cli", "list", "--format", "json"]).stdout || "[]").find((entry) => entry.tty_name === session.tty)?.pane_id ?? null; } catch {}
+    if (pane != null) run("wezterm", ["cli", "activate-pane", "--pane-id", String(pane)]);
+  }
+  if (place?.kitty || (session.host && /^kitty$/i.test(session.host.name))) {
+    const to = place?.kitty?.socket ? ["--to", place.kitty.socket] : [];
+    run("kitty", ["@", ...to, "focus-window", "--match", place?.kitty ? `id:${place.kitty.id}` : `pid:${session.pid}`]);
+  }
+  return session.host ? { app: session.host.app, tty } : {};
+}
+
+const FEED_BYTES = 768 << 10;
+const promptText = (content) => typeof content === "string" ? content
+  : Array.isArray(content) ? content.filter((block) => ["text", "input_text"].includes(block?.type) && typeof block.text === "string").map((block) => block.text).join("\n") : "";
+// What the agent itself was handed (instructions, environment, hook output), not words the person typed.
+const machinery = (text) => !text.trim() || /^\s*<[a-z_-]+[\s>]/i.test(text) || text.startsWith("Caveat:");
+
+/** A session's own file: the index's source, else Claude Code's projects folder for its working folder. */
+export function sessionFile(agent, sessionId, folder, recent = []) {
+  const row = recent.find((entry) => entry.agent === agent && String(entry.session_id).includes(sessionId) && entry.source);
+  if (row && fs.existsSync(row.source)) return row.source;
+  if (agent === "claude-code" && folder && PLAIN_ID.test(sessionId)) {
+    const file = path.join(historyRoots("claude-code")[0], folder.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
+/**
+ * The end of a session as the person reads it, oldest first: what they asked ("you"), what the agent said ("say") and
+ * the tools it used ("do"). Read from the last part of the session's own file, so a long session costs no more.
+ */
+export function sessionFeed(agent, file, limit = 80) {
+  let text = "";
+  try {
+    const size = fs.statSync(file).size;
+    const handle = fs.openSync(file, "r");
+    const buffer = Buffer.alloc(Math.min(size, FEED_BYTES));
+    fs.readSync(handle, buffer, 0, buffer.length, size - buffer.length);
+    fs.closeSync(handle);
+    text = buffer.toString("utf8");
+    if (size > buffer.length) text = text.slice(text.indexOf("\n") + 1);
+  } catch { return []; }
+  const items = [];
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("{")) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    const at = row.timestamp || null;
+    if (agent === "claude-code") {
+      if (row.type === "user" && !row.isMeta) {
+        const said = promptText(row.message?.content);
+        if (!machinery(said)) items.push({ kind: "you", text: said.trim(), at });
+      } else if (row.type === "assistant") items.push(...stepsOf(row).map((step) => ({ ...step, at })));
+    } else if (agent === "codex" && row.type === "response_item") {
+      const item = row.payload || {};
+      if (item.type === "message" && item.role === "user") { const said = promptText(item.content); if (!machinery(said)) items.push({ kind: "you", text: said.trim(), at }); }
+      else if (item.type === "message" && item.role === "assistant") { const said = (item.content || []).map((block) => block?.text || "").join("\n").trim(); if (said) items.push({ kind: "say", text: said, at }); }
+      else if (item.type === "function_call" || item.type === "custom_tool_call") items.push({ kind: "do", text: `${item.name}: ${String(item.arguments ?? item.input ?? "").replace(/\s+/g, " ").slice(0, 200)}`, at });
+    } else if (agent === "pi" && row.type === "message" && row.message) {
+      if (row.message.role === "user") { const said = promptText(row.message.content); if (!machinery(said)) items.push({ kind: "you", text: said.trim(), at }); }
+      else if (row.message.role === "assistant") items.push(...stepsOf({ type: "message_end", message: row.message }).map((step) => ({ ...step, at })));
+    }
+  }
+  return items.slice(-limit);
+}

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,8 +91,8 @@ 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 to bring that agent in and wake it: @claude-code, @codex, @pi, @opencode, @grok-bot, @bankr, @quotient, @muse, or @harness to have the thread coordinated. To ask another agent for help, name it, say exactly what you need, then stop: you are woken again when someone answers you by name. 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",
@@ -103,11 +103,29 @@ const LOCAL_TOOLS = [
     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 }),
@@ -117,7 +135,7 @@ const BOARD_CALLS = {
   list_tasks: (args) => ({ command: "board.list", status: args.status, all: args.all === true }),
   get_task: (args) => ({ command: "board.get", id: String(args.id || "") }),
   post_task: (args) => ({ command: "board.post", objective: args.objective, brief: args.brief, targetAgent: args.target_agent, targetAgents: args.target_agents, parentId: args.parent_id, contextRefs: args.context_refs, runWorkspace: args.run_workspace, inSession: args.in_session === true, posterCwd: process.cwd(), posterPid: process.ppid }),
-  claim_task: (args) => ({ command: "board.claim", id: String(args.id || ""), expectedVersion: args.expected_version, leaseMinutes: args.lease_minutes }),
+  claim_task: (args) => ({ command: "board.claim", id: String(args.id || ""), expectedVersion: args.expected_version, leaseMinutes: args.lease_minutes, claimerPid: process.ppid }),
   report_task: (args) => args.status === "answered"
     ? { command: "board.answer", id: String(args.id || ""), answer: args.result, expectedVersion: args.expected_version }
     : args.status === "released"

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/nudge.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { daemonRequest } from "./control-client.mjs";
 import { paths } from "./paths.mjs";
+import { placeEnv } from "./places.mjs";
 
 // The session-start nudge: what an interactive agent is told when a session opens, so work
 // waiting on the board is not silent until someone asks. Claude Code runs this as a
@@ -68,16 +69,65 @@ export async function boardNudgeIfChanged(agent, homeDir = paths.home) {
 // its grandparent when the hook runs through a shell.
 export const PS = ["/bin/ps", "/usr/bin/ps"].find((file) => fs.existsSync(file)) || "ps";
 
-export async function notePrompt(agent) {
+function agentPids() {
   const pids = [process.ppid];
   try { const up = Number(spawnSync(PS, ["-o", "ppid=", "-p", String(process.ppid)], { encoding: "utf8" }).stdout.trim()); if (up > 1) pids.push(up); } catch {}
-  try { await daemonRequest({ command: "board.prompted", agent, pids }, 1_500); } catch {}
+  return pids;
+}
+
+// Where the session runs, as its own environment says (the agent's, which the hook shares): places.mjs reads it.
+const placeOf = (input) => ({ sessionId: input?.session_id, folder: input?.cwd || process.cwd(), env: placeEnv(process.env) });
+
+export async function notePrompt(agent, input = null) {
+  try { await daemonRequest({ command: "board.prompted", agent, pids: agentPids(), ...(input?.session_id ? placeOf(input) : {}) }, 1_500); } catch {}
+}
+
+/** A session starting says where it runs. */
+export async function notePlace(agent, input) {
+  if (!input?.session_id) return;
+  try { await daemonRequest({ command: "board.live.place", agent, pids: agentPids(), ...placeOf(input) }, 1_500); } catch {}
+}
+
+// What the person sent this session from Harness (daemon board.live.say), taken once.
+export async function takeMessages(agent, sessionId) {
+  if (!sessionId) return [];
+  try {
+    const response = await daemonRequest({ command: "board.live.take", agent, sessionId }, 1_500);
+    return response?.ok ? response.messages || [] : [];
+  } catch {
+    return [];
+  }
+}
+
+export function messagesText(messages) {
+  return messages.map((message) => `The person sent you this from Harness:\n\n${message.text}`).join("\n\n");
+}
+
+// The JSON the agent hands every hook on stdin (session_id among it); null when there is none.
+async function hookInput() {
+  if (process.stdin.isTTY) return null;
+  let text = "";
+  process.stdin.setEncoding("utf8");
+  const read = new Promise((resolve) => { process.stdin.on("data", (chunk) => { text += chunk; }); process.stdin.on("end", resolve); process.stdin.on("error", resolve); });
+  await Promise.race([read, new Promise((resolve) => setTimeout(resolve, 1_000).unref())]);
+  process.stdin.destroy();
+  try { return JSON.parse(text); } catch { return null; }
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
   const index = process.argv.indexOf("--agent");
   const agent = index >= 0 ? process.argv[index + 1] : "claude-code";
-  if (process.argv.includes("--if-changed")) await notePrompt(agent);
-  const text = process.argv.includes("--if-changed") ? await boardNudgeIfChanged(agent) : await boardNudge(agent);
-  if (text) process.stdout.write(text + "\n");
+  const input = await hookInput();
+  const sessionId = input?.session_id;
+  if (process.argv.includes("--stop")) {
+    // The Stop hook: a message waiting for this session keeps the agent going with it.
+    const messages = await takeMessages(agent, sessionId);
+    if (messages.length) process.stdout.write(JSON.stringify({ decision: "block", reason: messagesText(messages) }) + "\n");
+  } else {
+    if (process.argv.includes("--if-changed")) await notePrompt(agent, input);
+    else await notePlace(agent, input);
+    const messages = process.argv.includes("--if-changed") ? await takeMessages(agent, sessionId) : [];
+    const text = [messages.length ? messagesText(messages) : "", process.argv.includes("--if-changed") ? await boardNudgeIfChanged(agent) : await boardNudge(agent)].filter(Boolean).join("\n\n");
+    if (text) process.stdout.write(text + "\n");
+  }
 }

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/phones.mjs

@@ -13,17 +13,17 @@ 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.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"]);
+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.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.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([
@@ -34,7 +34,7 @@ const HARNESS_COMMANDS = new Set([
 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 }) {
+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();
@@ -96,6 +96,8 @@ export async function createPhoneDesk({ store, identityFile, boardCommand, reads
     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 }) };
@@ -131,6 +133,8 @@ export async function createPhoneDesk({ store, identityFile, boardCommand, reads
       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 } : {}) }));