tryharness 0.7.18 → 0.7.23

package/README.md

@@ -50,15 +50,51 @@ 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
+## Local models
+
+Setup downloads the relay's core local models into `~/.harness/local`, each file checked
+against a pinned SHA-256 and every model under an allowlisted licence (`cli/lib/localmodels.mjs`):
+EmbeddingGemma 2's text part (one search space for code, agent sessions and board posts), an
+two injection guards (one reads long stretches and holds, one reads short ones and flags), a
+credential detector and a screenshot text reader (PP-OCR), plus llama.cpp's own server build
+(about 860 MB of models). Two more come down the first time they are used: speech for the buddy's
+Talk (Silero VAD, 1.3 MB, and on a Mac with macOS 26 Apple's own on-device transcriber through
+the buddy; elsewhere NVIDIA's Parakeet TDT 0.6B v3, 672 MB) and the search model's image and audio part
+(555 MB) when you first add a folder of recordings or screenshots. The search model runs on the
+GPU when this machine's check finds it faster, the CPU otherwise; the classifiers run in native
+ONNX Runtime. Background work runs at the OS's background priority and waits in Low Power Mode,
+on low battery and when the machine is hot.
+
+What they do:
+
+- **Briefs:** every brief a local coding agent gets carries a context pack (the files in its
+  repository most likely needed, earlier sessions on them, and a recording's minute or a
+  screenshot from your added folders when one is close) and the thread's task frame: what you
+  named resolved to file and line, the repository's state, other threads changing the same
+  repository, and each run's receipt. Agents can call `search_code`, `search_media`,
+  `compare_screens` (two screenshots of UI work, before and after: what changed and which text)
+  and `search_screen` (what you saw in tabs shared with Harness, asked of your own Harness window
+  sealed over the `tryharness link` line, so Harness's server carries it unread; your Allow in
+  that window comes first).
+- **Checks:** a finished run gets a receipt from its own session file; the coordinator hands an
+  untested "tests pass" to an agent to check. An agent's post that reads like orders to the
+  swarm is held; a key in anything sent to Harness's server goes as `[SECRET_n]` (and, in requests
+  that only decide, emails, phone numbers, wallet addresses and amounts as placeholders too); a
+  screenshot a cloud agent reads has keys, addresses and amounts covered; code a cloud agent asks to
+  see (`request_snippet`) leaves only when you share it (`tryharness board snippet`).
+- **Watches:** a command on this computer checked on a schedule (a heartbeat's age, a balance, a
+  count of error lines), said out loud only when it is off. Agents suggest them with
+  `suggest_watch`; nothing runs until you start it.
+- **Learning:** overnight, on the charger, the ranking model retrains on what the agents' runs
+  actually changed and is kept only if it beats the current one on the newest runs.
 
-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.
+```sh
+npx tryharness local                  # what is installed, where it runs, what is indexed, the last learning
+npx tryharness local learn            # start the learner now
+npx tryharness local add ~/Recordings # a folder of recordings and screenshots agents can search
+npx tryharness watch                  # watches and what each last read
+npx tryharness watch add "keeper heartbeat" --run "cat state/heartbeat.json" --age completedAt --above 900 --every 5m
+```
 
 ## Task board
 
@@ -92,18 +128,21 @@ claim carries a lease (default 60 minutes); a lapsed lease shows the claim as st
 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
