tryharness 0.7.18 → 0.7.23

package/lib/swarm.mjs

@@ -1,24 +1,26 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { readRunSteps } from "./runner.mjs";
-import { mainCheckout } from "./worktrees.mjs";
 import { nameOf, resolveMember } from "./members.mjs";
-import { setNote, swarmBlock, swarmCards, swarmDigest } from "./cards.mjs";
+import { modelOf, setNote, swarmBlock, swarmCards, swarmDigest } from "./cards.mjs";
+import { DEFAULT_ROUTING, PICKABLE, choiceOf, listingOf, picksIn, routingOf, setChoice, setRouting } from "./models.mjs";
 
 // The person's swarm as threads. A thread is a goal under the hood: its room is the transcript, its team the agents in
 // it, its folder where coding agents work, and it runs on its own authority. A message the person sends wakes the
 // agents it names (or the only agent in the thread), each resuming its own session; their runs' steps are read back
 // from the run logs. The person's own terminal sessions are listed too and continue in a thread once idle.
 
-const PROCESS_NAMES = { "claude-code": "claude", codex: "codex", pi: "pi", opencode: "opencode" };
+export const PROCESS_NAMES = { "claude-code": "claude", codex: "codex", pi: "pi", opencode: "opencode" };
 const SAY_LIMIT = 4_000;
 const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
 
 // The id an agent resumes a session by: the index keys sessions by their file name.
 export function nativeSessionId(agent, sessionId) {
   const bare = String(sessionId).replace(/\.jsonl$/, "");
-  return agent === "codex" ? bare.match(UUID)?.[0] ?? bare : bare;
+  // Codex and pi name a session's file by its time and id; the id is what resumes it.
+  return agent === "codex" || agent === "pi" ? bare.match(UUID)?.[0] ?? bare : bare;
 }
 
 // The folder each running coding agent works in, by agent, leaving out the runs the daemon started itself.
@@ -50,7 +52,7 @@ export function agentProcessCwds(exclude = new Set()) {
   return cwds;
 }
 
