tryharness 0.4.2 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # tryharness
 
-Connect the coding agents installed on this machine to [Harness](https://tryharness.ai):
+Harness Relay: turn the coding agents installed on this machine into your personal swarm with [Harness](https://tryharness.ai):
 
 ```sh
 npx tryharness
@@ -10,8 +10,9 @@ Supports the Node.js 18, 20, 22, and 24 release lines.
 
 That one command pairs the machine, detects Claude Code, Codex, pi, and opencode,
 configures every installed agent, installs the Harness daemon as a user-level login
-service, validates readiness, and starts indexing existing coding sessions locally in
-SQLite. Setup returns as soon as the daemon is ready; indexing continues in the
+service (launchd on macOS, a systemd user service on Linux, a Task Scheduler logon task
+on Windows; all without elevation), validates readiness, and starts indexing existing
+coding sessions locally in SQLite. Setup returns as soon as the daemon is ready; indexing continues in the
 background and does not require an open Harness tab.
 
 JSONL histories are streamed from beginning to end and only normalized conversation
@@ -29,7 +30,8 @@ npx tryharness doctor
 npx tryharness sync --agent codex
 npx tryharness task <run-id> --follow
 npx tryharness logs --follow
-npx tryharness handoff codex --file ./implementation-brief.md
+npx tryharness board
+npx tryharness board post --for claude-code --objective "Port the parser" --file ./brief.md
 npx tryharness disconnect
 ```
 
@@ -38,7 +40,7 @@ daemon, the bridge, the database, and agent discovery. `sync` requests a backgro
 rescan; it is diagnostic, not part of normal setup.
 
 Delegated coding tasks start only after the user presses Start on Harness's proposal
-card. They then run non-interactively with each agent's full-authority/auto-approve mode
+card, which posts the task on the machine's board under the run id. They then run non-interactively with each agent's full-authority/auto-approve mode
 inside the exact absolute working directory shown on that card; Harness never falls
 back to the user's home directory. The card immediately shows a
 `npx tryharness task <run-id> --follow` command for watching the machine-local raw output
@@ -47,10 +49,63 @@ command as soon as the agent reports its session id, including while the run is
 so the user can enter and steer the agent directly rather than interacting through a
 Harness wrapper.
 
+## Embedder
+
+Setup also downloads the embedding model the daemon uses for a task's context space,
+about 110 MB into `~/.harness/models`, reported like indexing is. It is the same model,
+quantization, pooling and normalization as Harness in the browser (bge-base, q8, CLS,
+L2), under the same version key, run on the wasm build of the ONNX runtime with no native
+addon, so a vector the daemon makes and one the browser makes describe the same space. The
+daemon never asks a browser tab to embed; until the model is present, context search
+answers from full-text search and says so.
+
+## Task board
+
+The daemon keeps a task board in its local SQLite database. Any connected agent can post
+work for another agent on the machine through the `post_task` tool, and every agent sees
+the board through `list_tasks`, `get_task`, `claim_task` and `report_task`, which the
+stdio MCP exposes. The board is pull-only: a task waits until
+its target agent reads the board and claims it, and nothing starts by itself. A claimer
+reports done, failed or needs_input; the poster answers a question with `report_task`
+and status `answered`, which returns the task to the claimer with the answer in its
+brief. The daemon is also the board's worker. A task posted for a coding agent installed on the
+machine with `--run --workspace <dir>` (or an agent's `run_workspace` request, once the user
+authorizes it with `tryharness board run <id>`) is claimed by the daemon in that agent's name,
+run non-interactively through the same runner as a delegated run, and reported back on the
+task with the result and the agent's session id; `tryharness task <id> --follow` works on it.
+One run per agent at a time; a daemon restart marks a running task unknown. An interactive
+claim carries a lease (default 60 minutes); a lapsed lease shows the claim as stale and only
+the poster or the user releases it. `tryharness board agents` shows when each agent last read
+the board. Every change goes up the bridge as identity and status only.
+
+Interactive sessions are told about waiting work when they open and when it changes. Setup adds
+SessionStart and UserPromptSubmit hooks for Claude Code (`~/.claude/settings.json`) and for Codex
+(`~/.codex/hooks.json`; Codex asks once to trust them with `/hooks`), the Pi extension puts the
+queue into pi's system prompt and speaks again after a turn when it changed, and the OpenCode
+plugin adds it to a message when it changed. Every MCP client also gets the queue in the
+connection handshake. The nudge is silent when nothing waits or no daemon is running.
+
+Every task has one holder, the only agent allowed to write it next, and a version that
+every write bumps; a write lands only for the holder at the expected version, and anything
+else comes back as a conflict carrying the task as it is now, so agents cannot overwrite
+each other. Briefs and results stay on the machine; the bridge reports identity and status
+only. Any MCP client on the machine joins the board by launching `lib/mcp-stdio.mjs --agent <name>`.
+
+Work stays where the agent lives. Bankr, Quotient and Muse live in Harness, not on any machine,
+so a task posted for one of them (`tryharness board post --for bankr`, or `post_task` from any
+agent here) goes up the bridge and waits on the server, where Bankr takes it under the limits
+the user set in Harness and Quotient answers it with one search over its tracked markets; the
+daemon must be connected to post it, and `get_task` (or `tryharness board show <id>`) with its
+id reads it back. A task for a coding agent or Grok Bot waits here. A task for several agents
+at once is for agents in one place.
+Grok Bot keeps its MCP servers in its own account settings, so setup prints
+`npx tryharness mcp grok-bot`, a one-server snippet to paste into Grok Bot's MCP settings; it
+then appears on the board as `grok-bot`.
+
 The daemon dials out to Harness over one authenticated WebSocket. Its local control
 socket is permissioned to the current user. When OpenCode is installed, the daemon also
 starts OpenCode's own helper on a random loopback-only port with a random per-process
 password so it can index OpenCode history; no fixed or unauthenticated port is used.
 Connection tokens stay in `~/.harness/config.json` with owner-only permissions. Coding
-history and handoffs stay in the local SQLite database unless an explicit operation
+history and the board stay in the local SQLite database unless an explicit operation
 sends content through Harness.

package/assets/opencode-plugin.js

@@ -8,6 +8,42 @@ const socketPath = process.platform === "win32"
   ? "\\\\.\\pipe\\tryharness-daemon"
   : path.join(os.homedir(), ".harness", "daemon.sock");
 
+function ask(message) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let socket;
+    try { socket = net.createConnection(socketPath); } catch { resolve(null); return; }
+    socket.setEncoding("utf8");
+    socket.setTimeout(1_500);
+    socket.on("connect", () => socket.write(JSON.stringify(message) + "\n"));
+    socket.on("data", (chunk) => { buffer += chunk; if (buffer.includes("\n")) { socket.destroy(); try { resolve(JSON.parse(buffer.split("\n")[0])); } catch { resolve(null); } } });
+    socket.on("timeout", () => { socket.destroy(); resolve(null); });
+    socket.on("error", () => resolve(null));
+  });
+}
+
+// What opencode is told once per session, on its first message: work waiting on the board.
+async function boardNudge(sessionId) {
+  const response = await ask({ command: "board.list", agent: "opencode" });
+  const tasks = response?.ok ? response.tasks : [];
+  const now = digest(tasks);
+  if (lastDigest.get(sessionId) === now) return "";
+  lastDigest.set(sessionId, now);
+  const waiting = tasks.filter((task) => task.status === "open" && (!task.target_agent || task.target_agent === "opencode"));
+  const held = tasks.filter((task) => task.claimed_by === "opencode" && (task.status === "claimed" || task.status === "needs_input"));
+  if (!waiting.length && !held.length) return "";
+  const line = (task) => `- ${task.id}: ${task.objective}${task.origin_agent ? ` (from ${task.origin_agent}${task.trust === "agent" ? ", agent-written" : ""})` : ""}`;
+  return ["Harness task board:", ...(waiting.length ? [`${waiting.length} task${waiting.length === 1 ? "" : "s"} waiting for you:`, ...waiting.slice(0, 5).map(line)] : []),
+    ...(held.length ? [`${held.length} you already claimed:`, ...held.slice(0, 5).map(line)] : []),
+    "Read one with get_task, claim it with claim_task before working, and report_task when done or stuck."].join("\n");
+}
+// One digest per session: the nudge is added again only when the queue changed.
+const lastDigest = new Map();
+function digest(tasks) {
+  return tasks.filter((task) => (task.status === "open" && (!task.target_agent || task.target_agent === "opencode")) || (task.claimed_by === "opencode" && ["claimed", "needs_input"].includes(task.status)))
+    .map((task) => `${task.id}:${task.status}:${task.version}`).sort().join("|");
+}
+
 function notify(message) {
   try {
     const socket = net.createConnection(socketPath);
@@ -19,6 +55,13 @@ function notify(message) {
 }
 
 export const TryHarnessPlugin = async ({ directory }) => ({
+  // Every message of a session carries the board nudge as an extra text part when the queue changed since the last one.
+  "chat.message": async (input, output) => {
+    const sessionId = input?.sessionID || input?.sessionId;
+    if (!sessionId || !Array.isArray(output?.parts)) return;
+    const nudge = await boardNudge(sessionId);
+    if (nudge) output.parts.push({ type: "text", text: nudge });
+  },
   event: async ({ event }) => {
     if (event?.type !== "session.idle") return;
     const sessionId = event?.properties?.sessionID || event?.properties?.sessionId;

package/assets/pi-extension.ts

@@ -5,7 +5,46 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import net from "node:net";
+
 const CONFIG_PATH = path.join(os.homedir(), ".harness", "config.json");
+const SOCKET_PATH = process.platform === "win32" ? "\\\\.\\pipe\\tryharness-daemon" : path.join(os.homedir(), ".harness", "daemon.sock");
+
+// One request to the local daemon; nothing waiting, or no daemon, is an empty answer.
+function daemon(message) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let socket;
+    try { socket = net.createConnection(SOCKET_PATH); } catch { resolve(null); return; }
+    socket.setEncoding("utf8");
+    socket.setTimeout(1_500);
+    socket.on("connect", () => socket.write(JSON.stringify(message) + "\n"));
+    socket.on("data", (chunk) => { buffer += chunk; if (buffer.includes("\n")) { socket.destroy(); try { resolve(JSON.parse(buffer.split("\n")[0])); } catch { resolve(null); } } });
+    socket.on("timeout", () => { socket.destroy(); resolve(null); });
+    socket.on("error", () => resolve(null));
+  });
+}
+
+// What pi is told when a session opens, and again after a turn when the queue changed.
+let lastDigest = null;
+function digest(tasks) {
+  return tasks.filter((task) => (task.status === "open" && (!task.target_agent || task.target_agent === "pi")) || (task.claimed_by === "pi" && ["claimed", "needs_input"].includes(task.status)))
+    .map((task) => `${task.id}:${task.status}:${task.version}`).sort().join("|");
+}
+async function boardNudge(onlyIfChanged = false) {
+  const response = await daemon({ command: "board.list", agent: "pi" });
+  const tasks = response?.ok ? response.tasks : [];
+  const now = digest(tasks);
+  if (onlyIfChanged && now === lastDigest) return "";
+  lastDigest = now;
+  const waiting = tasks.filter((task) => task.status === "open" && (!task.target_agent || task.target_agent === "pi"));
+  const held = tasks.filter((task) => task.claimed_by === "pi" && (task.status === "claimed" || task.status === "needs_input"));
+  if (!waiting.length && !held.length) return "";
+  const line = (task) => `- ${task.id}: ${task.objective}${task.origin_agent ? ` (from ${task.origin_agent}${task.trust === "agent" ? ", agent-written" : ""})` : ""}`;
+  return ["Harness task board:", ...(waiting.length ? [`${waiting.length} task${waiting.length === 1 ? "" : "s"} waiting for you:`, ...waiting.slice(0, 5).map(line)] : []),
+    ...(held.length ? [`${held.length} you already claimed:`, ...held.slice(0, 5).map(line)] : []),
+    "Read one with get_task, claim it with claim_task before working, and report_task when done or stuck."].join("\n");
+}
 let nextId = 1;
 let typeApi = null;
 
@@ -88,5 +127,21 @@ export default function tryHarness(pi) {
     return connecting;
   };
   pi.on("session_start", (_event, ctx) => void connect(ctx).catch((error) => ctx?.ui?.notify?.("Harness unavailable: " + error?.message, "warning")));
+  const tell = (nudge, ctx) => {
+    if (!nudge) return;
+    // Into the model's context when pi offers it; always visible to the person.
+    if (typeof pi.sendMessage === "function") { try { pi.sendMessage({ customType: "harness-board", content: nudge, display: true }); } catch {} }
+    ctx?.ui?.notify?.(nudge.split("\n").slice(0, 2).join(" "), "info");
+  };
+  pi.on("session_start", async (_event, ctx) => tell(await boardNudge(false), ctx));
+  // Into the model's own context: pi lets an extension return the system prompt it should use
+  // (pi 0.87: before_agent_start -> { systemPrompt }). The queue is appended, never substituted.
+  pi.on("before_agent_start", async (event) => {
+    const nudge = await boardNudge(false);
+    if (!nudge || typeof event?.systemPrompt !== "string") return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${nudge}` };
+  });
+  // After each turn (pi 0.87 event name turn_end), only when the queue moved.
+  pi.on("turn_end", async (_event, ctx) => tell(await boardNudge(true), ctx));
   pi.registerCommand("harness-reconnect", { description: "Reconnect Harness", handler: async (_args, ctx) => connect(ctx) });
 }

package/cli.mjs

@@ -3,16 +3,17 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { configureAgents, AGENTS, removeAgentConfigurations } from "./lib/adapters.mjs";
+import { configureAgents, AGENTS, MCP_CLIENTS, detectMcpClients, mcpClientSnippet, removeAgentConfigurations } from "./lib/adapters.mjs";
 import { detectAgents } from "./lib/commands.mjs";
 import { daemonRequest } from "./lib/control-client.mjs";
 import { ensureDir, readJson, writeJsonAtomic } from "./lib/files.mjs";
 import { paths } from "./lib/paths.mjs";
-import { installRuntime } from "./lib/runtime-install.mjs";
+import { currentRuntime, installRuntime } from "./lib/runtime-install.mjs";
+import { ensureModel, modelPresent } from "./lib/embedder.mjs";
 import { installService, serviceInfo, uninstallService } from "./lib/service.mjs";
 
 const SOURCE_ROOT = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE = readJson(path.join(SOURCE_ROOT, "package.json"), { version: "0.4.2" });
+const PACKAGE = readJson(path.join(SOURCE_ROOT, "package.json"), { version: "0.4.3" });
 const VERSION = PACKAGE.version;
 const NODE_MAJOR = Number(process.versions.node.split(".")[0]);
 if (!Number.isFinite(NODE_MAJOR) || NODE_MAJOR < 18) {
@@ -150,10 +151,21 @@ async function connect() {
   config = { ...readJson(paths.config, config), version: VERSION, runtimeRoot, agentStates: stateMap };
   writeJsonAtomic(paths.config, config);
   printAgentStates(states);
+  for (const client of detectMcpClients()) {
+    if (client.path) console.log(`  ! ${client.client}: found; it joins the task board once you paste its MCP snippet (npx tryharness mcp ${client.client})`);
+  }
 
   const service = installService({ runtimeRoot });
   const ready = await waitForDaemon();
   console.log(`daemon: ready via ${service.manager} and connected to Harness`);
+  // The context space's embedder lives with the daemon and comes down with setup, so the machine
+  // can search a task by meaning before the first task exists. About 110 MB, once.
+  try {
+    if (modelPresent(paths.models)) console.log("embedder: ready");
+    else { console.log("embedder: downloading (about 110 MB, once)"); await ensureModel({ modelsDir: paths.models, log: (line) => console.log(`  ${line}`) }); console.log("embedder: ready"); }
+  } catch (error) {
+    console.log(`embedder: not downloaded (${error.message}); task search uses words until the next setup run`);
+  }
   const failed = states.filter((state) => selected.includes(state.agent) && state.installed && !state.configured);
   if (failed.length) {
     throw new Error(`setup is incomplete for ${failed.map((state) => state.agent).join(", ")}. Nothing was hidden; run npx tryharness doctor after fixing the reported CLI error, then rerun setup.`);
@@ -211,18 +223,167 @@ async function sync() {
   console.log(`Local history scan started for ${agent}. It runs in the daemon; this terminal does not need to stay open.`);
 }
 
-async function handoff() {
-  const agent = argv[0];
-  if (!AGENTS.includes(agent)) throw new Error("usage: tryharness handoff <claude-code|codex|pi|opencode> --file <brief.md>");
+async function notify() {
+  const mode = argv[0];
+  if (!["on", "off"].includes(mode)) { const config = readJson(paths.config, {}); console.log(`desktop notifications: ${config.notifications === false ? "off" : "on"} (tryharness notify on|off)`); return; }
+  const config = readJson(paths.config, {});
+  writeJsonAtomic(paths.config, { ...config, notifications: mode === "on" });
+  console.log(`desktop notifications ${mode}. The daemon picks this up on its next change.`);
+}
+
+async function connectAgent() {
+  // Ask another person's listed agent to work an issue with one of ours: a request their Harness shows them.
+  const to = String(argv[0] || "");
+  if (!/^[a-z0-9][a-z0-9-]{1,19}\/[a-z0-9][a-z0-9._-]{0,63}$/.test(to)) throw new Error("usage: tryharness connect <handle/agent> --about <text> [--agent <your agent>] [--file <brief.md>]");
+  const fromAgent = arg("--agent", "claude-code");
+  if (!AGENTS.includes(fromAgent)) throw new Error(`--agent must be one of ${AGENTS.join(", ")}`);
+  const about = arg("--about", "");
+  if (!about.trim()) throw new Error("connect needs --about");
   const file = arg("--file");
-  let body = "";
-  if (file) body = fs.readFileSync(path.resolve(file), "utf8");
-  else if (!process.stdin.isTTY) for await (const chunk of process.stdin) body += chunk;
-  else body = arg("--body", "");
-  if (!body.trim()) throw new Error("handoff needs --file, --body, or piped input");
-  const response = await daemonRequest({ command: "handoffs.create", agent, sessionId: arg("--session"), title: arg("--title", path.basename(file || "Harness handoff")), body, source: file ? path.resolve(file) : "tryharness CLI" });
-  if (!response.ok) throw new Error(response.error || "handoff failed");
-  console.log(`Handoff ${response.id} is ready for ${agent}. Harness's get_handoff tool can read it.`);
+  let brief = "";
+  if (file) brief = fs.readFileSync(path.resolve(file), "utf8");
+  else if (!process.stdin.isTTY) for await (const chunk of process.stdin) brief += chunk;
+  const response = await daemonRequest({ command: "relay.request", to, fromAgent, about, brief }, 20_000);
+  if (!response.ok) throw new Error(response.error || "request failed");
+  console.log(`Asked ${to} to work "${about}" with your ${fromAgent}. Thread ${String(response.threadId || "").slice(0, 8)} is ${response.status || "requested"}; once they accept, it appears on your board and your ${fromAgent} is told.`);
+}
+
+async function mcpSnippet() {
+  const client = argv[0];
+  if (!MCP_CLIENTS.includes(client)) throw new Error(`usage: tryharness mcp <${MCP_CLIENTS.join("|")}>`);
+  const config = readJson(paths.config, {});
+  const runtimeRoot = config.runtimeRoot || currentRuntime();
+  if (!runtimeRoot) throw new Error("no Harness runtime is installed yet; run npx tryharness first");
+  const found = detectMcpClients().find((entry) => entry.client === client);
+  console.log(`${client}: ${found?.path ? `found at ${found.path}` : "not found on this machine; the snippet still works once it is installed"}`);
+  console.log(`In ${client === "grok-bot" ? "Grok Bot, open Settings, MCP, add a server" : client} and paste this:\n`);
+  console.log(JSON.stringify(mcpClientSnippet({ runtimeRoot, client }), null, 2));
+  console.log(`\nIt then sees the board through list_tasks, get_task, post_task, claim_task and report_task as "${client}".`);
+}
+
+async function board() {
+  const sub = argv.find((value) => !value.startsWith("--")) || "list";
+  const agent = arg("--as", "user");
+  if (sub === "post") {
+    // --for codex,claude-code posts one task for several agents at once.
+    const targets = String(arg("--for", "")).split(",").map((value) => value.trim()).filter(Boolean);
+    const target = targets.length === 1 ? targets[0] : null;
+    // Coding agents, Grok Bot and Harness live on this machine's board; Bankr, Quotient and Muse live in Harness and the daemon posts there.
+    const allowed = (name) => AGENTS.includes(name) || ["harness", "grok-bot", "muse", "bankr", "quotient"].includes(name);
+    if (targets.some((name) => !allowed(name))) throw new Error("usage: tryharness board post --for <agent[,agent...]> --objective <text> [--file <brief.md>] [--run --workspace <dir>]");
+    const objective = arg("--objective", "");
+    const file = arg("--file");
+    let brief = "";
+    if (file) brief = fs.readFileSync(path.resolve(file), "utf8");
+    else if (!process.stdin.isTTY) for await (const chunk of process.stdin) brief += chunk;
+    if (!objective.trim()) throw new Error("board post needs --objective");
+    const runWorkspace = has("--run") ? path.resolve(arg("--workspace", process.cwd())) : null;
+    if (runWorkspace && !targets.every((name) => AGENTS.includes(name))) throw new Error("--run needs --for with coding agents installed on this machine");
+    if (targets.length > 1 && targets.some((name) => ["bankr", "quotient", "muse"].includes(name))) throw new Error("a task for several agents at once is for agents on this machine; post a task for bankr, quotient or muse on its own");
+    const response = await daemonRequest({ command: "board.post", agent, objective, brief, targetAgent: target, ...(targets.length > 1 ? { targetAgents: targets } : {}), runWorkspace });
+    if (!response.ok) throw new Error(response.error || "post failed");
+    if (targets.length > 1) console.log(`Task ${response.task.id} is on the board for ${targets.join(", ")} at once${runWorkspace ? `, each running in ${runWorkspace}` : ""}. It closes with every result when the last of them finishes.`);
+    else if (runWorkspace) console.log(`Task ${response.task.id} is on the board and ${target} will run it in ${runWorkspace}. Follow it: npx tryharness task ${response.task.id} --follow`);
+    else console.log(`Task ${response.task.id} is on the board${target ? ` for ${target}` : ""}. Any agent's list_tasks tool shows it.`);
+    return;
+  }
+  if (sub === "send" || sub === "discard") {
+    const id = String(argv[argv.indexOf(sub) + 1] || "");
+    const messageId = String(argv[argv.indexOf(sub) + 2] || "");
+    if (!id || !messageId) throw new Error(`usage: tryharness board ${sub} <task id> <message id>`);
+    const response = await daemonRequest({ command: sub === "send" ? "board.thread.send" : "board.thread.discard", agent, id, messageId });
+    if (!response.ok) throw new Error(response.error || `${sub} failed`);
+    console.log(sub === "send" ? `Sent to ${response.message.recipient}.` : "Discarded.");
+    return;
+  }
+  if (sub === "auto" || sub === "end") {
+    const id = String(argv[argv.indexOf(sub) + 1] || "");
+    const response = sub === "auto"
+      ? await daemonRequest({ command: "board.thread.auto", agent, id, on: argv[argv.indexOf(sub) + 2] !== "off" })
+      : await daemonRequest({ command: "board.thread.end", agent, id, outcome: arg("--outcome", "") });
+    if (!response.ok) throw new Error(response.error || `${sub} failed`);
+    console.log(sub === "auto" ? `Auto-send ${response.thread.auto_send ? "on" : "off"} for ${id.slice(0, 8)}. It turns off again if a reply is flagged.` : `Thread ended; the other side is told.`);
+    return;
+  }
+  if (sub === "context") {
+    const id = String(argv[argv.indexOf(sub) + 1] || "");
+    const query = argv.slice(argv.indexOf(sub) + 2).filter((value) => !value.startsWith("--")).join(" ");
+    if (!id || !query) throw new Error("usage: tryharness board context <task id> <what you are looking for>");
+    const response = await daemonRequest({ command: "board.context.search", agent, id, query, limit: 8 }, 20_000);
+    if (!response.ok) throw new Error(response.error || "search failed");
+    const how = response.retrieval === "vectors" ? "meaning" : response.embedder === "absent" ? "words (the embedder is not downloaded yet; run npx tryharness)" : `words (${response.context?.embedded ?? 0} of ${response.context?.total ?? 0} entries embedded so far)`;
+    console.log(`${response.entries.length} result${response.entries.length === 1 ? "" : "s"} by ${how}`);
+    for (const entry of response.entries) console.log(`\n[${entry.kind} · ${entry.author}${entry.source ? ` · ${entry.source}` : ""} · ${entry.score}]\n${entry.text.slice(0, 400)}`);
+    return;
+  }
+  if (sub === "run" || sub === "release") {
+    const id = String(argv[argv.indexOf(sub) + 1] || "");
+    const response = await daemonRequest({ command: sub === "run" ? "board.run" : "board.release", agent, id });
+    if (!response.ok) throw new Error(response.error || `${sub} failed`);
+    console.log(sub === "run" ? `Run authorized; ${response.task.target_agent} starts it now. Follow it: npx tryharness task ${id} --follow` : `Task ${id} is open again.`);
+    return;
+  }
+  if (sub === "watch" || has("--watch")) {
+    // The terminal view that follows the board: one line per change, no Harness window needed.
+    const seen = new Map();
+    let first = true;
+    for (;;) {
+      const response = await daemonRequest({ command: "board.list", agent, all: true, limit: 100 }).catch(() => null);
+      if (response?.ok) {
+        for (const t of response.tasks) {
+          const key = `${t.status}:${t.version}:${t.stale ? "stale" : ""}`;
+          if (seen.get(t.id) === key) continue;
+          seen.set(t.id, key);
+          if (!first || ["open", "claimed", "running", "needs_input"].includes(t.status)) console.log(`${new Date().toLocaleTimeString()}  ${t.id.slice(0, 8)}  ${(t.stale ? "stale" : t.status).padEnd(11)} ${t.origin_agent} → ${t.target_agent || "anyone"}${t.claimed_by ? ` (${t.claimed_by})` : ""}${t.run_workspace && !t.run_authorized_at ? " [wants to run]" : ""}  ${t.objective}`);
+        }
+        if (first) console.log("watching the board (Ctrl-C stops)");
+        first = false;
+      } else if (first) { console.log("daemon not running; waiting"); first = false; }
+      await sleep(2_000);
+    }
+  }
+  if (sub === "agents") {
+    const response = await daemonRequest({ command: "board.agents", agent });
+    if (!response.ok) throw new Error(response.error || "board unavailable");
+    if (!response.agents.length) { console.log("No agent has read the board yet."); return; }
+    for (const row of response.agents) console.log(`${row.agent.padEnd(14)} last seen ${row.last_seen_at}${response.running.some((run) => run.agent === row.agent) ? " · running a task" : ""}`);
+    return;
+  }
+  if (sub === "show") {
+    const response = await daemonRequest({ command: "board.get", agent, id: String(argv[argv.indexOf("show") + 1] || "") });
+    if (!response.ok) throw new Error(response.error || "task not found");
+    const { task: t } = response;
+    console.log(`${t.id} · ${t.status}${t.stale ? " (stale claim)" : ""} · from ${t.origin_agent}${t.target_agent ? ` for ${t.target_agent}` : ""}${t.claimed_by ? ` · claimed by ${t.claimed_by}` : ""} · held by ${t.holder || "nobody"} · version ${t.version}\n${t.objective}\n`);
+    if (t.kind === "group") for (const part of t.children || []) console.log(`  part for ${part.target_agent}: ${part.status}${part.claimed_by ? ` (${part.claimed_by})` : ""} · ${part.id}${part.result ? `\n    ${String(part.result).slice(0, 200)}` : ""}`);
+    if (t.run_workspace) console.log(`run: ${t.run_authorized_at ? `authorized by ${t.run_authorized_by}` : "requested, waiting for: npx tryharness board run " + t.id} · ${t.run_workspace}${t.session_id ? `\nagent session: ${t.session_id}\nopen live session: ${resumeCommand(t.target_agent, t.session_id, t.run_workspace)}` : ""}\n`);
+    if (t.brief) console.log(t.brief + "\n");
+    if (t.result) console.log(`${t.status === "needs_input" ? "question" : "result"}: ${t.result}`);
+    const thread = await daemonRequest({ command: "board.thread.read", agent, id: t.id });
+    if (thread.ok) {
+      console.log(`\nthread with ${thread.thread.with_agent}${thread.thread.closed_at ? " (ended)" : thread.thread.auto_send ? " (auto-send on)" : " (replies held for you)"}`);
+      for (const m of thread.messages) console.log(`  ${m.direction === "in" ? "←" : "→"} ${m.sender} [${m.state}${m.flag_reason ? `: ${m.flag_reason}` : ""}] ${m.text.slice(0, 300)}${m.state === "held" || m.state === "flagged" ? `\n    send: tryharness board send ${t.id} ${m.id}` : ""}`);
+    }
+    return;
+  }
+  if (sub === "trace") {
+    const response = await daemonRequest({ command: "board.trace", agent, id: String(argv[argv.indexOf("trace") + 1] || "") }, 30_000);
+    if (!response.ok) throw new Error(response.error || "trace unavailable");
+    const t = response.trace;
+    const time = (value) => (value == null ? "-" : value < 1_000 ? `${value}ms` : value < 120_000 ? `${(value / 1_000).toFixed(1)}s` : `${(value / 60_000).toFixed(1)}m`);
+    console.log(`${t.hops} hop${t.hops === 1 ? "" : "s"} · ${t.status} · ${time(t.wall_ms)} end to end${t.finished_at ? "" : " so far"} · ${time(t.person_ms)} waiting on you · agents: ${t.agents.join(", ")}`);
+    for (const span of t.spans) console.log(`${"  ".repeat(span.depth)}${span.id.slice(0, 8)} ${span.origin_agent} → ${span.worked_by || span.target_agent || "anyone"} [${span.status}${span.trust === "agent" ? `, written by ${span.origin_chain.join(" → ")}` : ""}] you ${time(span.person_ms)} · queue ${time(span.queue_ms)} · work ${time(span.work_ms)} · ${span.objective.slice(0, 60)}`);
+    if (t.slowest) console.log(`slowest: ${t.slowest.id.slice(0, 8)} (${t.slowest.worked_by}) ${time(t.slowest.work_ms)}`);
+    const c = t.cost;
+    const usd = (microCents) => `$${(microCents / 100_000_000).toFixed(4)}`;
+    console.log(`cost: ${usd(c.charged_micro_cents)} charged by Harness${c.held_micro_cents ? `, ${usd(c.held_micro_cents)} held` : ""}; agents reported $${c.agent_reported_usd.toFixed(4)} and ${c.tokens.input + c.tokens.output} tokens${c.unrecorded.length ? `; no figure for ${c.unrecorded.map((id) => id.slice(0, 8)).join(", ")}` : ""}`);
+    for (const wait of t.waiting_on) console.log(`waiting: ${wait.id.slice(0, 8)} is ${wait.status}${wait.holder ? ` with ${wait.holder}` : ""}`);
+    return;
+  }
+  if (sub !== "list") throw new Error("usage: tryharness board [list --all | show <id> | trace <id> | post --for <agent> --objective <text> [--file <brief.md>] [--run --workspace <dir>] | run <id> | release <id> | agents]");
+  const response = await daemonRequest({ command: "board.list", agent, all: has("--all") });
+  if (!response.ok) throw new Error(response.error || "board unavailable");
+  if (!response.tasks.length) { console.log("The board is empty."); return; }
+  for (const t of response.tasks) console.log(`${t.id}  ${(t.stale ? "stale" : t.status).padEnd(11)} ${t.origin_agent} → ${t.kind === "group" ? `${t.child_agents} (${t.child_done} of ${t.child_count} done)` : t.target_agent || "anyone"}${t.claimed_by ? ` (${t.claimed_by})` : ""}${t.run_workspace && !t.run_authorized_at ? " [wants to run]" : ""}  ${t.objective}`);
 }
 
 async function task() {
@@ -254,11 +415,12 @@ async function task() {
       console.log(`\nagent session: ${current.sessionId}`);
       console.log(`open live session: ${resumeCommand(current.agent, current.sessionId, current.cwd)}`);
     }
-    const terminal = current.status === "done" || current.status === "failed";
+    const terminal = current.status === "done" || current.status === "failed" || current.status === "interrupted";
     if (!follow || (terminal && offset >= current.logLength)) {
       console.log(`\nstatus: ${current.status}`);
       if (current.message) console.log(current.message);
-      if (current.status === "failed") process.exitCode = 1;
+      if (current.status === "interrupted") console.log("The daemon restarted during this run; its outcome is unknown. Check the repository.");
+      if (current.status !== "done") process.exitCode = 1;
       return;
     }
     await sleep(500);
@@ -282,16 +444,19 @@ async function disconnect() {
 }
 
 function help() {
-  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness task <id> --follow\n                             follow a delegated agent run in this terminal\n  tryharness handoff <agent> --file <path>\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
+  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness task <id> --follow\n                             follow a delegated agent run in this terminal\n  tryharness board [--all]   list open work on the machine's task board\n  tryharness board post --for <agent> --objective <text> [--file <brief.md>]\n  tryharness board show <id>\n  tryharness board post --for codex --objective <text> --run --workspace <dir>\n                             the daemon runs it and reports back on the task\n  tryharness board run <id>  authorize a run an agent asked for\n  tryharness board release <id>\n  tryharness board agents    when each agent last read the board\n  tryharness board --watch   follow the board in this terminal\n  tryharness notify on|off   desktop notifications for what waits on you\n  tryharness board send <task> <message>   send a held reply to another person's agent\n  tryharness board auto <task> on|off      auto-send replies on that thread\n  tryharness board end <task> --outcome <text>\n  tryharness board context <task> <query>  search everything written about a task\n  tryharness connect <handle/agent> --about <text>   ask another person's agent to work an issue with yours\n  tryharness mcp grok-bot    print the MCP snippet that puts Grok Bot on the board\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
 }
 
 try {
-  if (command === "connect" || command === "setup") await connect();
+  if (command === "setup" || (command === "connect" && !argv[0])) await connect();
   else if (command === "status" || command === "bridge") await status();
   else if (command === "doctor") await doctor();
   else if (command === "sync" || command === "backfill" || command === "drain") await sync();
   else if (command === "task") await task();
-  else if (command === "handoff") await handoff();
+  else if (command === "board") await board();
+  else if (command === "mcp") await mcpSnippet();
+  else if (command === "notify") await notify();
+  else if (command === "connect") await connectAgent();
   else if (command === "logs") logs();
   else if (command === "disconnect") await disconnect();
   else if (command === "daemon") { const { startDaemon } = await import("./lib/daemon.mjs"); await startDaemon(); }

package/lib/adapters.mjs

@@ -7,6 +7,23 @@ import { paths } from "./paths.mjs";
 
 export const AGENTS = ["claude-code", "codex", "pi", "opencode"];
 
+// MCP clients that are not coding agents: no history to index and nothing to run, but they
+// join the machine's task board by launching the same stdio MCP under their own name.
+export const MCP_CLIENTS = ["grok-bot"];
+const MCP_CLIENT_APPS = {
+  "grok-bot": { darwin: ["/Applications/Grok Bot.app", path.join(os.homedir(), "Applications", "Grok Bot.app")] },
+};
+
+export function detectMcpClients({ platform = process.platform, exists = fs.existsSync } = {}) {
+  return MCP_CLIENTS.map((client) => ({ client, path: (MCP_CLIENT_APPS[client][platform] || []).find((candidate) => exists(candidate)) || null }));
+}
+
+// Grok Bot keeps its MCP server list in its account and writes it only from its own settings
+// (a one-server JSON paste); there is no file on disk to write. The snippet is the setup.
+export function mcpClientSnippet({ runtimeRoot, client, nodePath = process.execPath }) {
+  return { mcpServers: { harness: { command: nodePath, args: [path.join(runtimeRoot, "lib", "mcp-stdio.mjs"), "--agent", client] } } };
+}
+
 function installAsset(source, target) {
   ensureDir(path.dirname(target));
   fs.copyFileSync(source, target);
@@ -24,6 +41,70 @@ export function integrationAssets(homeDir = os.homedir()) {
   };
 }
 
+// Claude Code learns about waiting board work through a SessionStart hook whose stdout joins
+// its context. The hook is one entry in the user's settings, added once and removed on
+// disconnect; every other setting and hook is left as it was.
+export function claudeSettingsPath(homeDir = os.homedir()) {
+  return path.join(homeDir, ".claude", "settings.json");
+}
+const isHarnessHook = (entry) => JSON.stringify(entry).includes("/lib/nudge.mjs");
+
+export function installClaudeSessionHook({ runtimeRoot, homeDir = os.homedir(), nodePath = process.execPath }) {
+  const file = claudeSettingsPath(homeDir);
+  const settings = readJson(file, {});
+  const hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const nudge = JSON.stringify(path.join(runtimeRoot, "lib", "nudge.mjs"));
+  const starts = (Array.isArray(hooks.SessionStart) ? hooks.SessionStart : []).filter((entry) => !isHarnessHook(entry));
+  starts.push({ hooks: [{ type: "command", command: `${JSON.stringify(nodePath)} ${nudge} --agent claude-code`, timeout: 10 }] });
+  // Mid-session: on every prompt, one line only when the queue changed since the session last saw it.
+  const prompts = (Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : []).filter((entry) => !isHarnessHook(entry));
+  prompts.push({ hooks: [{ type: "command", command: `${JSON.stringify(nodePath)} ${nudge} --agent claude-code --if-changed`, timeout: 10 }] });
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: starts, UserPromptSubmit: prompts } }, null, 2) + "\n");
+}
+
+// Codex reads the same hook shape from ~/.codex/hooks.json (SessionStart and UserPromptSubmit,
+// stdout added as developer context). Codex asks the person to trust a new or changed hook once,
+// with /hooks in its TUI, before it runs; setup says so.
+export function codexHooksPath(homeDir = os.homedir()) {
+  return path.join(homeDir, ".codex", "hooks.json");
+}
+
+export function installCodexHooks({ runtimeRoot, homeDir = os.homedir(), nodePath = process.execPath }) {
+  const file = codexHooksPath(homeDir);
+  const settings = readJson(file, {});
+  const hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const nudge = JSON.stringify(path.join(runtimeRoot, "lib", "nudge.mjs"));
+  const starts = (Array.isArray(hooks.SessionStart) ? hooks.SessionStart : []).filter((entry) => !isHarnessHook(entry));
+  starts.push({ matcher: "startup|resume", hooks: [{ type: "command", command: `${JSON.stringify(nodePath)} ${nudge} --agent codex`, statusMessage: "Reading the Harness board", timeout: 10 }] });
+  const prompts = (Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : []).filter((entry) => !isHarnessHook(entry));
+  prompts.push({ hooks: [{ type: "command", command: `${JSON.stringify(nodePath)} ${nudge} --agent codex --if-changed`, timeout: 10 }] });
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: starts, UserPromptSubmit: prompts } }, null, 2) + "\n");
+}
+
+export function removeCodexHooks(homeDir = os.homedir()) {
+  const file = codexHooksPath(homeDir);
+  const settings = readJson(file, null);
+  if (!settings?.hooks) return;
+  const hooks = { ...settings.hooks };
+  for (const event of ["SessionStart", "UserPromptSubmit"]) {
+    if (Array.isArray(hooks[event])) hooks[event] = hooks[event].filter((entry) => !isHarnessHook(entry));
+  }
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks }, null, 2) + "\n");
+}
+
+export function removeClaudeSessionHook(homeDir = os.homedir()) {
+  const file = claudeSettingsPath(homeDir);
+  const settings = readJson(file, null);
+  if (!settings?.hooks) return;
+  const hooks = { ...settings.hooks };
+  for (const event of ["SessionStart", "UserPromptSubmit"]) {
+    if (Array.isArray(hooks[event])) hooks[event] = hooks[event].filter((entry) => !isHarnessHook(entry));
+  }
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks }, null, 2) + "\n");
+}
+
 export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.homedir(), detected = detectAgents(), execute = run, connection = readJson(paths.config, {}) }) {
   const byAgent = new Map(detected.map((entry) => [entry.agent, entry]));
   const mcpPath = path.join(runtimeRoot, "lib", "mcp-stdio.mjs");
@@ -42,11 +123,15 @@ export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.h
     if (agent === "claude-code") {
       execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
       const added = execute(found.path, ["mcp", "add", "--scope", "user", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
-      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP configured" : diagnostic(added) });
+      let hooked = true;
+      try { installClaudeSessionHook({ runtimeRoot, homeDir }); } catch { hooked = false; }
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? (hooked ? "MCP and session-start nudge configured" : "MCP configured; the session-start hook could not be written") : diagnostic(added) });
     } else if (agent === "codex") {
       execute(found.path, ["mcp", "remove", "harness"]);
       const added = execute(found.path, ["mcp", "add", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
-      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP configured" : diagnostic(added) });
+      let hooked = true;
+      try { installCodexHooks({ runtimeRoot, homeDir }); } catch { hooked = false; }
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? (hooked ? "MCP and session hooks configured; in Codex run /hooks once to trust them" : "MCP configured; the session hooks could not be written") : diagnostic(added) });
     } else if (agent === "pi") {
       installAsset(path.join(runtimeRoot, "assets", "pi-extension.ts"), assets.pi);
       states.push({ agent, installed: true, configured: fs.existsSync(assets.pi), detail: "extension installed" });
@@ -69,8 +154,9 @@ export function agentHealth(states) {
 export function removeAgentConfigurations({ homeDir = os.homedir(), detected = detectAgents(), execute = run } = {}) {
   for (const found of detected) {
     if (!found.path) continue;
-    if (found.agent === "claude-code") execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
-    else if (found.agent === "codex" || found.agent === "opencode") execute(found.path, ["mcp", "remove", "harness"]);
+    if (found.agent === "claude-code") { execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]); removeClaudeSessionHook(homeDir); }
+    else if (found.agent === "codex") { execute(found.path, ["mcp", "remove", "harness"]); removeCodexHooks(homeDir); }
+    else if (found.agent === "opencode") execute(found.path, ["mcp", "remove", "harness"]);
   }
   const assets = integrationAssets(homeDir);
   for (const target of Object.values(assets)) {