+Interactive sessions are told about waiting work when they open and when it changes, by the same
+code (`lib/nudge.mjs`) for every agent. 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 session's first message and to
+later ones 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>`.
+only. Any MCP client on the machine joins the board by launching `lib/mcp-stdio.mjs --agent <name>`:
+Claude Code, Codex, OpenCode, OpenClaw and Hermes have it in their MCP settings, and pi, which has no
+MCP client, gets it from its extension, which launches it and gives pi its tools.
 
 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
@@ -132,3 +171,7 @@ room. Agents read, post and search the room with `read_room`, `post_to_room` and
 Start. Harness facilitates and answers once. `tryharness goal show <id>` prints the room, `goal stop <id>` ends
 everything, `goal resume <id>` reopens a room that paused at a backstop, and `goal invite <id> handle/agent` asks another
 person's agent to join as a guest over a relay thread. `tryharness room post <goal> <text> [--guests]` posts as you.
+
+Parakeet TDT 0.6B v3 is by NVIDIA, licensed under CC BY 4.0
+(https://creativecommons.org/licenses/by/4.0/); the relay uses the 8-bit ONNX export by
+istupakov (https://huggingface.co/istupakov/parakeet-tdt-0.6b-v3-onnx), unmodified.

package/assets/opencode-plugin.js

@@ -1,59 +1,19 @@
-// Installed globally by tryharness. It only nudges the local daemon; indexing and retry
-// state stay in the daemon's SQLite database and never block opencode's idle event.
+// Installed globally by tryharness. It tells opencode about its board and hands it what the person sends a session from
+// Harness with lib/nudge.mjs, the code Claude Code's and Codex's hooks run, and nudges the local daemon to index a session; indexing and retry state stay in the daemon's
+// SQLite database and never block opencode's idle event. Its tools come from the Harness server in its MCP config.
 import net from "node:net";
-import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-const socketPath = process.platform === "win32"
-  ? "\\\\.\\pipe\\tryharness-daemon"
-  : path.join(os.homedir(), ".harness", "daemon.sock");
+// Filled in by setup: the runtime the other agents' Harness server runs from.
+const RUNTIME = "__HARNESS_RUNTIME__";
+const AGENT = "opencode";
+const harness = () => import(pathToFileURL(path.join(RUNTIME, "lib", "nudge.mjs")).href);
+const socketPath = async () => (await import(pathToFileURL(path.join(RUNTIME, "lib", "paths.mjs")).href)).paths.socket;
 
-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, and the person's other
-// agents and what each is for (the swarm block, from the daemon), again only when either changed.
-async function boardNudge(sessionId) {
-  const response = await ask({ command: "board.list", agent: "opencode", swarm: true });
-  const tasks = response?.ok ? response.tasks : [];
-  const swarm = response?.swarm?.digest && lastSwarm.get(sessionId) !== response.swarm.digest ? response.swarm : null;
-  if (swarm) lastSwarm.set(sessionId, swarm.digest);
-  return [queueNudge(sessionId, tasks), swarm?.text].filter(Boolean).join("\n\n");
-}
-const lastSwarm = new Map();
-function queueNudge(sessionId, 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) {
+async function notify(message) {
   try {
-    const socket = net.createConnection(socketPath);
+    const socket = net.createConnection(await socketPath());
     socket.setTimeout(1_000);
     socket.on("connect", () => socket.end(JSON.stringify(message) + "\n"));
     socket.on("error", () => {});
@@ -61,28 +21,49 @@ function notify(message) {
   } catch {}
 }
 
-// Where a session runs, as opencode's own environment says (Harness's places.mjs reads it): once per session.
-const PLACE_ENV = ["__CFBundleIdentifier", "TERM_PROGRAM", "TMUX", "TMUX_PANE", "WEZTERM_PANE", "KITTY_WINDOW_ID", "KITTY_LISTEN_ON", "WT_SESSION", "VSCODE_GIT_ASKPASS_NODE"];
-const placed = new Set();
-function notePlace(sessionId, directory) {
-  if (placed.has(sessionId)) return;
-  placed.add(sessionId);
-  const env = Object.fromEntries(PLACE_ENV.filter((name) => process.env[name]).map((name) => [name, process.env[name]]));
-  notify({ command: "board.live.place", agent: "opencode", sessionId, folder: directory, pids: [process.pid, process.ppid], env });
-}
+const started = new Set();
+const pids = [process.pid, process.ppid];
+// opencode saves only a part that names its id, session and message; the id is opencode's own shape (prt_, the time,
+// then random), so the notice sorts after the person's words.
+let counter = 0;
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const partId = () => {
+  const time = ((BigInt(Date.now()) * 0x1000n) + BigInt(++counter % 0x1000)) & 0xffffffffffffn;
+  return "prt_" + time.toString(16).padStart(12, "0") + Array.from(crypto.getRandomValues(new Uint8Array(14)), (byte) => BASE62[byte % 62]).join("");
+};
 
-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.
+export const TryHarnessPlugin = async ({ directory, client }) => ({
+  // A session's first message is its start (Claude Code's SessionStart: the whole board); each later one carries the
+  // board again only when it changed (UserPromptSubmit).
   "chat.message": async (input, output) => {
     const sessionId = input?.sessionID || input?.sessionId;
     if (!sessionId || !Array.isArray(output?.parts)) return;
-    notePlace(sessionId, directory);
-    const nudge = await boardNudge(sessionId);
-    if (nudge) output.parts.push({ type: "text", text: nudge });
+    const board = await harness().catch(() => null);
+    if (!board) return;
+    const where = { session_id: sessionId, cwd: directory };
+    const first = !started.has(sessionId);
+    started.add(sessionId);
+    if (first) await board.notePlace(AGENT, where, pids);
+    await board.notePrompt(AGENT, where, pids);
+    const messageID = output.message?.id || input?.messageID;
+    if (!messageID) return;
+    const messages = await board.takeMessages(AGENT, sessionId);
+    const nudge = first ? await board.boardNudge(AGENT) : await board.boardNudgeIfChanged(AGENT);
+    // Marked synthetic: the model reads them, and they are not the words typed here.
+    for (const text of [messages.length ? board.messagesText(messages) : "", nudge]) {
+      if (text) output.parts.push({ id: partId(), sessionID: sessionId, messageID, type: "text", text, synthetic: true });
+    }
   },
   event: async ({ event }) => {
     if (event?.type !== "session.idle") return;
     const sessionId = event?.properties?.sessionID || event?.properties?.sessionId;
-    if (sessionId) notify({ command: "sync", agent: "opencode", sessionId, cwd: directory });
+    if (!sessionId) return;
+    await notify({ command: "sync", agent: AGENT, sessionId, cwd: directory });
+    // When a turn ends, a message waiting from Harness starts the next one (Claude Code's Stop hook does the same).
+    const board = await harness().catch(() => null);
+    const messages = board ? await board.takeMessages(AGENT, sessionId) : [];
+    const send = client?.session?.promptAsync?.bind(client.session) ?? client?.session?.prompt?.bind(client.session);
+    if (messages.length && send) await send({ path: { id: sessionId }, body: { parts: [{ type: "text", text: board.messagesText(messages) }] } }).catch(() => {});
+    else if (board && !messages.length) await board.noteTurn(AGENT, { session_id: sessionId, cwd: directory }, pids);
   },
 });

package/assets/pi-extension.ts

@@ -1,76 +1,58 @@
 // @ts-nocheck
-// Installed globally by tryharness. pi has no native MCP client, so the extension maps
-// the connected Harness MCP surface into normal pi tools without blocking pi startup.
-import fs from "node:fs";
-import os from "node:os";
+// Installed globally by tryharness. pi has no native MCP client, so the extension starts the Harness server every
+// other agent here uses (lib/mcp-stdio.mjs --agent pi) and maps its tools into normal pi tools, and tells pi about its
+// board and hands it what the person sends the session from Harness with lib/nudge.mjs, the code Claude Code's and
+// Codex's hooks run. Neither blocks pi starting.
+import { spawn } from "node:child_process";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-import net from "node:net";
+// Filled in by setup: the runtime and the Node the other agents' Harness server runs from.
+const RUNTIME = "__HARNESS_RUNTIME__";
+const NODE = "__HARNESS_NODE__";
+const AGENT = "pi";
+const harness = () => import(pathToFileURL(path.join(RUNTIME, "lib", "nudge.mjs")).href);
 
-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("|");
-}
-// The system prompt also carries the swarm block (the person's other agents and what each is for, from the daemon).
-async function boardNudge(onlyIfChanged = false, withSwarm = false) {
-  const response = await daemon({ command: "board.list", agent: "pi", ...(withSwarm ? { swarm: true } : {}) });
-  const tasks = response?.ok ? response.tasks : [];
-  const now = digest(tasks);
-  if (onlyIfChanged && now === lastDigest) return "";
-  lastDigest = now;
-  const queue = queueText(tasks);
-  return withSwarm && response?.swarm?.text ? [queue, response.swarm.text].filter(Boolean).join("\n\n") : queue;
-}
-function queueText(tasks) {
-  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");
-}
+// The server, one per session: JSON-RPC over its stdin and stdout.
+let server = null;
 let nextId = 1;
-let typeApi = null;
-
-function config() {
-  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")); } catch { return {}; }
+function start() {
+  if (server) return server;
+  const child = spawn(NODE, [path.join(RUNTIME, "lib", "mcp-stdio.mjs"), "--agent", AGENT], { stdio: ["pipe", "pipe", "ignore"] });
+  const pending = new Map();
+  let buffer = "";
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    const lines = buffer.split("\n");
+    buffer = lines.pop();
+    for (const line of lines) {
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      pending.get(message.id)?.(message);
+      pending.delete(message.id);
+    }
+  });
+  const stopped = () => {
+    if (server?.child === child) server = null;
+    for (const settle of pending.values()) settle({ error: { message: "the Harness server stopped" } });
+    pending.clear();
+  };
+  child.on("exit", stopped);
+  child.on("error", stopped);
+  server = { child, pending };
+  return server;
 }
-
-async function rpc(method, params = {}) {
-  const current = config();
-  if (!current.origin || !current.token) throw new Error("Harness is not connected. Run: npx tryharness");
-  const response = await fetch(String(current.origin).replace(/\/$/, "") + "/api/mcp", {
-    method: "POST",
-    headers: { "content-type": "application/json", authorization: "Bearer " + current.token },
-    body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method, params }),
-    signal: AbortSignal.timeout(90_000),
+function rpc(method, params = {}) {
+  const { child, pending } = start();
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    pending.set(id, (message) => (message.error ? reject(new Error(message.error.message)) : resolve(message.result)));
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
   });
-  const payload = await response.json().catch(() => null);
-  if (!response.ok || payload?.error) throw new Error(payload?.error?.message || "Harness returned HTTP " + response.status);
-  return payload?.result;
 }
 
+let typeApi = null;
 async function types() {
   if (typeApi) return typeApi;
   try { typeApi = (await import("@sinclair/typebox")).Type; }
@@ -104,9 +86,8 @@ function toType(schema, Type) {
 export default function tryHarness(pi) {
   const installed = new Set();
   let connecting = null;
-  const connect = async (ctx) => {
-    if (connecting) return connecting;
-    connecting = (async () => {
+  const connect = (ctx) => {
+    connecting ??= (async () => {
       const Type = await types();
       const listing = await rpc("tools/list");
       for (const def of listing?.tools || []) {
@@ -117,44 +98,64 @@ export default function tryHarness(pi) {
           description: def.description || "Use this connected Harness capability.",
           parameters: toType(def.inputSchema, Type),
           async execute(_id, params) {
-            try {
-              const result = await rpc("tools/call", { name: def.name, arguments: params || {} });
-              return { content: result?.content || [{ type: "text", text: "Harness returned no content." }], details: {}, isError: result?.isError === true };
-            } catch (error) {
-              return { content: [{ type: "text", text: error?.message || "Harness call failed." }], details: {}, isError: true };
-            }
+            const result = await rpc("tools/call", { name: def.name, arguments: params || {} });
+            const content = result?.content || [{ type: "text", text: "Harness returned no content." }];
+            // pi marks a tool failed when it throws.
+            if (result?.isError) throw new Error(content.map((part) => part.text || "").join("\n") || "Harness call failed.");
+            return { content, details: undefined };
           },
         });
         installed.add(def.name);
       }
       ctx?.ui?.notify?.("Harness connected", "info");
-    })().finally(() => { connecting = null; });
+    })().catch((error) => { connecting = null; ctx?.ui?.notify?.("Harness unavailable: " + error?.message, "warning"); });
     return connecting;
   };
-  pi.on("session_start", (_event, ctx) => void connect(ctx).catch((error) => ctx?.ui?.notify?.("Harness unavailable: " + error?.message, "warning")));
+  const where = (ctx) => ({ session_id: ctx?.sessionManager?.getSessionId?.(), cwd: ctx?.cwd || process.cwd() });
+  const pids = [process.pid, process.ppid];
   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));
-  // Where the session runs, as pi's own environment says (Harness's places.mjs reads it).
-  pi.on("session_start", (_event, ctx) => {
-    const sessionId = ctx?.sessionManager?.getSessionId?.();
-    if (!sessionId) return;
-    const names = ["__CFBundleIdentifier", "TERM_PROGRAM", "TMUX", "TMUX_PANE", "WEZTERM_PANE", "KITTY_WINDOW_ID", "KITTY_LISTEN_ON", "WT_SESSION", "VSCODE_GIT_ASKPASS_NODE"];
-    const env = Object.fromEntries(names.filter((name) => process.env[name]).map((name) => [name, process.env[name]]));
-    void daemon({ command: "board.live.place", agent: "pi", sessionId, folder: ctx?.cwd || process.cwd(), pids: [process.pid, process.ppid], env });
+  pi.on("session_start", async (_event, ctx) => {
+    void connect(ctx);
+    const board = await harness().catch(() => null);
+    if (!board) return;
+    await board.notePlace(AGENT, where(ctx), pids);
+    tell(await board.boardNudge(AGENT), 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, true);
-    if (!nudge || typeof event?.systemPrompt !== "string") return undefined;
-    return { systemPrompt: `${event.systemPrompt}\n\n${nudge}` };
+  // (pi 0.87: before_agent_start -> { systemPrompt }). The queue is appended, never substituted. The tools are in
+  // place before the run, as an MCP client's are.
+  // What the person sent this session from Harness (board.live.say), taken once, as Claude Code's hooks take it.
+  const said = async (board, ctx) => {
+    const sessionId = where(ctx).session_id;
+    const messages = sessionId ? await board.takeMessages(AGENT, sessionId) : [];
+    return messages.length ? board.messagesText(messages) : "";
+  };
+  pi.on("before_agent_start", async (event, ctx) => {
+    await connect(ctx);
+    const board = await harness().catch(() => null);
+    if (!board) return undefined;
+    await board.notePrompt(AGENT, where(ctx), pids);
+    const text = [await said(board, ctx), await board.boardNudge(AGENT)].filter(Boolean).join("\n\n");
+    if (!text || typeof event?.systemPrompt !== "string") return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${text}` };
+  });
+  // When a run has settled, a message waiting from Harness starts the next turn (Claude Code's Stop hook does the same).
+  pi.on("agent_settled", async (_event, ctx) => {
+    const board = await harness().catch(() => null);
+    const text = board ? await said(board, ctx) : "";
+    if (text) pi.sendUserMessage(text);
+    else if (board) await board.noteTurn(AGENT, where(ctx), pids);
   });
   // 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) });
+  pi.on("turn_end", async (_event, ctx) => {
+    const board = await harness().catch(() => null);
+    if (board) tell(await board.boardNudgeIfChanged(AGENT), ctx);
+  });
+  pi.on("session_shutdown", () => { server?.child.kill(); server = null; });
+  pi.registerCommand("harness-reconnect", { description: "Reconnect Harness", handler: async (_args, ctx) => { connecting = null; await connect(ctx); } });
 }