-export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoard, goalCommand, stopThreadRuns, runLog, runningPids, provenanceFor, defaults, coordinator, worktrees, roster, authorizeRun }) {
+export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoard, goalCommand, stopThreadRuns, runLog, runningPids, provenanceFor, defaults, coordinator, worktrees, roster, authorizeRun, pickable, listModels, folders, runsIn, threadFiles = () => ({ files: [], rendering: [] }) }) {
   const awaitingStart = (run) => run.status === "open" && Boolean(run.run_workspace) && !run.run_authorized_at;
   const isDir = (folder) => typeof folder === "string" && path.isAbsolute(folder) && fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory();
   const agentsOf = (thread) => thread.goal.team.filter((agent) => agent !== thread.goal.facilitator);
@@ -116,19 +118,27 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
   // The agent a request names in `to`: null for none, false for one no thread can have.
   const recipient = (request) => (request.to == null || request.to === "" ? null : roomAgents.includes(String(request.to)) ? String(request.to) : false);
 
-  const lastFolder = (agent) => store.recentSessions(100).find((session) => session.agent === agent && isDir(session.cwd))?.cwd ?? null;
+  // A thread needs a folder when a coding agent is in it, or when no one is named and the coordinator picks who works.
+  const needsFolder = (team) => !team.length || team.some((name) => PROCESS_NAMES[name]);
+  // Where each coding agent in a thread would run its turn there: in T3 Code, or here, and why not T3 when the person uses it there.
+  // `lastWorked`: where its agent last worked, when Harness picked another folder from the message, for the person to take.
+  const placeOf = (folder, team, by, lastWorked = null) => ({ ok: true, folder, name: folder ? path.basename(folder) : null, by,
+    lastWorked: lastWorked ? { folder: lastWorked, name: path.basename(lastWorked) } : null,
+    runs: folder ? team.filter((name) => PROCESS_NAMES[name]).map((name) => ({ agent: name, ...runsIn(name, folder) })) : [] });
 
-  const read = (thread) => {
+  const read = (thread, hostedCaller = false) => {
     const runs = store.threadRuns(thread.id).map((run) => ({
       id: run.id, agent: run.claimed_by || run.target_agent, kind: run.kind, status: run.status, awaitingStart: awaitingStart(run), startedAt: run.created_at, endedAt: run.reported_at,
-      sessionId: run.session_id, folder: run.run_workspace, usage: run.usage,
+      sessionId: run.session_id, folder: run.run_workspace, usage: run.usage, model: run.run_model,
       steps: readRunSteps(runLog(run.id), 300).map((step) => ({ ...step, text: step.text.slice(0, SAY_LIMIT) })),
     }));
-    return { ok: true, thread: summary(thread), posts: store.roomPosts(thread.id, 0, 500), runs };
+    return { ok: true, thread: summary(thread), posts: store.roomPosts(thread.id, 0, 500), runs, ...threadFiles(thread, hostedCaller) };
   };
 
   // `to`: the one agent the person wrote to (the desktop's agent list), so their words go as written, with no @name.
   const post = (thread, text, to = null) => {
+    const picked = picksIn(store, text, roomAgents);
+    if (picked.error) return { ok: false, error: picked.error };
     // A new name in the person's message joins the thread.
     const joining = [...new Set([...mentionsIn(text, roomAgents), ...(to ? [to] : [])])].filter((agent) => !thread.goal.team.includes(agent));
     if (joining.length) store.setGoalTeam(thread.id, [...thread.goal.team, ...joining]);
@@ -160,6 +170,19 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       const agents = swarmCards(store, roster().filter((entry) => entry.id !== agent));
       return { ok: true, agents, text: swarmBlock(agents), digest: swarmDigest(agents) };
     }
+    // Each coding agent's models as it lists them, the person's choice for it and their routing words (models.mjs). Open
+    // to every caller, so an agent names a model that exists: post_task's model, or `@codex:model/effort` in a post.
+    if (command === "board.swarm.models") {
+      const named = request.target ? resolveMember(request.target) : null;
+      if (named && !named.ok) return { ok: false, error: `no agent called "${request.target}"` };
+      const ids = pickable().filter((id) => !named || id === named.id);
+      if (named && !ids.length) return { ok: false, error: `the relay sets the model of ${[...PICKABLE].join(", ")} when they are installed here, not ${nameOf(named.id)}` };
+      const listing = () => ({ ok: true, routing: routingOf(store), defaultRouting: DEFAULT_ROUTING, agents: ids.map((id) => {
+        const listed = listingOf(store, id);
+        return { id, name: nameOf(id), choice: choiceOf(store, id), ownModel: modelOf(id), listedAt: listed?.at ?? null, ...(listed?.error ? { error: listed.error } : {}), models: listed?.models ?? [] };
+      }) });
+      return request.refresh === true && agent === "user" ? { pending: listModels().then(listing) } : listing();
+    }
     // Any of the person's agents may start a thread and stop one it started. The thread carries the agent's trust, so
     // nothing in it runs without the person's Start, and one started through Harness gets no coordinator rounds (they
     // are paid) until the person sets a spend ceiling.
@@ -169,8 +192,10 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       const folder = request.folder ? String(request.folder) : null;
       if (folder && !isDir(folder)) return { ok: false, error: `${folder} is not an absolute path to a folder` };
       const team = new Set(mentionsIn(text, roomAgents));
+      const picked = picksIn(store, text, roomAgents);
+      if (picked.error) return { ok: false, error: picked.error };
       if (!team.size) return { ok: false, error: `name who the thread is for with @, one of: ${roomAgents.filter((name) => name !== agent && name !== "harness").join(", ")}` };
-      const objective = text.split("\n").map((line) => line.trim()).find(Boolean).replace(/@([a-z][a-z0-9-]*)\s*/g, "").slice(0, 120) || text.slice(0, 120);
+      const objective = text.split("\n").map((line) => line.trim()).find(Boolean).replace(/@([a-z][a-z0-9-]*)(:\S+)?\s*/g, "").slice(0, 120) || text.slice(0, 120);
       const thread = store.createGoal({ objective, originAgent: agent, provenance: provenanceFor(agent), team: [...team, agent, "harness"], facilitator: "harness", workspace: folder ? path.resolve(folder) : null, maxPosts: defaults.maxPosts, maxWakes: defaults.maxWakes });
       if (request.hostedCaller) store.meta(`hosted-thread:${thread.id}`, "1");
       const first = store.roomPost({ goalId: thread.id, author: agent, kind: "post", text, mentions: addressed(store.getTask(thread.id), text) });
@@ -186,12 +211,37 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       return { ok: true, thread: summary(store.getTask(thread.id)) };
     }
     if (agent !== "user") return { ok: false, error: "only the person writes in, stops or resumes a thread they did not start; post in it with post_to_room" };
+    // Where a thread works, for the composer (folders.mjs): the folders the person works in, any folder on the computer
+    // from a typed path, and where a message would work: the folder chosen (`folder`) or the one Harness suggests, and
+    // where each coding agent named in it (`text`, `to`, `agents`) runs its turns there.
+    if (command === "board.swarm.places") return { ok: true, places: folders.known(), home: os.homedir() };
+    if (command === "board.swarm.browse") return folders.browse(request.path);
+    if (command === "board.swarm.place") {
+      const text = String(request.text || "").slice(0, 20_000);
+      const to = recipient(request);
+      const team = [...new Set([...mentionsIn(text, roomAgents), ...(to ? [to] : []), ...(Array.isArray(request.agents) ? request.agents.map(String).filter((name) => roomAgents.includes(name)) : [])])];
+      if (request.folder) {
+        const folder = String(request.folder);
+        return isDir(folder) ? placeOf(path.resolve(folder), team, "you") : { ok: false, error: `${folder} is not a folder on this computer` };
+      }
+      if (!needsFolder(team)) return placeOf(null, team, null);
+      return { pending: folders.suggest(text, team).then(({ folder, by, lastWorked }) => placeOf(folder, team, by, lastWorked)) };
+    }
     // The person's own note on one agent's card ("use it for reviews"), told to every other agent; no text clears it.
     if (command === "board.swarm.note") {
       const named = resolveMember(request.target);
       if (!named.ok) return { ok: false, error: named.candidates.length ? `"${request.target}" could be ${named.candidates.join(" or ")}; name one` : `no agent called "${request.target}"` };
       return { ok: true, agent: named.id, note: setNote(store, named.id, request.text) };
     }
+    // The person's choice of model and effort for one agent: a model it lists, "auto", or "default" for its own settings.
+    if (command === "board.swarm.model") {
+      const named = resolveMember(request.target);
+      if (!named.ok || !PICKABLE.has(named.id)) return { ok: false, error: `the relay sets the model of ${[...PICKABLE].join(", ")}, not "${request.target}"` };
+      const set = setChoice(store, named.id, request.model, request.effort);
+      return set.ok ? { ok: true, agent: named.id, choice: set.choice } : set;
+    }
+    // The person's words on how Auto picks models for swarm work; no text goes back to the default words.
+    if (command === "board.swarm.routing") return { ok: true, routing: setRouting(store, request.text), defaultRouting: DEFAULT_ROUTING };
     // The coordinator's record: what each round saw, chose and cost. The evidence for its limits.
     if (command === "board.swarm.rounds") return { ok: true, rounds: store.rounds(request.id ? String(request.id) : null, request.limit) };
     if (command === "board.swarm.coordinator") {
@@ -211,6 +261,8 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       const to = recipient(request);
       if (to === false) return { ok: false, error: `${request.to} can't be written to in a thread` };
       const team = new Set([...mentionsIn(text, roomAgents), ...(to ? [to] : [])]);
+      const picked = picksIn(store, text, roomAgents);
+      if (picked.error) return { ok: false, error: picked.error };
       if (from) {
         const agentName = String(from.agent || ""), sessionId = String(from.sessionId || "");
         if (!PROCESS_NAMES[agentName]) return { ok: false, error: "only a coding agent's session continues in a thread" };
@@ -222,23 +274,23 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
         team.add(agentName);
         folder ??= isDir(session.cwd) ? session.cwd : null;
       }
-      // Where the work happens: the named agent's last folder, else the latest coding session's on this computer; one in
-      // a worktree (a thread's copy here, T3 Code's) is the repository's own checkout, where the person works.
-      const last = [...team].map((name) => PROCESS_NAMES[name] ? lastFolder(name) : null).find(Boolean)
-        ?? store.recentSessions(100).find((session) => PROCESS_NAMES[session.agent] && isDir(session.cwd))?.cwd ?? null;
-      folder ??= last ? mainCheckout(last) : null;
-      const objective = text.split("\n").map((line) => line.trim()).find(Boolean).replace(/@([a-z][a-z0-9-]*)\s*/g, "").slice(0, 120) || text.slice(0, 120);
-      const thread = store.createGoal({ objective, originAgent: "user", provenance: provenanceFor("user"), team: [...team, "harness"], facilitator: "harness", workspace: folder ? path.resolve(folder) : null, maxPosts: defaults.maxPosts, maxWakes: defaults.maxWakes });
-      if (from) { store.setGoalSession(thread.id, String(from.agent), nativeSessionId(String(from.agent), String(from.sessionId))); worktrees.inPlace(thread.id); }
-      const opened = store.getTask(thread.id);
-      const first = store.roomPost({ goalId: thread.id, author: "user", kind: "post", text, mentions: addressed(opened, text) });
-      wakeFor(thread.id, first, "user");
-      notifyBoard(store.getTask(thread.id));
-      return { ok: true, thread: summary(store.getTask(thread.id)) };
+      // Where the work happens: the folder the person chose, else one picked from what they wrote, else where its agent
+      // last worked (folders.mjs); never the home folder or a hidden one.
+      const begin = (where) => {
+        const objective = text.split("\n").map((line) => line.trim()).find(Boolean).replace(/@([a-z][a-z0-9-]*)(:\S+)?\s*/g, "").slice(0, 120) || text.slice(0, 120);
+        const thread = store.createGoal({ objective, originAgent: "user", provenance: provenanceFor("user"), team: [...new Set([...team, "harness"])], facilitator: "harness", workspace: where ? path.resolve(where) : null, maxPosts: defaults.maxPosts, maxWakes: defaults.maxWakes });
+        if (from) { store.setGoalSession(thread.id, String(from.agent), nativeSessionId(String(from.agent), String(from.sessionId))); worktrees.inPlace(thread.id); }
+        const opened = store.getTask(thread.id);
+        const first = store.roomPost({ goalId: thread.id, author: "user", kind: "post", text, mentions: addressed(opened, text) });
+        wakeFor(thread.id, first, "user");
+        notifyBoard(store.getTask(thread.id));
+        return { ok: true, thread: summary(store.getTask(thread.id)) };
+      };
+      return folder || !needsFolder([...team]) ? begin(folder) : { pending: folders.suggest(text, [...team]).then((suggested) => begin(suggested.folder)) };
     }
     const thread = store.getTask(String(request.id || ""));
     if (!thread || thread.kind !== "goal") return { ok: false, error: "thread not found" };
-    if (command === "board.swarm.read") return read(thread);
+    if (command === "board.swarm.read") return read(thread, request.hostedCaller === true);
     if (command === "board.swarm.diff") return worktrees.diff(thread.id, request.runId ? String(request.runId) : null);
     if (command === "board.swarm.merge" || command === "board.swarm.discard") {
       // Both change the person's repository, so both wait for the person, and never while an agent is changing files.
@@ -276,10 +328,21 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       notifyBoard(store.getTask(thread.id));
       return { ok: true, thread: summary(store.getTask(thread.id)) };
     }
+    // The person moves the thread to another folder between turns. Each agent starts a new session there, as a session
+    // and a T3 thread belong to the folder they ran in.
     if (command === "board.swarm.folder") {
       const folder = String(request.folder || "");
-      if (!isDir(folder)) return { ok: false, error: `${folder} is not an absolute path to a folder` };
-      store.setGoalFolder(thread.id, path.resolve(folder));
+      if (!isDir(folder)) return { ok: false, error: `${folder} is not a folder on this computer` };
+      const where = path.resolve(folder);
+      if (where === thread.goal.workspace) return { ok: true, thread: summary(thread) };
+      if (store.threadRuns(thread.id).some((run) => ["open", "claimed", "running"].includes(run.status))) return { ok: false, error: "an agent is still working in this thread; stop it or wait for it first" };
+      const moved = worktrees.moved(thread.id);
+      if (!moved.ok) return moved;
+      store.setGoalFolder(thread.id, where);
+      for (const name of Object.keys(thread.goal.sessions || {})) store.setGoalSession(thread.id, name, null);
+      for (const name of thread.goal.team) if (store.meta(`t3-thread:${thread.id}:${name}`)) store.meta(`t3-thread:${thread.id}:${name}`, "");
+      store.roomPost({ goalId: thread.id, author: "user", kind: "note", text: `Now working in ${where}.` });
+      notifyBoard(store.getTask(thread.id));
       return { ok: true, thread: summary(store.getTask(thread.id)) };
     }
     return { ok: false, error: "unknown command" };

package/lib/t3.mjs

@@ -201,7 +201,7 @@ function stepOf(item) {
 /**
  * A coding agent's turn in a Harness thread, carried out by T3 Code, so the person finds it in T3 like any thread there.
  * The agent's first turn launches its own T3 thread (`launch`: T3's project, workspace and the model the person last
- * chose for the agent there; T3 applies the mode the person approved Harness with); later turns go into that thread,
+ * chose for the agent there, unless the relay chose one, `model`; T3 applies the mode the person approved Harness with); later turns go into that thread,
  * queued behind whatever it is doing. It reports as runner.mjs does: accepted, its session (the T3 thread, which is
  * how Open finds it), each step, then done with the agent's last words or failed; Stop interrupts it in T3.
  */
@@ -245,9 +245,12 @@ export function runInT3(run, emit, observe) {
   emit("accepted");
   void (async () => {
     try {
-      if (threadId) runId = (await t3Tool("t3_thread_send", { threadId, message: run.brief, mode: "queue", clientRequestId: run.runId })).runId ?? null;
-      else {
-        const launched = await t3Tool("t3_thread_launch", { title: run.title, message: run.brief, ...run.launch });
+      // A model the relay chose for this turn (models.mjs) is the thread's selection from this turn on.
+      if (threadId) {
+        if (run.model) await t3Tool("t3_thread_configure", { threadId, modelSelection: run.model });
+        runId = (await t3Tool("t3_thread_send", { threadId, message: run.brief, mode: "queue", clientRequestId: run.runId })).runId ?? null;
+      } else {
+        const launched = await t3Tool("t3_thread_launch", { title: run.title, message: run.brief, ...run.launch, ...(run.model ? { modelSelection: run.model } : {}) });
         threadId = launched.threadId;
         runId = launched.runId ?? null;
         run.onThread?.(threadId);

package/lib/trails.mjs

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+
+// What a coding session actually did, read from the agent's own session file: the person's first request, every tool
+// call in order (the paths it named, the files it changed, commands with their exit codes) and the tokens each model
+// call used. This is the record the context engine learns from (what a run needed against what its brief carried) and
+// the evidence receipts check claims against. Read only; the parsers never decide anything about intent.
+
+const PATH_TOKEN = /(?:\.{0,2}\/)?[\w@+-][\w@+.-]*(?:\/[\w@+.-]+)+|[\w@+-][\w@+-]*\.[A-Za-z][A-Za-z0-9]{0,7}\b/g;
+const PATCH_FILE = /\*\*\* (?:Update|Add|Delete) File: ([^\n"\\]+)/g;
+const REDIRECT_FILE = /(?:^|[\s;&|])(?:>>?|tee(?:\s+-a)?)\s+(["']?)([^\s"'|;&<>]+)\1/g;
+const SED_INPLACE = /\bsed\s+(?:-[a-zA-Z]*i[a-zA-Z]*(?:\s+''|\s+"")?|--in-place)\b[^|;&]*?\s(["']?)([^\s"'|;&]+)\1\s*(?:$|[|;&])/gm;
+// Test runners by their command, for receipts: a command's own exit code is the evidence, never the agent's words.
+const TEST_COMMAND = /\b(?:npm(?:\s+run)?\s+(?:test|smoke|e2e|eval|lint|typecheck)|npx\s+(?:jest|vitest|tsx\s+tests\/|playwright\s+test)|jest|vitest|pytest|cargo\s+(?:test|check|clippy)|go\s+test|forge\s+test|bun\s+test|deno\s+test|swift\s+test|mvn\s+test|gradlew?\s+test|make\s+(?:test|check)|node\s+(?:--test\b|[\w./-]*\btests?\/)|tsc(?:\s|$))/;
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "edit", "write", "apply_patch"]);
+const BRIEF_SKIP = /^<(?:command-|local-command|system-reminder|task-notification|user-prompt-submit-hook)|^Caveat:/;
+
+const parseJson = (line) => { try { const value = JSON.parse(line); return value && typeof value === "object" ? value : null; } catch { return null; } };
+const textOf = (content) => typeof content === "string" ? content
+  : Array.isArray(content) ? content.map((part) => (typeof part?.text === "string" ? part.text : "")).filter(Boolean).join("\n") : "";
+const ms = (value) => { const at = typeof value === "number" ? value * (value < 1e12 ? 1000 : 1) : Date.parse(value); return Number.isFinite(at) ? at : null; };
+
+/** Path-like words in a tool call's input or output, as written (relative or absolute). */
+export function pathTokens(text) {
+  return [...new Set(String(text).match(PATH_TOKEN) || [])].map((token) => token.replace(/[.,:;)\]}'"`]+$/, "")).filter((token) => token.length > 2 && token.length < 300);
+}
+
+/** Files a tool call changed: edit tools' own paths, patch headers, sed -i, redirects and tee. */
+export function editedPaths(tool, input) {
+  const out = new Set();
+  if (EDIT_TOOLS.has(tool) && typeof input?.file_path === "string") out.add(input.file_path);
+  if (EDIT_TOOLS.has(tool) && typeof input === "string") { const found = input.match(/"(?:file_path|path)":"([^"]+)"/); if (found && !found[1].endsWith("…")) out.add(found[1]); }
+  if (EDIT_TOOLS.has(tool) && typeof input?.path === "string") out.add(input.path);
+  if (tool === "NotebookEdit" && typeof input?.notebook_path === "string") out.add(input.notebook_path);
+  const text = typeof input === "string" ? input : JSON.stringify(input ?? "").replace(/\\n/g, "\n").replace(/\\"/g, "\"");
+  for (const match of text.matchAll(PATCH_FILE)) out.add(match[1].trim());
+  for (const match of text.matchAll(SED_INPLACE)) out.add(match[2]);
+  for (const match of text.matchAll(REDIRECT_FILE)) if (!/^\/dev\/|^&\d$/.test(match[2])) out.add(match[2]);
+  return [...out];
+}
+
+export const isTestCommand = (command) => TEST_COMMAND.test(String(command));
+
+function exitCodeOf(text) {
+  const found = String(text).match(/"?exit_code"?\s*[:=]\s*(-?\d+)|Exit code:?\s*(-?\d+)|Process exited with code (-?\d+)/i);
+  return found ? Number(found[1] ?? found[2] ?? found[3]) : null;
+}
+
+/**
+ * A session's trail: { agent, sessionId, cwd, brief, startedAt, endedAt, calls, usage, turns }. A call is
+ * { at, tool, input (clipped text), named (path words), edited (paths), command, exitCode, error }; usage is one row
+ * per model call { at, input, cached, output }; turns are the person's messages and stops, { at, interrupted }. Claude Code and Codex are read in full; other agents fall back to none.
+ */
+export async function readTrail(agent, file) {
+  if (!["claude-code", "codex"].includes(agent) || !fs.existsSync(file)) return null;
+  const trail = { agent, sessionId: null, cwd: null, brief: null, startedAt: null, endedAt: null, calls: [], usage: [], turns: [] };
+  const byId = new Map();
+  const add = (at, tool, input, id) => {
+    const text = typeof input === "string" ? input : JSON.stringify(input ?? {});
+    const command = typeof input?.command === "string" ? input.command : Array.isArray(input?.command) ? input.command.join(" ") : typeof input?.cmd === "string" ? input.cmd
+      : [...text.matchAll(/cmd\s*:\s*"((?:[^"\\]|\\.)*)"/g)].map((match) => match[1]).join("\n") || null;
+    const call = { at, tool, input: text.slice(0, 4_000), named: pathTokens(text), edited: editedPaths(tool, input), command, exitCode: null, error: false, output: "" };
+    trail.calls.push(call);
+    if (id) byId.set(id, call);
+  };
+  const result = (id, text, error) => {
+    const call = byId.get(id);
+    if (!call) return;
+    call.output = String(text).slice(0, 4_000);
+    call.named = [...new Set([...call.named, ...pathTokens(String(text).slice(0, 20_000))])];
+    call.exitCode = exitCodeOf(text);
+    call.error = Boolean(error) || (call.exitCode !== null && call.exitCode !== 0);
+  };
+  const lines = readline.createInterface({ input: fs.createReadStream(file, { encoding: "utf8" }), crlfDelay: Infinity });
+  for await (const line of lines) {
+    const row = parseJson(line);
+    if (!row) continue;
+    const at = ms(row.timestamp ?? row.payload?.timestamp);
+    if (at) { trail.startedAt ??= at; trail.endedAt = at; }
+    if (agent === "claude-code") {
+      trail.sessionId ??= row.sessionId ?? null;
+      trail.cwd ??= row.cwd ?? null;
+      const content = row.message?.content;
+      if (row.type === "user" && !row.isMeta) {
+        const words = (typeof content === "string" ? content : Array.isArray(content) && !content.some((part) => part?.type === "tool_result") ? textOf(content) : "").trim();
+        // The person's turns: each message starts one; Esc leaves "[Request interrupted by user...]" where it stopped one.
+        if (words.startsWith("[Request interrupted by user")) trail.turns.push({ at, interrupted: true });
+        else if (words && !BRIEF_SKIP.test(words)) { trail.turns.push({ at, interrupted: false }); trail.brief ??= words; }
+      }
+      if (Array.isArray(content)) for (const part of content) {
+        if (part?.type === "tool_use") add(at, part.name, part.input, part.id);
+        if (part?.type === "tool_result") result(part.tool_use_id, textOf(part.content) || JSON.stringify(row.toolUseResult ?? ""), part.is_error);
+      }
+      const usage = row.type === "assistant" ? row.message?.usage : null;
+      if (usage) trail.usage.push({ at, input: (usage.input_tokens || 0) + (usage.cache_creation_input_tokens || 0) + (usage.cache_read_input_tokens || 0), cached: usage.cache_read_input_tokens || 0, output: usage.output_tokens || 0 });
+    } else {
+      const payload = row.payload ?? {};
+      if (row.type === "session_meta") { trail.sessionId ??= payload.id ?? null; trail.cwd ??= payload.cwd ?? null; }
+      if (row.type === "response_item" && payload.type === "message" && payload.role === "user") {
+        const words = textOf(payload.content).trim();
+        if (words && !/^<(?:environment_context|user_instructions|permissions|turn_aborted)/.test(words) && !words.startsWith("# AGENTS.md")) { trail.turns.push({ at, interrupted: false }); trail.brief ??= words; }
+      }
+      if (row.type === "event_msg" && payload.type === "turn_aborted" && payload.reason === "interrupted") trail.turns.push({ at, interrupted: true });
+      if (row.type === "response_item" && ["function_call", "custom_tool_call", "local_shell_call"].includes(payload.type)) {
+        const input = payload.input ?? parseJson(payload.arguments) ?? payload.arguments ?? payload.action;
+        add(at, payload.name ?? payload.type, input, payload.call_id);
+      }
+      if (row.type === "response_item" && ["function_call_output", "custom_tool_call_output"].includes(payload.type)) {
+        const text = typeof payload.output === "string" ? payload.output : textOf(payload.output) || JSON.stringify(payload.output ?? "");
+        result(payload.call_id, text, false);
+      }
+      if (row.type === "token_usage_record" && payload.usage) trail.usage.push({ at, input: payload.usage.input_tokens || 0, cached: payload.usage.cached_input_tokens || 0, output: payload.usage.output_tokens || 0 });
+    }
+  }
+  return trail;
+}
+
+const RESULT_EDIT = /(?:The file (\S+) has been (?:updated|created)|File created successfully at: (\S+?)[\s)\]])/g;
+
+/**
+ * A trail rebuilt from the relay's own copy of a session (store.mjs keeps every message with tool calls clipped), for
+ * sessions whose source file the agent has since deleted. It has the brief, the calls with the paths they named and the
+ * files they changed (the edit tools' own confirmations carry the whole path), but no token counts or timestamps.
+ */
+export function trailFromTranscript(agent, transcript, { cwd = null, startedAt = null } = {}) {
+  const trail = { agent, sessionId: null, cwd, brief: null, startedAt, endedAt: startedAt, calls: [], usage: [] };
+  for (const block of String(transcript).split(/\n\n(?=(?:User|Agent): )/)) {
+    const user = block.startsWith("User: ");
+    const text = block.replace(/^(?:User|Agent): /, "");
+    if (user && !trail.brief && !text.startsWith("[tool result") && !BRIEF_SKIP.test(text.trim()) && !text.includes("<local-command-caveat>")) trail.brief = text.trim();
+    for (const match of text.matchAll(/\[tool: (\S+) ([\s\S]*?)\](?=\n|$)/g)) {
+      trail.calls.push({ at: null, tool: match[1], input: match[2], named: pathTokens(match[2]), edited: editedPaths(match[1], match[2]).filter((file) => !file.endsWith("…")), command: null, exitCode: null, error: false, output: "" });
+    }
+    if (user && text.startsWith("[tool result")) {
+      const last = trail.calls.at(-1);
+      if (!last) continue;
+      last.named = [...new Set([...last.named, ...pathTokens(text)])];
+      for (const match of text.matchAll(RESULT_EDIT)) last.edited = [...new Set([...last.edited, match[1] || match[2]])];
+    }
+  }
+  return trail;
+}
+
+/** A path as written in a call, made relative to root when it lies inside it; null when it points elsewhere. */
+export function insideRoot(token, root, cwd = root) {
+  const absolute = path.isAbsolute(token) ? token : path.resolve(cwd || root, token);
+  const rel = path.relative(root, absolute);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : null;
+}
+
+/**
+ * What a trail shows a run needed, against the files that existed: { edited, read, firstEditAt, beforeFirstEdit }.
+ * `read` is every existing file the run named before its first edit (opened, listed, grepped into); `beforeFirstEdit`
+ * counts the calls and tokens spent before that edit, which is what a better brief can save.
+ */
+export function needs(trail, root, files) {
+  const known = (token) => { const rel = insideRoot(token, root, trail.cwd); return rel && files.has(rel) ? rel : null; };
+  const edited = new Set();
+  const read = new Set();
+  let firstEditAt = null;
+  let editing = false;
+  let callsBefore = 0;
+  for (const call of trail.calls) {
+    const changed = call.edited.map(known).filter(Boolean);
+    if (changed.length && !editing) { editing = true; firstEditAt = call.at; }
+    for (const file of changed) edited.add(file);
+    if (!editing) { callsBefore += 1; for (const token of call.named) { const file = known(token); if (file) read.add(file); } }
+  }
+  const before = trail.usage.filter((row) => !editing || firstEditAt === null || (row.at ?? 0) < firstEditAt);
+  return {
+    edited: [...edited], read: [...read], firstEditAt,
+    beforeFirstEdit: { calls: callsBefore, modelCalls: before.length, inputTokens: before.reduce((sum, row) => sum + row.input, 0),
+      uncachedInputTokens: before.reduce((sum, row) => sum + Math.max(0, row.input - row.cached), 0), outputTokens: before.reduce((sum, row) => sum + row.output, 0),
+      ms: firstEditAt !== null && trail.startedAt !== null ? firstEditAt - trail.startedAt : null },
+  };
+}

package/lib/watches.mjs

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+// Watches: something the person wants kept an eye on, read by a command on this computer on a schedule (a log, a status
+// command, a balance), and said out loud only when it is off. Each check reads one number from the command's output (a
+// field like "ageSeconds" or the count of lines matching a pattern like "critical") and compares it with a limit the
+// watch names, or, without one, with its own usual range once it has enough history. A falling number with a floor gets
+// a run-out estimate. Plain arithmetic, no model. An agent may suggest a watch; it runs only once the person starts it.
+// The October 13 keeper outage is why: its own health job logged "no recent successful keeper run" every 5 minutes for
+// 41 hours and nobody saw it.
+
+const HISTORY = 500;
+const USUAL_AFTER = 12;
+const MIN_EVERY_SECONDS = 5;
+const RUN_OUT_HOURS = 24;
+
+const median = (values) => { const sorted = [...values].sort((a, b) => a - b); const mid = sorted.length >> 1; return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2; };
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The number a check reads from output: how many lines hold a phrase (count), seconds since a named field's last
+ * timestamp (age: unix seconds, milliseconds or an ISO date), a named field's last value (field), or the last number in
+ * it. null when absent.
+ */
+export function readNumber(output, measure, now = Date.now()) {
+  const text = String(output ?? "");
+  if (measure.count) return text.split("\n").filter((line) => line.toLowerCase().includes(String(measure.count).toLowerCase())).length;
+  if (measure.age) {
+    const found = [...text.matchAll(new RegExp(`["']?${escape(measure.age)}["']?\\s*[:=]\\s*"?([0-9][0-9:.TZ+-]*)`, "g"))].at(-1)?.[1];
+    if (!found) return null;
+    const at = /^\d+(?:\.\d+)?$/.test(found) ? Number(found) * (Number(found) < 1e12 ? 1000 : 1) : Date.parse(found);
+    return Number.isFinite(at) ? Math.max(0, Math.round((now - at) / 1000)) : null;
+  }
+  if (measure.field) {
+    const found = [...text.matchAll(new RegExp(`["']?${escape(measure.field)}["']?\\s*[:=]\\s*"?(-?\\d+(?:\\.\\d+)?)`, "g"))].at(-1);
+    return found ? Number(found[1]) : null;
+  }
+  const found = text.match(/-?\d+(?:\.\d+)?(?=\D*$)/);
+  return found ? Number(found[0]) : null;
+}
+
+/**
+ * Whether the newest sample is off, and why: past a limit the watch names, outside its usual range (median and spread of
+ * its history, once it has some), or, falling toward its floor, due to cross it within a day. null when it is fine.
+ */
+export function offPattern(samples, { above = null, below = null } = {}) {
+  const values = samples.map((sample) => sample.value).filter((value) => value !== null && Number.isFinite(value));
+  const latest = samples.at(-1);
+  if (!latest || latest.value === null) return latest?.error ? { kind: "failed", text: `its check failed: ${latest.error}` } : null;
+  if (above !== null && latest.value > above) return { kind: "limit", text: `is ${latest.value}, above ${above}` };
+  if (below !== null && latest.value < below) return { kind: "limit", text: `is ${latest.value}, below ${below}` };
+  if (below !== null && samples.length >= 4) {
+    // Falling toward the floor: a straight line through the recent samples, and when it reaches it.
+    const recent = samples.slice(-12).filter((sample) => sample.value !== null);
+    const t0 = recent[0].at;
+    const xs = recent.map((sample) => (sample.at - t0) / 3_600_000), ys = recent.map((sample) => sample.value);
+    const mx = xs.reduce((a, b) => a + b, 0) / xs.length, my = ys.reduce((a, b) => a + b, 0) / ys.length;
+    const slope = xs.reduce((sum, x, i) => sum + (x - mx) * (ys[i] - my), 0) / (xs.reduce((sum, x) => sum + (x - mx) ** 2, 0) || 1);
+    if (slope < 0) {
+      const hours = (latest.value - below) / -slope;
+      if (hours <= RUN_OUT_HOURS) return { kind: "run-out", text: `is falling by ${Math.abs(slope).toPrecision(2)} an hour and reaches ${below} in about ${hours < 1 ? `${Math.max(1, Math.round(hours * 60))} minutes` : `${Math.round(hours)} hour${Math.round(hours) === 1 ? "" : "s"}`}` };
+    }
+  }
+  if (above === null && below === null && values.length > USUAL_AFTER) {
+    const history = values.slice(0, -1).slice(-100);
+    const middle = median(history);
+    // A number that takes two values (a sawtooth, a flag) has no median deviation; the mean deviation stands in.
+    const deviations = history.map((value) => Math.abs(value - middle));
+    const spread = median(deviations) || deviations.reduce((a, b) => a + b, 0) / deviations.length || Math.max(1e-9, Math.abs(middle) * 0.05);
+    if (Math.abs(latest.value - middle) > 6 * spread) return { kind: "unusual", text: `is ${latest.value}; it is usually about ${Number(middle.toPrecision(4))}` };
+  }
+  return null;
+}
+
+/** Runs a check's command in its folder; its output, or an error. A check never runs longer than its own interval. */
+function runCheck(watch, shell = process.env.SHELL || "/bin/sh") {
+  return new Promise((resolve) => {
+    const started = performance.now();
+    let out = "", err = "", done = false;
+    const child = spawn(shell, ["-lc", watch.command], { cwd: watch.folder || undefined, stdio: ["ignore", "pipe", "pipe"] });
+    const timer = setTimeout(() => { child.kill("SIGKILL"); finish(null, `it took longer than its ${watch.everySeconds} s interval`); }, watch.everySeconds * 1000);
+    const finish = (output, error) => { if (done) return; done = true; clearTimeout(timer); resolve({ output, error, ms: Math.round(performance.now() - started) }); };
+    child.stdout.on("data", (chunk) => { out = (out + chunk).slice(-200_000); });
+    child.stderr.on("data", (chunk) => { err = (err + chunk).slice(-4_000); });
+    child.on("error", (error) => finish(null, error.message));
+    child.on("close", (code) => finish(code === 0 || out ? out : null, code === 0 || out ? null : (err.trim().split("\n").at(-1) || `it exited with code ${code}`)));
+  });
+}
+
+export function createWatches({ store, notify = () => {}, log = () => {}, run = runCheck }) {
+  const list = () => { try { return JSON.parse(store.meta("watches") || "[]"); } catch { return []; } };
+  const save = (watches) => store.meta("watches", JSON.stringify(watches));
+  const samplesOf = (id) => { try { return JSON.parse(store.meta(`watch-samples:${id}`) || "[]"); } catch { return []; } };
+  const timers = new Map();
+
+  const check = async (id) => {
+    const watch = list().find((entry) => entry.id === id);
+    if (!watch || watch.state !== "on") return null;
+    const result = await run(watch);
+    const value = result.output === null ? null : readNumber(result.output, watch.measure);
+    const samples = [...samplesOf(id), { at: Date.now(), value, ms: result.ms, ...(result.error ? { error: result.error.slice(0, 300) } : value === null ? { error: "its output had no number to read" } : {}) }].slice(-HISTORY);
+    store.meta(`watch-samples:${id}`, JSON.stringify(samples));
+    const off = offPattern(samples, watch.measure);
+    const current = list().find((entry) => entry.id === id);
+    if (!current) return null;
+    // Said once when it goes off and once when it is back; not on every check while it stays off.
+    if (off && !current.off) {
+      const alert = { at: new Date().toISOString(), text: `${current.name} ${off.text}.`, kind: off.kind };
+      save(list().map((entry) => (entry.id === id ? { ...entry, off: alert } : entry)));
+      store.meta("watch-alerts", JSON.stringify([...(JSON.parse(store.meta("watch-alerts") || "[]")), { watch: id, ...alert }].slice(-200)));
+      notify(alert.text, { watch: current, alert });
+      log(`watch ${current.name}: ${off.text}`);
+    } else if (!off && current.off) {
+      save(list().map((entry) => (entry.id === id ? { ...entry, off: null } : entry)));
+      notify(`${current.name} is back to normal.`, { watch: current, alert: null });
+    }
+    return { value, off, ms: result.ms };
+  };
+
+  const schedule = (watch) => {
+    clearTimeout(timers.get(watch.id));
+    if (watch.state !== "on") { timers.delete(watch.id); return; }
+    const tick = () => { void check(watch.id).catch((error) => log(`watch ${watch.name}: ${error.message}`)).finally(() => { if (timers.has(watch.id)) timers.set(watch.id, setTimeout(tick, watch.everySeconds * 1000).unref?.() ?? null); }); };
+    timers.set(watch.id, setTimeout(tick, 0));
+  };
+
+  return {
+    list: () => list().map((watch) => ({ ...watch, samples: samplesOf(watch.id).slice(-20) })),
+    alerts: (since = "") => { try { return JSON.parse(store.meta("watch-alerts") || "[]").filter((alert) => alert.at > since); } catch { return []; } },
+    /** A new watch: the person's starts at once; an agent's waits for the person's start. */
+    add({ name, command, folder = null, everySeconds = 300, measure = {}, by = "user" }) {
+      if (!String(name || "").trim() || !String(command || "").trim()) return { ok: false, error: "a watch needs a name and a command to read" };
+      const every = Math.max(MIN_EVERY_SECONDS, Math.round(Number(everySeconds) || 300));
+      const clean = {
+        ...(measure.field ? { field: String(measure.field).slice(0, 100) } : {}), ...(measure.count ? { count: String(measure.count).slice(0, 100) } : {}), ...(measure.age ? { age: String(measure.age).slice(0, 100) } : {}),
+        above: Number.isFinite(Number(measure.above)) && measure.above !== null && measure.above !== "" ? Number(measure.above) : null,
+        below: Number.isFinite(Number(measure.below)) && measure.below !== null && measure.below !== "" ? Number(measure.below) : null,
+      };
+      const watch = { id: randomUUID(), name: String(name).trim().slice(0, 120), command: String(command).slice(0, 2_000), folder, everySeconds: every, measure: clean, by, state: by === "user" ? "on" : "suggested", off: null, createdAt: new Date().toISOString() };
+      save([...list(), watch]);
+      if (watch.state === "on") schedule(watch);
+      return { ok: true, watch };
+    },
+    start(id) {
+      const watch = list().find((entry) => entry.id === id);
+      if (!watch) return { ok: false, error: "no such watch" };
+      const on = { ...watch, state: "on" };
+      save(list().map((entry) => (entry.id === id ? on : entry)));
+      schedule(on);
+      return { ok: true, watch: on };
+    },
+    remove(id) {
+      if (!list().some((entry) => entry.id === id)) return { ok: false, error: "no such watch" };
+      clearTimeout(timers.get(id)); timers.delete(id);
+      save(list().filter((entry) => entry.id !== id));
+      store.meta(`watch-samples:${id}`, "[]");
+      return { ok: true };
+    },
+    check,
+    resume() { for (const watch of list()) if (watch.state === "on") schedule(watch); },
+    stop() { for (const timer of timers.values()) clearTimeout(timer); timers.clear(); },
+  };
+}