tryharness 0.7.7 → 0.7.9

package/lib/live.mjs

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

package/lib/mcp-stdio.mjs

@@ -135,7 +135,7 @@ const BOARD_CALLS = {
   list_tasks: (args) => ({ command: "board.list", status: args.status, all: args.all === true }),
   get_task: (args) => ({ command: "board.get", id: String(args.id || "") }),
   post_task: (args) => ({ command: "board.post", objective: args.objective, brief: args.brief, targetAgent: args.target_agent, targetAgents: args.target_agents, parentId: args.parent_id, contextRefs: args.context_refs, runWorkspace: args.run_workspace, inSession: args.in_session === true, posterCwd: process.cwd(), posterPid: process.ppid }),
-  claim_task: (args) => ({ command: "board.claim", id: String(args.id || ""), expectedVersion: args.expected_version, leaseMinutes: args.lease_minutes }),
+  claim_task: (args) => ({ command: "board.claim", id: String(args.id || ""), expectedVersion: args.expected_version, leaseMinutes: args.lease_minutes, claimerPid: process.ppid }),
   report_task: (args) => args.status === "answered"
     ? { command: "board.answer", id: String(args.id || ""), answer: args.result, expectedVersion: args.expected_version }
     : args.status === "released"

package/lib/nudge.mjs

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

package/lib/phones.mjs

@@ -24,6 +24,8 @@ const PHONE_COMMANDS = new Set([
   "board.goal.list", "board.goal.get", "board.goal.stop", "board.room.read",
   "board.swarm.list", "board.swarm.read", "board.swarm.start", "board.swarm.post", "board.swarm.stop", "board.swarm.stop_all", "board.swarm.resume", "board.swarm.folder", "board.swarm.coordinator",
   "board.swarm.diff", "board.swarm.merge", "board.swarm.discard", "board.swarm.start_run",
+  // The person's own running sessions, read and messaged as from the desktop app; never queued (a session may be gone).
+  "board.live", "board.live.read", "board.live.say",
 ]);
 // What the chat owner does on the board, in Harness's name (was src/server/mcp/board.ts HARNESS_COMMANDS).
 const HARNESS_COMMANDS = new Set([

package/lib/places.mjs

@@ -0,0 +1,297 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+
+// Where a coding session runs, and how it opens there again. A session's place comes from its own environment: the
+// Harness piece inside the agent sends it when the session starts (the Claude Code and Codex hooks, nudge.mjs; the
+// opencode plugin; the pi extension), or the daemon reads it from the running process when nothing did. Terminals and
+// editors put their own ids into everything they start, the same on every OS (TERM_PROGRAM, TMUX_PANE, WEZTERM_PANE,
+// KITTY_WINDOW_ID, VSCODE_GIT_ASKPASS_NODE: the editor's own install); macOS adds the app (__CFBundleIdentifier).
+//
+// Any other agent (a custom harness) does the same with one line to the daemon's socket as a session starts:
+//   {"command":"board.live.place","agent":"<its id>","sessionId":"<id>","folder":"<absolute path>","pids":[<its pid>],
+//    "env":{<its environment>},"reopen":{"link":"http://127.0.0.1:<port>/…","command":"<what a person types to resume>"}}
+// `reopen` is optional: a page it serves on this computer opens directly; a command is only ever copied for the person
+// to paste, never run. Only PLACE_ENV is kept of `env`.
+
+const PS = ["/bin/ps", "/usr/bin/ps"].find((file) => fs.existsSync(file)) || "ps";
+
+/** The names a place is read from: nothing else of a session's environment is kept. */
+export const PLACE_ENV = ["__CFBundleIdentifier", "TERM_PROGRAM", "TMUX", "TMUX_PANE", "WEZTERM_PANE", "KITTY_WINDOW_ID", "KITTY_LISTEN_ON", "WT_SESSION", "VSCODE_GIT_ASKPASS_NODE", "CLAUDE_CODE_ENTRYPOINT", "T3CODE_CLI_PATH"];
+
+export function placeEnv(env) {
+  const picked = {};
+  for (const name of PLACE_ENV) if (typeof env?.[name] === "string" && env[name] && env[name].length <= 1024) picked[name] = env[name];
+  return picked;
+}
+
+/** A running process's environment, as far as this OS shows another process's (Linux /proc, macOS ps); {} elsewhere. */
+export function processEnv(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return {};
+  if (process.platform === "linux") {
+    try {
+      return placeEnv(Object.fromEntries(fs.readFileSync(`/proc/${pid}/environ`, "utf8").split("\0").filter((entry) => entry.includes("="))
+        .map((entry) => [entry.slice(0, entry.indexOf("=")), entry.slice(entry.indexOf("=") + 1)])));
+    } catch { return {}; }
+  }
+  if (process.platform !== "darwin") return {};
+  // `ps eww` prints the command, then each variable as NAME=value, space separated (values may hold spaces).
+  const line = spawnSync(PS, ["eww", "-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 3_000 }).stdout || "";
+  const env = {};
+  for (const name of PLACE_ENV) {
+    const found = line.match(new RegExp(`(?:^|\\s)${name}=(.*?)(?=\\s[A-Za-z_][A-Za-z0-9_]*=|\\s*$)`));
+    if (found?.[1]) env[name] = found[1];
+  }
+  return placeEnv(env);
+}
+
+export const appDirs = () => (process.env.HARNESS_APP_DIRS ? process.env.HARNESS_APP_DIRS.split(path.delimiter) : ["/Applications", path.join(os.homedir(), "Applications")]);
+
+// ── Editors built on VS Code ──────────────────────────────────────────────────
+
+/** Each one's app, link scheme, command-line tool, settings folder and extensions folder. */
+const EDITORS = [
+  { id: "cursor", name: "Cursor", bundle: "com.todesktop.230313mzl4w4u92", match: /cursor/i, scheme: "cursor", cli: "cursor", data: "Cursor", extensions: ".cursor" },
+  { id: "windsurf", name: "Windsurf", bundle: "com.exafunction.windsurf", match: /windsurf/i, scheme: "windsurf", cli: "windsurf", data: "Windsurf", extensions: ".windsurf" },
+  { id: "vscode-insiders", name: "Visual Studio Code - Insiders", bundle: "com.microsoft.VSCodeInsiders", match: /insiders/i, scheme: "vscode-insiders", cli: "code-insiders", data: "Code - Insiders", extensions: ".vscode-insiders" },
+  { id: "vscode", name: "Visual Studio Code", bundle: "com.microsoft.VSCode", match: /visual studio code|microsoft vs code|[\\/]code[\\/]/i, scheme: "vscode", cli: "code", data: "Code", extensions: ".vscode" },
+];
+export const EDITOR_IDS = EDITORS.map((editor) => editor.id);
+const editorById = (id) => EDITORS.find((editor) => editor.id === id) ?? null;
+export const editorName = (id) => editorById(id)?.name ?? null;
+
+/** An editor's install with its command-line tool, from a path inside it (or where its installer puts it). */
+export function editorInstall(editorId, hint = "") {
+  const editor = editorById(editorId);
+  if (!editor) return null;
+  const tries = [];
+  const app = String(hint).match(/^(.*?\.app)(?:\/|$)/)?.[1];
+  if (app) tries.push({ app, cli: path.join(app, "Contents", "Resources", "app", "bin", editor.cli) });
+  // Linux and Windows: the editor's executable sits beside its bin folder.
+  else if (hint && path.isAbsolute(hint)) tries.push({ app: path.dirname(hint), cli: path.join(path.dirname(hint), "bin", editor.cli + (process.platform === "win32" ? ".cmd" : "")) });
+  for (const dir of appDirs()) {
+    const at = path.join(dir, `${editor.name}.app`);
+    tries.push({ app: at, cli: path.join(at, "Contents", "Resources", "app", "bin", editor.cli) });
+  }
+  return tries.find((entry) => fs.existsSync(entry.cli)) ?? null;
+}
+
+function editorData(editor) {
+  if (process.env.HARNESS_EDITOR_ROOT) return path.join(process.env.HARNESS_EDITOR_ROOT, editor.data);
+  if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Application Support", editor.data);
+  if (process.platform === "win32") return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), editor.data);
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), editor.data);
+}
+
+/** Whether an editor has an extension installed (and not marked for removal). */
+export function editorHas(editorId, extension) {
+  const editor = editorById(editorId);
+  if (!editor) return false;
+  const dir = path.join(process.env.HARNESS_EDITOR_ROOT || os.homedir(), editor.extensions, "extensions");
+  let removed = {};
+  try { removed = JSON.parse(fs.readFileSync(path.join(dir, ".obsolete"), "utf8")); } catch {}
+  try { return fs.readdirSync(dir).some((name) => name.toLowerCase().startsWith(`${extension}-`) && !removed[name]); } catch { return false; }
+}
+
+/**
+ * The folder the person opens in an editor that holds `folder`: the deepest one the editor has a record of (it keeps one
+ * per folder it opened, User/workspaceStorage/<id>/workspace.json), else the folder itself.
+ */
+export function editorFolder(editorId, folder) {
+  const editor = editorById(editorId);
+  if (!editor || !folder) return folder || null;
+  const root = path.join(editorData(editor), "User", "workspaceStorage");
+  let best = null;
+  let dirs = [];
+  try { dirs = fs.readdirSync(root); } catch {}
+  for (const dir of dirs) {
+    let opened;
+    try { opened = fileURLToPath(JSON.parse(fs.readFileSync(path.join(root, dir, "workspace.json"), "utf8")).folder); } catch { continue; }
+    if ((folder === opened || folder.startsWith(opened + path.sep)) && (!best || opened.length > best.length)) best = opened;
+  }
+  return best ?? folder;
+}
+
+/**
+ * The editor's window on a folder comes up, by the editor's own command-line tool: the window that has the folder open,
+ * else a new one on it. No link, so the editor asks nothing; its tool brings itself forward.
+ */
+export function openEditorFolder(place, folder) {
+  if (!place?.cli || !folder || !path.isAbsolute(folder) || !fs.existsSync(place.cli)) return false;
+  const env = { ...process.env };
+  // Not inside one of its terminals: a tool started there would replace that window's folder.
+  delete env.VSCODE_IPC_HOOK_CLI;
+  delete env.ELECTRON_RUN_AS_NODE;
+  const windows = process.platform === "win32";
+  const child = spawn(place.cli, [windows ? `"${folder}"` : folder], { env, detached: !windows, stdio: "ignore", shell: windows });
+  child.on("error", () => {});
+  child.unref();
+  return true;
+}
+
+/** How many times the person started a command in an editor's terminal, by the editor's own record of its last commands. */
+export function editorTerminalStarts(editorId, command) {
+  const editor = editorById(editorId);
+  const db = editor ? path.join(editorData(editor), "User", "globalStorage", "state.vscdb") : null;
+  if (!db || !fs.existsSync(db) || !fs.existsSync(SQLITE)) return 0;
+  const found = spawnSync(SQLITE, ["-readonly", "-cmd", ".timeout 500", db, "select value from ItemTable where key = 'terminal.history.entries.commands';"], { encoding: "utf8", timeout: 3_000 });
+  let entries = [];
+  try { entries = JSON.parse(found.stdout || "{}").entries || []; } catch { return 0; }
+  return entries.filter((entry) => path.basename(String(entry?.key || "").trim().split(/\s+/)[0] || "") === command).length;
+}
+
+// ── The agents ────────────────────────────────────────────────────────────────
+
+/** How each agent picks a session up again; its own panel in an editor, when it has one; its name in T3 Code. */
+const AGENTS = {
+  "claude-code": { command: "claude", resume: "claude --resume", t3: "claudeAgent",
+    panel: { extension: "anthropic.claude-code", link: (scheme, id) => `${scheme}://anthropic.claude-code/open?session=${id}` } },
+  codex: { command: "codex", resume: "codex resume", t3: "codex",
+    panel: { extension: "openai.chatgpt", link: (scheme, id) => `${scheme}://openai.chatgpt/local/${id}` } },
+  pi: { command: "pi", resume: "pi --session" },
+  opencode: { command: "opencode", resume: "opencode --session" },
+};
+export const agentCommand = (agent) => AGENTS[agent]?.command ?? null;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PLAIN_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const quote = (text) => `'${String(text).replace(/'/g, `'\\''`)}'`;
+
+/** The command a person types to pick a session up again, in its folder. */
+export function resumeLine(agent, sessionId, folder = null) {
+  const resume = AGENTS[agent]?.resume;
+  if (!resume || !PLAIN_ID.test(String(sessionId || ""))) return null;
+  return `${folder && path.isAbsolute(folder) ? `cd ${quote(folder)} && ` : ""}${resume} ${sessionId}`;
+}
+
+/** A session in its agent's own panel in an editor (Claude Code's, OpenAI's Codex extension), when it is installed there. */
+export function panelLink(agent, editorId, sessionId) {
+  const panel = AGENTS[agent]?.panel;
+  const editor = editorById(editorId);
+  if (!panel || !editor || !UUID.test(String(sessionId || "")) || !editorHas(editorId, panel.extension)) return null;
+  return panel.link(editor.scheme, sessionId);
+}
+
+// ── T3 Code ───────────────────────────────────────────────────────────────────
+
+const SQLITE = "/usr/bin/sqlite3";
+const T3_BUNDLE = "com.t3tools.t3code";
+export const t3Home = () => process.env.T3_HOME || path.join(os.homedir(), ".t3", "userdata");
+
+/** T3 Code's state database: 0.0.46 nightlies (Orchestrator V2) keep a copy of their own, statev2.sqlite; the newer file is the one in use. */
+function t3Database(home) {
+  const [found] = ["statev2.sqlite", "state.sqlite"].map((name) => path.join(home, name))
+    .map((file) => { try { return { file, at: fs.statSync(file).mtimeMs }; } catch { return null; } })
+    .filter(Boolean).sort((a, b) => b.at - a.at);
+  return found?.file ?? null;
+}
+function t3Query(home, sql) {
+  const db = t3Database(home);
+  if (!db || !fs.existsSync(SQLITE)) return null;
+  const found = spawnSync(SQLITE, ["-readonly", "-cmd", ".timeout 500", db, sql], { encoding: "utf8", timeout: 3_000 });
+  return found.status === 0 ? (found.stdout || "").trim() : null;
+}
+const t3Tables = (home) => new Set((t3Query(home, "select name from sqlite_master where type = 'table';") || "").split("\n"));
+
+/**
+ * The T3 Code thread that has a provider session: the thread T3 ran it in (nightlies record the session on the thread's
+ * provider thread; 0.0.45 in provider_session_runtime), else T3's import of it.
+ */
+export function t3Thread(sessionId, home = t3Home()) {
+  if (!PLAIN_ID.test(String(sessionId || ""))) return null;
+  const tables = t3Tables(home);
+  // The id is checked above: letters, digits and . _ : - only.
+  const parts = [];
+  if (tables.has("orchestration_v2_projection_provider_threads")) parts.push(`select thread_id, updated_at as at from orchestration_v2_projection_provider_threads where thread_id is not null and json_extract(payload_json, '$.nativeThreadRef.nativeId') = '${sessionId}'`);
+  if (tables.has("orchestration_v2_projection_threads")) parts.push(`select thread_id, updated_at as at from orchestration_v2_projection_threads where deleted_at is null and thread_id in ('import:claudeAgent:${sessionId}', 'import:codex:${sessionId}')`);
+  else if (tables.has("provider_session_runtime")) parts.push(`select thread_id, last_seen_at as at from provider_session_runtime where thread_id like '%:${sessionId}' or json_extract(resume_cursor_json, '$.resume') = '${sessionId}'`);
+  if (!parts.length) return null;
+  return t3Query(home, `select thread_id from (${parts.join(" union all ")}) order by at desc limit 1;`) || null;
+}
+
+/** T3 Code's own link to one of its threads (t3code://threads/<environment>/<thread>). */
+export function t3Link(threadId, home = t3Home()) {
+  let environment = "";
+  try { environment = fs.readFileSync(path.join(home, "environment-id"), "utf8").trim(); } catch { return null; }
+  return threadId && PLAIN_ID.test(environment) ? `t3code://threads/${environment}/${encodeURIComponent(threadId)}` : null;
+}
+
+/** How many threads the person ran an agent in T3 Code since a time: threads T3 itself ran (an import it never ran is not use). */
+export function t3Runs(agent, sinceIso, home = t3Home()) {
+  const provider = AGENTS[agent]?.t3;
+  if (!provider || !/^[0-9TZ:.-]+$/.test(sinceIso)) return 0;
+  const tables = t3Tables(home);
+  const parts = [];
+  if (tables.has("orchestration_v2_projection_provider_threads")) parts.push(`select thread_id from orchestration_v2_projection_provider_threads where provider = '${provider}' and updated_at > '${sinceIso}'`);
+  if (tables.has("provider_session_runtime")) parts.push(`select thread_id from provider_session_runtime where provider_name = '${provider}' and last_seen_at > '${sinceIso}' and (thread_id not like 'import:%' or resume_cursor_json like '%turnCount%')`);
+  return parts.length ? Number(t3Query(home, `select count(*) from (${parts.join(" union ")});`) || 0) || 0 : 0;
+}
+
+// T3 Code opens thread and prompt links from other apps only in its newer builds (0.0.46 nightlies on); 0.0.45 hands
+// t3code:// links to its sign-in alone. Read once per installed build: its bundle carries the link handler's own error
+// message (code names do not survive its minifier; this text does).
+const t3LinkSupport = new Map();
+export function t3OpensLinks(app) {
+  const archive = path.join(app, "Contents", "Resources", "app.asar");
+  let stamp = "";
+  try { stamp = String(fs.statSync(archive).mtimeMs); } catch { return false; }
+  const known = t3LinkSupport.get(archive);
+  if (known?.stamp === stamp) return known.ok;
+  let ok = false;
+  try { ok = fs.readFileSync(archive).includes("so T3 Code did not open it"); } catch {}
+  t3LinkSupport.set(archive, { stamp, ok });
+  return ok;
+}
+
+/** T3 Code's app: the one running when several builds are installed (stable and nightly side by side), else one that opens links, else any. */
+export function t3App() {
+  const apps = appDirs().flatMap((dir) => { try { return fs.readdirSync(dir).filter((entry) => /^T3 Code\b.*\.app$/.test(entry)).map((entry) => path.join(dir, entry)); } catch { return []; } });
+  if (!apps.length) return null;
+  const running = apps.length > 1 ? spawnSync(PS, ["-axo", "comm="], { encoding: "utf8", maxBuffer: 16 << 20 }).stdout || "" : "";
+  const app = apps.find((candidate) => running.includes(`${candidate}/Contents/MacOS/`)) ?? apps.find((candidate) => t3OpensLinks(candidate)) ?? apps[0];
+  return { name: path.basename(app, ".app"), app };
+}
+
+// ── A place ───────────────────────────────────────────────────────────────────
+
+const TERMINAL_NAMES = { Apple_Terminal: "Terminal", "iTerm.app": "iTerm", WezTerm: "WezTerm", ghostty: "Ghostty", WarpTerminal: "Warp", Hyper: "Hyper", kitty: "kitty", alacritty: "Alacritty" };
+
+/**
+ * Where a session runs, from its environment and the app found up its process tree (`host`, live.mjs hostApp):
+ *   t3        T3 Code;
+ *   editor    an editor built on VS Code: its terminal, or an agent's own panel there ("surface");
+ *   codex-app the Codex app;
+ *   terminal  a terminal app, with the ids that pick its pane on any OS (tmux, WezTerm, kitty) and its tty;
+ *   app       any other app.
+ * The environment comes first: the app a process sits under can be a different one (a terminal started from an editor).
+ */
+export function placeFrom({ env = {}, host = null, tty = null, folder = null }) {
+  const bundle = env.__CFBundleIdentifier || null;
+  const hostName = host?.name ?? "";
+  const editorOf = () => EDITORS.find((editor) => editor.bundle === bundle) ?? EDITORS.find((editor) => editor.match.test(env.VSCODE_GIT_ASKPASS_NODE || ""))
+    ?? (env.TERM_PROGRAM === "vscode" || env.CLAUDE_CODE_ENTRYPOINT === "claude-vscode" ? editorById("vscode") : null);
+  const editorPlace = (editor) => {
+    const install = editorInstall(editor.id, env.VSCODE_GIT_ASKPASS_NODE || host?.app || "");
+    const panel = env.CLAUDE_CODE_ENTRYPOINT === "claude-vscode" || env.TERM_PROGRAM !== "vscode";
+    return { kind: "editor", editor: editor.id, name: editor.name, app: install?.app ?? host?.app ?? null, cli: install?.cli ?? null, surface: panel ? "panel" : "terminal", folder };
+  };
+  if (env.T3CODE_CLI_PATH || bundle === T3_BUNDLE) return { kind: "t3", name: "T3 Code", folder };
+  const editor = editorOf();
+  if (editor) return editorPlace(editor);
+  const ids = { tty,
+    tmux: env.TMUX && /^%\d+$/.test(env.TMUX_PANE || "") ? env.TMUX_PANE : null,
+    wezterm: /^\d+$/.test(env.WEZTERM_PANE || "") ? env.WEZTERM_PANE : null,
+    kitty: /^\d+$/.test(env.KITTY_WINDOW_ID || "") ? { id: env.KITTY_WINDOW_ID, socket: env.KITTY_LISTEN_ON || null } : null };
+  if (env.TERM_PROGRAM && env.TERM_PROGRAM !== "vscode") return { kind: "terminal", name: hostName || TERMINAL_NAMES[env.TERM_PROGRAM] || env.TERM_PROGRAM, app: host?.app ?? null, ...ids, folder };
+  // Nothing in its environment says: the app it runs under.
+  if (/^T3 Code\b/.test(hostName)) return { kind: "t3", name: "T3 Code", folder };
+  const hosted = EDITORS.find((entry) => entry.name === hostName);
+  if (hosted) return editorPlace(hosted);
+  if (hostName === "Codex") return { kind: "codex-app", name: "Codex", app: host.app, folder };
+  if (tty || ids.tmux || ids.wezterm || ids.kitty) return { kind: "terminal", name: hostName || "Terminal", app: host?.app ?? null, ...ids, folder };
+  return host ? { kind: "app", name: hostName, app: host.app, folder } : null;
+}
+
+/** One key per place the person uses an agent in: both T3 builds are T3; an editor's terminal and its panel differ. */
+export const placeKey = (place) => (place.kind === "editor" ? `editor:${place.editor}:${place.surface}` : place.kind === "t3" ? "t3" : `${place.kind}:${place.name}`);