tryharness 0.7.22 → 0.7.23

package/lib/digest.mjs

@@ -0,0 +1,40 @@
+import { nameOf } from "./members.mjs";
+
+// "While you were away": what happened on the board since a moment, built by code from the board's own records (no
+// model writes it, so every name, number and verdict in it is one the board holds). Threads with finished work and what
+// each run's own session shows, questions waiting for the person, posts the guard held, watches that went off, and what
+// the overnight learner kept. The buddy shows it when the person comes back.
+
+const MAX_THREADS = 6;
+const clip = (text, length) => { const flat = String(text || "").replace(/\s+/g, " ").trim(); return flat.length > length ? `${flat.slice(0, length - 1)}…` : flat; };
+
+/** { since, lines, threads, empty }: lines are plain sentences, threads their ids for opening them. */
+export function digestSince(store, since, { alerts = [], learning = null, receiptOf = () => null } = {}) {
+  const lines = [];
+  const threads = [];
+  for (const thread of store.goals({ all: true })) {
+    if (thread.updated_at <= since) continue;
+    const posts = store.roomPosts(thread.id, 0, 500).filter((post) => post.created_at > since);
+    const results = posts.filter((post) => post.author !== "user" && post.author !== thread.goal.facilitator && (post.kind === "post" || post.kind === "result"));
+    const questions = posts.filter((post) => post.kind === "question");
+    const held = store.heldCount(thread.id, since);
+    const runs = store.threadRuns(thread.id).filter((run) => run.reported_at && run.reported_at > since);
+    if (!results.length && !questions.length && !runs.length) continue;
+    const parts = [];
+    const finished = runs.filter((run) => run.status === "done"), failed = runs.filter((run) => run.status === "failed");
+    if (finished.length) parts.push(`${[...new Set(finished.map((run) => nameOf(run.target_agent)))].join(" and ")} finished ${finished.length === 1 ? "a turn" : `${finished.length} turns`}`);
+    if (failed.length) parts.push(`${failed.length} failed`);
+    const checks = runs.map((run) => ({ agent: run.target_agent, ...receiptOf(run.id) })).filter((check) => check.verdict && check.verdict !== "no changes");
+    const untested = checks.filter((check) => check.verdict !== "tested");
+    if (checks.length) parts.push(untested.length ? `${untested.map((check) => `${nameOf(check.agent)}: ${check.verdict}`).join("; ")}` : "its changes were tested");
+    if (questions.length) parts.push(`a question waits for you: "${clip(questions.at(-1).text, 90)}"`);
+    if (held) parts.push(`${held} post${held === 1 ? "" : "s"} held because ${held === 1 ? "it reads" : "they read"} like orders to your agents`);
+    if (!finished.length && !failed.length && results.length) parts.unshift(`${[...new Set(results.map((post) => nameOf(post.author)))].join(" and ")} answered`);
+    lines.push(`"${clip(thread.objective, 60)}": ${parts.join("; ")}.`);
+    threads.push(thread.id);
+    if (threads.length >= MAX_THREADS) break;
+  }
+  for (const alert of alerts) lines.push(`Watch: ${alert.text}`);
+  if (learning?.kept && learning.at > since) lines.push(`Learned from ${learning.runs} runs: briefs now hold the files agents went on to change ${Math.round(learning.recallAt10.candidate * 100)}% of the time (was ${Math.round(Math.max(learning.recallAt10.default, learning.recallAt10.current ?? 0) * 100)}%).`);
+  return { since, lines, threads, empty: !lines.length };
+}

package/lib/environment.mjs

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+// What the relay can see of the person's computer without asking for any permission: which app is in front and how
+// long since they last touched the keyboard or mouse (macOS: lsappinfo and the HID idle timer; Linux under X11 when
+// xprintidle and xdotool are installed; nothing elsewhere), and the state of each repository the swarm works in (its
+// branch, files changed and not committed, and how long ago). The front app and idle time stay on this computer: they
+// time the buddy's digest and keep it quiet while the person is in a call. Window titles are never read.
+
+const PERSON_TTL_MS = 15_000;
+const REPO_TTL_MS = 10_000;
+const CALL_APPS = /^(?:zoom\.us|FaceTime|Microsoft Teams|Webex|Slack Huddle|Discord|Around|Google Meet|Tuple|Pop)$/i;
+
+const run = (command, args, options = {}) => {
+  try {
+    const out = spawnSync(command, args, { encoding: "utf8", timeout: 2_000, ...options });
+    return out.status === 0 ? out.stdout : null;
+  } catch { return null; }
+};
+
+/** The front app's name and seconds since the last input, or nulls where the OS can't say without a permission. */
+export function readPerson({ platform = process.platform, exec = run, file = process.env.HARNESS_PRESENCE_FILE } = {}) {
+  // Tests stand in for the OS: a JSON file { app, idleSeconds }, read instead of it (tests/e2e/desktop-local.mts).
+  if (file) {
+    try {
+      const read = JSON.parse(fs.readFileSync(file, "utf8"));
+      return { app: typeof read.app === "string" ? read.app : null, idleSeconds: Number.isFinite(read.idleSeconds) ? read.idleSeconds : null };
+    } catch { return { app: null, idleSeconds: null }; }
+  }
+  if (platform === "darwin") {
+    const asn = exec("lsappinfo", ["front"])?.trim();
+    const app = asn ? exec("lsappinfo", ["info", "-only", "name", asn])?.match(/"LSDisplayName"\s*=\s*"([^"]*)"/)?.[1] ?? null : null;
+    const idle = exec("ioreg", ["-c", "IOHIDSystem", "-d", "4", "-r", "-k", "HIDIdleTime"])?.match(/"HIDIdleTime"\s*=\s*(\d+)/)?.[1];
+    return { app, idleSeconds: idle ? Math.round(Number(idle) / 1e9) : null };
+  }
+  if (platform === "linux" && process.env.DISPLAY) {
+    const idle = exec("xprintidle", []);
+    const pid = exec("xdotool", ["getactivewindow", "getwindowpid"])?.trim();
+    let app = null;
+    try { if (pid) app = fs.readFileSync(`/proc/${pid}/comm`, "utf8").trim(); } catch {}
+    return { app, idleSeconds: idle ? Math.round(Number(idle) / 1000) : null };
+  }
+  return { app: null, idleSeconds: null };
+}
+
+/** A repository's branch and the files changed in it and not committed, newest change first. */
+export function readRepository(folder, { exec = run } = {}) {
+  const top = exec("git", ["rev-parse", "--show-toplevel"], { cwd: folder })?.trim();
+  if (!top) return null;
+  const branch = exec("git", ["branch", "--show-current"], { cwd: top })?.trim() || null;
+  const status = exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], { cwd: top }) ?? "";
+  const changed = [];
+  const entries = status.split("\0");
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i];
+    if (entry.length < 4) continue;
+    // A rename's old path follows it.
+    if (entry[0] === "R" || entry[0] === "C") i += 1;
+    const rel = entry.slice(3);
+    let mtime = null;
+    try { mtime = fs.statSync(path.join(top, rel)).mtimeMs; } catch {}
+    changed.push({ path: rel, state: entry.slice(0, 2).trim() === "??" ? "new" : entry[1] === "D" || entry[0] === "D" ? "deleted" : "changed", at: mtime });
+  }
+  changed.sort((a, b) => (b.at ?? 0) - (a.at ?? 0));
+  const last = exec("git", ["log", "-1", "--format=%ct%x00%s"], { cwd: top })?.split("\0");
+  return { root: top, branch, changed, lastCommit: last?.[0] ? { at: Number(last[0]) * 1000, subject: String(last[1] || "").trim().slice(0, 200) } : null };
+}
+
+export function createEnvironment({ platform = process.platform, exec = run } = {}) {
+  let person = null;
+  const repos = new Map();
+  return {
+    /** { app, idleSeconds, inCall, at }: never sent off this computer. */
+    person() {
+      if (!person || Date.now() - person.at > (process.env.HARNESS_PRESENCE_FILE ? 0 : PERSON_TTL_MS)) {
+        const read = readPerson({ platform, exec });
+        person = { ...read, inCall: Boolean(read.app && CALL_APPS.test(read.app)), at: Date.now() };
+      }
+      return person;
+    },
+    repository(folder) {
+      const cached = repos.get(folder);
+      if (cached && Date.now() - cached.at < REPO_TTL_MS) return cached.value;
+      const value = folder && fs.existsSync(folder) ? readRepository(folder, { exec }) : null;
+      repos.set(folder, { at: Date.now(), value });
+      if (repos.size > 200) repos.delete(repos.keys().next().value);
+      return value;
+    },
+    /** Minutes since a file in folder last changed, from its uncommitted files or its last commit; null when unknown. */
+    lastChanged(folder, now = Date.now()) {
+      const repo = this.repository(folder);
+      if (!repo) return null;
+      const newest = Math.max(repo.changed[0]?.at ?? 0, repo.lastCommit?.at ?? 0);
+      return newest ? Math.max(0, Math.round((now - newest) / 60_000)) : null;
+    },
+  };
+}

package/lib/firewall.mjs

@@ -0,0 +1,154 @@
+import { secretReason } from "./secrets.mjs";
+import { personalSpans } from "./personal.mjs";
+
+// The handoff firewall: two small local models on the text agents pass each other. Inbound, an injection guard reads
+// what an agent, page, tool or file hands another agent and flags or holds words that try to give orders. Outbound, a
+// credential model joins the room's patterns (secrets.mjs) and swaps any key or password in a brief bound for a hosted
+// agent for a placeholder, restored when the answer comes back to this computer. Neither model decides anything about
+// money or permissions: those stay code-enforced. Thresholds come from the handoff-firewall eval (measured on this
+// computer's own threads); a guard that cannot run leaves the text as it was, with the patterns still applied.
+
+const OVERLAP = 200;
+// A guard's score is its logit margin (injection minus benign), the scale its card calibrates on; the maximum over
+// windows stands for the whole text. Measured on this computer's own threads (handoff-firewall eval, October 14): small
+// windows find a sentence planted in a long page, large ones almost never hold a harmless post. A hold (the person must
+// release it) is Wolf Defender over 1,800-character windows at 2.5: no harmless post held, 90% of standalone attacks
+// held. A flag (a label every reader sees) is a hold or Horizon over 300-character windows at 6.0: 3.4% of real
+// harmless posts and pages flagged, 83% of planted and all standalone attacks caught (84% planted at 4.4% flagged with
+// the thresholds chosen on one half of the attacks and checked on the other). Without Horizon, Wolf Defender flags alone
+// over 400-character windows at 1.6 (3.9% flagged, 63% planted, 95% standalone).
+const HOLD_WINDOW = 1_800;
+const FLAG_WINDOW = 300;
+const FALLBACK_WINDOW = 400;
+export const GUARD_HOLD = 2.5;
+export const GUARD_FLAG = 6.0;
+export const FALLBACK_FLAG = 1.6;
+// Lines worth asking the credential model about: an assignment, a header, or a long unbroken token.
+const CANDIDATE_LINE = /[=:]\s*\S{12,}|\b(?:bearer|authorization|token|secret|password|passwd|api[_-]?key|private[_-]?key)\b|[A-Za-z0-9_\-+/]{24,}/i;
+const TOKEN = /[^\s"'`,;()<>{}[\]]{12,}/g;
+const USERINFO = /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:([^\s@/]+)@/i;
+const ASSIGNED = /(?:[=:]|\b(?:is|key|token|password|secret|passwd)\b)\s*(["']?)([^\s"'`,;]{8,})\1/i;
+
+/** The secret itself on a flagged line: a URL's password, a token that mixes kinds of characters, or an assigned value. */
+// A public wallet address is not a secret, and work for Bankr needs it whole (the credential model scores a line holding
+// one as a credential; local-stack smoke 6b). An Ethereum or bech32 address always; base58 only where the line says it
+// is an address, since API keys of that length look the same. Private keys stay secrets: 64 hex, or base58 of 51 or more.
+const publicAddress = (token, line) => /^0x[0-9a-fA-F]{40}$/.test(token) || /^(?:bc1|tb1|ltc1)[a-z0-9]{25,62}$/.test(token)
+  || (/^[1-9A-HJ-NP-Za-km-z]{26,44}$/.test(token) && /\b(?:address|wallet|solana|sol|btc|bitcoin|send|sent|pay|to)\b/i.test(line));
+
+export function secretSpan(line) {
+  const url = line.match(USERINFO);
+  if (url) return { at: url.index + url[0].lastIndexOf(url[1]), text: url[1] };
+  const classes = (token) => [/[a-z]/, /[A-Z]/, /\d/, /[^A-Za-z0-9]/].filter((re) => re.test(token)).length;
+  // A NAME=value or name:value token keeps its name; only the value is the secret.
+  const value = (token) => { const split = token.match(/^[A-Za-z_][\w.-]*[=:](.{8,})$/); return split ? split[1] : token; };
+  const tokens = [...line.matchAll(TOKEN)].map((m) => ({ at: m.index, text: value(m[0].replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9=]+$/g, "")) }))
+    .map((t) => ({ ...t, at: line.indexOf(t.text, t.at) })).filter((t) => t.text.length >= 12 && (classes(t.text) >= 3 || (t.text.length >= 24 && classes(t.text) >= 2)) && !/^[\w.-]+\.[a-z]{2,}$/i.test(t.text) && !/^(?:\/|\.\.?\/)/.test(t.text) && !publicAddress(t.text, line));
+  if (tokens.length) return tokens.sort((a, b) => classes(b.text) - classes(a.text) || b.text.length - a.text.length)[0];
+  const assigned = line.match(ASSIGNED);
+  return assigned ? { at: assigned.index + assigned[0].lastIndexOf(assigned[2]), text: assigned[2] } : null;
+}
+
+/** Overlapping windows over a long text, the start and end always included. */
+export function windows(text, size, max = Math.ceil(24_000 / size)) {
+  const value = String(text);
+  if (value.length <= size) return [value];
+  const out = [];
+  for (let at = 0; at < value.length; at += size - Math.min(OVERLAP, size / 4)) out.push(value.slice(at, at + size));
+  return out.length <= max ? out : [...out.slice(0, max - 2), ...out.slice(-2)];
+}
+
+export function createFirewall({ inference, log = () => {} }) {
+  const margin = async (id, text, size, lane) => Math.max(...(await inference.logits(id, windows(text, size), { lane, maxLength: 640 })).map((row) => row[1] - row[0]));
+  /** { score, holdScore, verdict: "clean" | "flag" | "hold" } for text one agent hands another. */
+  const inspect = async (text, { lane = "handoff" } = {}) => {
+    if (!String(text).trim()) return { score: -Infinity, holdScore: -Infinity, verdict: "clean" };
+    try {
+      const holdScore = await margin("guard", text, HOLD_WINDOW, lane);
+      if (holdScore >= GUARD_HOLD) return { score: holdScore, holdScore, verdict: "hold" };
+      const short = await margin("guard-short", text, FLAG_WINDOW, lane).catch((error) => { log(`firewall: the short-window guard could not run (${error.message})`); return null; });
+      if (short !== null) return { score: short, holdScore, verdict: short >= GUARD_FLAG ? "flag" : "clean" };
+      const score = await margin("guard", text, FALLBACK_WINDOW, lane);
+      return { score, holdScore, verdict: score >= FALLBACK_FLAG ? "flag" : "clean" };
+    } catch (error) {
+      log(`firewall: the guard could not run (${error.message})`);
+      return { score: null, verdict: "clean", unavailable: true };
+    }
+  };
+
+  /** Secret spans in a text: [{ start, end, reason }], from the patterns and the credential model. */
+  const secrets = async (text, { lane = "handoff" } = {}) => {
+    const value = String(text);
+    const spans = [];
+    let offset = 0;
+    const lines = value.split("\n").map((line) => { const start = offset; offset += line.length + 1; return { line, start }; });
+    const candidates = lines.filter(({ line }) => line.length <= 2_000 && (CANDIDATE_LINE.test(line) || secretReason(line)));
+    let probabilities = [];
+    if (candidates.length) {
+      try {
+        probabilities = (await inference.logits("credentials", candidates.map(({ line }) => line), { lane, maxLength: 256 }))
+          // The model's own calibration (policy.json): temperature 2.0954, threshold 0.74.
+          .map((row) => { const a = row[0] / 2.0954, b = row[1] / 2.0954; return 1 / (1 + Math.exp(a - b)); });
+      } catch (error) { log(`firewall: the credential model could not run (${error.message})`); }
+    }
+    candidates.forEach(({ line, start }, i) => {
+      const flagged = (probabilities[i] ?? 0) >= 0.74 || secretReason(line);
+      if (!flagged) return;
+      const span = secretSpan(line);
+      if (span) spans.push({ start: start + span.at, end: start + span.at + span.text.length, reason: secretReason(line) || "a credential" });
+    });
+    return spans.sort((a, b) => a.start - b.start);
+  };
+
+  /**
+   * The text with every secret replaced by [SECRET_n]; vault maps placeholders back. Restore with restore(text, vault).
+   * A vault passed in keeps placeholders stable across a thread. With personal set (a request that only decides, nothing
+   * acts on the values), emails, phone numbers, wallet addresses and amounts become [EMAIL_n], [PHONE_n], [WALLET_n] and
+   * [AMOUNT_n] too.
+   */
+  const scrub = async (text, { vault = new Map(), lane = "handoff", personal = false } = {}) => {
+    const value = String(text);
+    const found = await secrets(value, { lane });
+    const spans = personal ? [...found, ...personalSpans(value).filter((span) => !found.some((other) => other.start < span.end && span.start < other.end))].sort((a, b) => a.start - b.start) : found;
+    if (!spans.length) return { text: value, masked: 0, vault };
+    const reverse = new Map([...vault].map(([placeholder, original]) => [original, placeholder]));
+    let out = "";
+    let at = 0;
+    for (const span of spans) {
+      if (span.start < at) continue;
+      const original = value.slice(span.start, span.end);
+      let placeholder = reverse.get(original);
+      if (!placeholder) { placeholder = `[${LABELS[span.kind] ?? "SECRET"}_${vault.size + 1}]`; vault.set(placeholder, original); reverse.set(original, placeholder); }
+      out += value.slice(at, span.start) + placeholder;
+      at = span.end;
+    }
+    return { text: out + value.slice(at), masked: spans.length, vault };
+  };
+
+  return { inspect, secrets, scrub };
+}
+
+const LABELS = { email: "EMAIL", phone: "PHONE", wallet: "WALLET", money: "AMOUNT" };
+
+/** Puts a vault's originals back in place of its placeholders (only ever for text staying on this computer). */
+export function restore(text, vault) {
+  let out = String(text);
+  for (const [placeholder, original] of vault) out = out.split(placeholder).join(original);
+  return out;
+}
+
+/** restore over every string in a JSON-like value. */
+export function restoreDeep(value, vault) {
+  if (typeof value === "string") return restore(value, vault);
+  if (Array.isArray(value)) return value.map((item) => restoreDeep(item, vault));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, restoreDeep(item, vault)]));
+  return value;
+}
+
+/** Applies scrub to every string in a JSON-like value. */
+export async function scrubDeep(firewall, value, vault = new Map(), options = {}) {
+  if (typeof value === "string") return (await firewall.scrub(value, { vault, ...options })).text;
+  if (Array.isArray(value)) { const out = []; for (const item of value) out.push(await scrubDeep(firewall, item, vault, options)); return out; }
+  if (value && typeof value === "object") { const out = {}; for (const [key, item] of Object.entries(value)) out[key] = await scrubDeep(firewall, item, vault, options); return out; }
+  return value;
+}

package/lib/folders.mjs

@@ -2,26 +2,23 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { mainCheckout } from "./worktrees.mjs";
 import { nameOf } from "./members.mjs";
 import { paths } from "./paths.mjs";
 import { t3Projects } from "./places.mjs";
 
 // Where the person's threads work. The folder is the person's to choose, any folder on the computer: the composer offers
-// the folders they work in (T3 Code's projects, the folders their agents' sessions and threads ran in) and browses from
-// their home folder. With none chosen, Harness picks one from the message among those folders (src/server/swarm/folder.ts),
-// else the folder the agent last worked in. The home folder itself and hidden folders are never offered or picked, nor
-// Harness's and T3's own copies (their repository's checkout stands for them): work there is never what was meant (the
-// owner's October 13 thread ran Codex over their whole home folder).
+// the folders they work in (T3 Code's projects, the folders their agents' sessions and threads ran in, each as its
+// repository) and browses from their home folder. With none chosen, Harness picks one from the message among those folders
+// (src/server/swarm/folder.ts), else the folder the agent last worked in. The home folder itself and hidden folders are never
+// offered or picked, nor Harness's and T3's own copies or a repository's subfolders (the repository stands for them): work
+// there is never what was meant (the owner's October 13 thread ran Codex over their whole home folder; on October 14 a
+// buddy message was picked into ~/harness/src).
 
 const CODING = new Set(["claude-code", "codex", "pi", "opencode"]);
 // Folders offered and sent to Jev: the most recently worked in. Browsing reaches any other.
 const OFFERED = 60;
 const LISTED = 200;
-const README_MAX = 100_000;
-const TOP_LEVEL_MAX = 2_000;
 const PICK_TTL_MS = 10 * 60_000;
-const README = /^readme(\.(md|markdown|txt|rst))?$/i;
 
 const realDir = (dir) => { try { return fs.realpathSync(dir); } catch { return null; } };
 export const isDir = (dir) => typeof dir === "string" && path.isAbsolute(dir) && fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory() === true;
@@ -41,36 +38,44 @@ function offerable(dir) {
 
 const git = (cwd, args) => { const found = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 2_000 }); return found.status === 0 ? (found.stdout || "").trim() : ""; };
 
-/** What Jev reads of a folder: its name, repository, top level and README, whole. */
+// The repository a folder is in, as its main checkout (for a worktree's or a subfolder's sessions), else the folder itself.
+const ROOT_TTL_MS = 10 * 60_000;
+const roots = new Map();
+function repositoryOf(dir) {
+  const cached = roots.get(dir);
+  if (cached && cached.at > Date.now() - ROOT_TTL_MS) return cached.root;
+  const [top, common] = git(dir, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]).split("\n");
+  const root = (top && common ? realDir(path.basename(common) === ".git" ? path.dirname(common) : top) : null) ?? dir;
+  roots.set(dir, { root, at: Date.now() });
+  return root;
+}
+
+/**
+ * What Jev reads of a folder: its name, its repository, who worked there and when, and the titles of the sessions there
+ * (each the start of its first message), newest first. What was worked on in a folder says where new work goes; READMEs
+ * mostly say how to install a project, and together they passed Jev's limit (October 14).
+ */
 function facts(place) {
-  let entries = [];
-  try { entries = fs.readdirSync(place.path, { withFileTypes: true }).filter((entry) => ![".git", ".DS_Store"].includes(entry.name)); } catch {}
-  const readme = entries.find((entry) => entry.isFile() && README.test(entry.name));
-  let text = null;
-  try { text = readme ? fs.readFileSync(path.join(place.path, readme.name), "utf8") : null; } catch {}
   // A remote's address without any credentials in it.
   const remote = git(place.path, ["remote", "get-url", "origin"]).replace(/\/\/[^@/]+@/, "//");
-  return {
-    path: place.path, name: place.name, repository: remote || null,
-    topLevel: entries.map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`).sort().slice(0, TOP_LEVEL_MAX),
-    readme: text && text.length <= README_MAX ? text : null,
-    agents: place.agents.map(nameOf), lastWorked: place.lastWorked,
-  };
+  return { path: place.path, name: place.name, repository: remote || null, agents: place.agents.map(nameOf), lastWorked: place.lastWorked, titles: place.titles };
 }
 
-export function createFolders({ store, askHarness, canAsk, privacy, log = () => {} }) {
-  /** The folders the person works in, most recently worked in first: { path, name, t3, agents, lastWorked }. */
+export function createFolders({ store, askHarness, canAsk, privacy, log = () => {}, lastChanged = () => null, rank = async (_message, places) => places }) {
+  /** The folders the person works in, most recently worked in first: { path, name, t3, agents, lastWorked, titles }. */
   const known = () => {
     const byPath = new Map();
-    const add = (dir, agent, at) => {
-      const where = realDir(dir) && realDir(mainCheckout(realDir(dir)));
+    const add = (dir, agent, at, title) => {
+      const real = realDir(dir);
+      const where = real && repositoryOf(real);
       if (!where || !offerable(where)) return;
-      const place = byPath.get(where) ?? { path: where, name: path.basename(where), t3: false, agents: [], lastWorked: null };
+      const place = byPath.get(where) ?? { path: where, name: path.basename(where), t3: false, agents: [], lastWorked: null, titles: [] };
       if (agent && CODING.has(agent) && !place.agents.includes(agent)) place.agents.push(agent);
       if (at && (!place.lastWorked || at > place.lastWorked)) place.lastWorked = at;
+      if (title && !place.titles.includes(title)) place.titles.push(title);
       byPath.set(where, place);
     };
-    for (const row of store.sessionFolders(300)) add(row.cwd, row.agent, row.at);
+    for (const row of store.sessionPlaces()) add(row.cwd, row.agent, row.at, row.title);
     for (const thread of store.goals({ all: true })) if (thread.goal?.workspace) for (const agent of thread.goal.team) add(thread.goal.workspace, agent, thread.updated_at || thread.created_at);
     const projects = t3Projects();
     for (const dir of projects) add(dir, null, null);
@@ -106,10 +111,26 @@ export function createFolders({ store, askHarness, canAsk, privacy, log = () =>
     const key = JSON.stringify([message, places.map((place) => place.path)]);
     const cached = picks.get(key);
     if (cached && cached.at > Date.now() - PICK_TTL_MS) return cached.pending;
-    const pending = askHarness("pick_folder", { message, folders: places.map(facts) }, null).then((reply) => {
+    // How recently each folder's files changed, where Harness takes it (a daemon newer than the server would be refused).
+    const changed = lastChanged();
+    const ask = (offered) => askHarness("pick_folder", { message, folders: offered.map((place) => (changed ? { ...facts(place), lastChanged: changed(place.path) } : facts(place))) }, null);
+    const pending = (async () => {
+      let reply = await ask(places);
+      // Over Jev's limit: asked again about the most recently worked in half, halving until it fits. On the owner's
+      // sessions that half held the folder 99.5% of the time; the search model's closest half, 95.6% (eval folder-shortlist).
+      if (reply?.ok && reply.tooLarge) {
+        const ranked = await rank(message, places);
+        for (let n = Math.ceil(places.length / 2); reply?.ok && reply.tooLarge && n >= 2; n = Math.floor(n / 2)) {
+          log(`folder pick: ${places.length} folders are over Jev's limit; asking about the closest ${n}`);
+          reply = await ask(ranked.slice(0, n));
+        }
+      }
       if (!reply?.ok) throw new Error(reply?.error || "Harness did not pick a folder");
-      return places.some((place) => place.path === reply.folder) ? reply.folder : null;
-    });
+      const folder = places.some((place) => place.path === reply.folder) ? reply.folder : null;
+      // Jev's answers, so a wrong pick can be explained (not the message).
+      log(`folder pick: ${folder ?? "none"}${reply.tooLarge ? " (over Jev's limit)" : ""} ${JSON.stringify(reply.judgments ?? null)}`);
+      return folder;
+    })();
     picks.set(key, { at: Date.now(), pending });
     for (const [old, entry] of picks) if (entry.at <= Date.now() - PICK_TTL_MS || picks.size > 50) picks.delete(old);
     pending.catch(() => picks.delete(key));
@@ -117,22 +138,24 @@ export function createFolders({ store, askHarness, canAsk, privacy, log = () =>
   };
 
   /**
-   * The folder for a thread the person starts without choosing one: { folder, by }, by "message" (Jev's pick from what
-   * they wrote), "last" (where one of its agents last worked) or null when there is none to suggest.
+   * The folder for a thread the person starts without choosing one: { folder, by, lastWorked }, by "message" (Jev's pick
+   * from what they wrote), "last" (where one of its agents last worked) or null when there is none to suggest; lastWorked
+   * is that last folder when Jev picked another, for the person to take instead.
    */
   const suggest = async (text, agents) => {
     const places = known();
+    const coding = agents.filter((agent) => CODING.has(agent));
+    const last = places.filter((place) => place.lastWorked).find((place) => !coding.length || place.agents.some((agent) => coding.includes(agent)))?.path ?? null;
     const message = String(text).replace(/@([a-z][a-z0-9-]*)(:\S+)?\s*/g, "").trim();
     if (message && places.length && canAsk() && !privacy()) {
       try {
         const folder = await pickFromMessage(message, places);
-        if (folder) return { folder, by: "message" };
+        if (folder) return { folder, by: "message", lastWorked: folder === last ? null : last };
       } catch (error) { log(`folder pick: ${error.message}`); }
     }
-    const coding = agents.filter((agent) => CODING.has(agent));
-    const last = places.filter((place) => place.lastWorked).find((place) => !coding.length || place.agents.some((agent) => coding.includes(agent)));
-    return last ? { folder: last.path, by: "last" } : { folder: null, by: null };
+    return { folder: last, by: last ? "last" : null, lastWorked: null };
   };
 
-  return { known, browse, suggest };
+  // Offered to the composer without the session titles, which only Jev reads.
+  return { known: () => known().map(({ titles, ...place }) => place), browse, suggest };
 }

package/lib/frames.mjs

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { repositoryOf } from "./worktrees.mjs";
+import { nameOf } from "./members.mjs";
+
+// The task frame: one record per thread, built by the relay from what is on this computer and refreshed at every
+// handoff. What's asked: the files and code the person named, resolved to where they are (a function named in the words
+// becomes the file and line that declare it). The environment: the repository's branch and what is changed and not
+// committed. Peers: other open threads working in the same repository and what they change. Checks: each run's receipt
+// (receipts.mjs), so "done" is read against what the run's own session shows. The evidence (the context pack) is the
+// context engine's. Local agents get the frame in their brief and from get_task; the coordinator's round gets its peers,
+// checks and repository state; nothing in it is a guess by a model.
+
+const LINE_SUFFIX = /:(\d{1,6})(?::\d+)?$/;
+const FILE_TOKEN = /(?:[\w@.-]+\/)+[\w@.-]+|[\w-]+\.[a-z][a-z0-9]{0,5}\b/gi;
+// Names that only code has: camelCase, PascalCase with two humps, snake_case. A plain word, even written as a call
+// ("address(es)"), is left alone: in the owner's sessions they resolved to unrelated files (task-frame eval).
+const CODE_NAME = /\b([A-Za-z_$][\w$]{3,})\b/g;
+const codeShaped = (name) => /[a-z][A-Z]/.test(name) || /^[A-Z][a-z]+[A-Z]/.test(name) || (/_/.test(name) && /[a-z]/i.test(name.replace(/_/g, "")));
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const declares = (name) => new RegExp(`(?:^|\\n)[ \\t]*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function\\*?|class|const|let|var|type|interface|enum|def|fn|func|struct|trait|impl|module|contract|library|pub(?:\\([^)]*\\))?\\s+(?:async\\s+)?fn)\\s+${escape(name)}\\b|(?:^|\\n)[ \\t]+(?:async\\s+)?${escape(name)}\\s*\\([^)]*\\)\\s*\\{|(?:^|\\n)[ \\t]*(?:export\\s+)?const\\s+${escape(name)}\\s*=`);
+const minutes = (at, now) => (at ? Math.max(0, Math.round((now - at) / 60_000)) : null);
+const MAX_NAMED = 8;
+
+/**
+ * Files and code named in the person's words, resolved against a repository snapshot: { files: [{ path, line }],
+ * symbols: [{ name, path, line }] }. scope: the snapshot's files ([{ path, blob }]); atlas: the context engine's index.
+ */
+export function mentions(text, { scope = [], atlas = null } = {}) {
+  const words = String(text || "");
+  const files = [];
+  const seen = new Set();
+  for (const raw of words.match(FILE_TOKEN) ?? []) {
+    const token = raw.replace(/^\.?\/+/, "").replace(/[.,;:)]+$/, "");
+    const line = Number(token.match(LINE_SUFFIX)?.[1]) || null;
+    const rel = token.replace(LINE_SUFFIX, "");
+    if (rel.length < 4) continue;
+    const hits = scope.filter((row) => row.path === rel || row.path.endsWith(`/${rel}`));
+    if (!hits.length || hits.length > 3) continue;
+    for (const row of hits) if (!seen.has(row.path)) { seen.add(row.path); files.push({ path: row.path, line }); }
+  }
+  const symbols = [];
+  if (atlas) {
+    let inScope = null;
+    const names = new Map();
+    for (const match of words.matchAll(CODE_NAME)) if (codeShaped(match[1])) names.set(match[1], true);
+    for (const name of [...names.keys()].slice(0, 20)) {
+      // The atlas's word index finds the pieces that hold the name; one in this snapshot that declares it wins.
+      const hits = atlas.words([name], 200);
+      if (!hits.length) continue;
+      inScope ??= new Set(scope.flatMap((row) => atlas.blob(row.blob) ?? []));
+      const pattern = declares(name);
+      for (const hit of hits) {
+        if (!inScope.has(hit.hash)) continue;
+        const piece = atlas.piece(hit.hash);
+        const found = piece && pattern.exec(piece.text);
+        if (!found) continue;
+        const before = piece.text.slice(0, found.index + (found[0].startsWith("\n") ? 1 : 0));
+        symbols.push({ name, path: piece.path, line: piece.line + (before.match(/\n/g)?.length ?? 0) });
+        break;
+      }
+      if (symbols.length >= MAX_NAMED) break;
+    }
+  }
+  return { files: files.slice(0, MAX_NAMED), symbols };
+}
+
+export function createFrames({ store, environment, worktrees, atlas = () => null, scope = () => [], log = () => {} }) {
+  const key = (threadId) => `frame:${threadId}`;
+  const get = (threadId) => { try { return JSON.parse(store.meta(key(threadId)) || "null"); } catch { return null; } };
+
+  /** Where a thread's files are: its own worktree while open, else its folder. */
+  const placeOf = (thread) => {
+    const tree = worktrees.get(thread.id);
+    return tree?.state === "open" && tree.path ? { folder: tree.path, own: true, repo: tree.repo } : thread.goal?.workspace ? { folder: thread.goal.workspace, own: false, repo: repositoryOf(thread.goal.workspace)?.root ?? null } : null;
+  };
+
+  /** The files a thread is changing: its worktree's diff, or what its runs' receipts say they changed. */
+  const changing = (thread) => {
+    const tree = worktrees.get(thread.id);
+    if (tree?.state === "open") { try { return (worktrees.diff(thread.id).files || []).map((entry) => entry.file); } catch { return []; } }
+    return [...new Set(store.threadRuns(thread.id).flatMap((run) => receiptOf(run.id)?.changed ?? []))];
+  };
+
+  const receiptOf = (taskId) => { try { return JSON.parse(store.meta(`receipt:${taskId}`) || "null"); } catch { return null; } };
+
+  /** The frame for a thread, rebuilt from what is on the computer now. pack: the context engine's latest pack, if any. */
+  const build = (threadId, { pack = null } = {}) => {
+    const started = performance.now();
+    const thread = store.getTask(threadId);
+    if (!thread || thread.kind !== "goal") return null;
+    const now = Date.now();
+    const previous = get(threadId);
+    const place = placeOf(thread);
+    // What's asked: the person's own words in the thread, resolved once per change of words.
+    const asked = [thread.objective, thread.brief, ...store.roomPosts(threadId, 0, 500).filter((post) => post.author === "user").map((post) => post.text)].filter(Boolean).join("\n");
+    const wordsHash = createHash("sha1").update(asked).digest("hex");
+    let named = previous?.asked?.hash === wordsHash ? previous.asked : null;
+    if (!named) {
+      const index = atlas();
+      named = { hash: wordsHash, ...mentions(asked, { scope: index && place ? scope(place.folder) : [], atlas: index }) };
+    }
+    const repo = place ? environment.repository(place.folder) : null;
+    const repository = repo ? {
+      branch: repo.branch, own: place.own,
+      changed: repo.changed.slice(0, 8).map((entry) => ({ path: entry.path, state: entry.state, minutesAgo: minutes(entry.at, now) })),
+      uncommitted: repo.changed.length,
+      lastCommit: repo.lastCommit ? { subject: repo.lastCommit.subject, minutesAgo: minutes(repo.lastCommit.at, now) } : null,
+    } : null;
+    const peers = [];
+    if (place?.repo) {
+      for (const other of store.goals({ all: false })) {
+        if (other.id === threadId || other.status !== "open") continue;
+        const there = placeOf(other);
+        if (!there?.repo || there.repo !== place.repo) continue;
+        const runs = store.threadRuns(other.id);
+        const files = changing(other);
+        const running = runs.filter((run) => run.status === "running").map((run) => run.target_agent);
+        if (!files.length && !running.length) continue;
+        peers.push({ thread: other.id, title: other.objective.slice(0, 200), agents: other.goal.team.filter((agent) => agent !== other.goal.facilitator), running, files: files.slice(0, 20) });
+      }
+    }
+    const checks = store.threadRuns(threadId).map((run) => ({ run: run.id, agent: run.target_agent, ...receiptOf(run.id) })).filter((check) => check.verdict).slice(-5);
+    const frame = {
+      thread: threadId, updatedAt: new Date(now).toISOString(), folder: place?.folder ?? null,
+      asked: named, repository, peers: peers.slice(0, 6), checks,
+      evidence: pack ? { files: pack.files, earlier: pack.earlier.map((run) => ({ agent: run.agent, at: run.at, brief: run.brief.slice(0, 200), edited: run.edited.slice(0, 6) })) } : previous?.evidence ?? null,
+      ms: 0,
+    };
+    frame.ms = Math.round(performance.now() - started);
+    store.meta(key(threadId), JSON.stringify(frame));
+    return frame;
+  };
+
+  /** The frame as a local agent reads it in its brief; empty parts are left out. */
+  const briefText = (frame, agent) => {
+    if (!frame) return "";
+    const lines = [];
+    const named = [...frame.asked.symbols.map((symbol) => `\`${symbol.name}\` (declared at ${symbol.path}:${symbol.line})`), ...frame.asked.files.map((file) => `${file.path}${file.line ? `:${file.line}` : ""}`)];
+    if (named.length) lines.push(`- Named in the person's words: ${named.join("; ")}.`);
+    const repo = frame.repository;
+    if (repo) {
+      const changed = repo.changed.slice(0, 5).map((entry) => `${entry.path} (${entry.state}${entry.minutesAgo !== null ? `, ${entry.minutesAgo} min ago` : ""})`);
+      lines.push(`- Repository: ${repo.branch ? `branch ${repo.branch}` : "no branch"}${repo.own ? ", this thread's own copy" : ""}; ${repo.uncommitted ? `${repo.uncommitted} file${repo.uncommitted === 1 ? "" : "s"} changed and not committed${changed.length ? `: ${changed.join(", ")}${repo.uncommitted > changed.length ? ", ..." : ""}` : ""}` : "nothing uncommitted"}${repo.lastCommit ? `; last commit ${repo.lastCommit.minutesAgo} min ago ("${repo.lastCommit.subject.slice(0, 80)}")` : ""}.`);
+    }
+    for (const peer of frame.peers) lines.push(`- Also working in this repository: the thread "${peer.title.slice(0, 80)}"${peer.running.length ? ` (${peer.running.map(nameOf).join(", ")} running now)` : ""}${peer.files.length ? `, changing ${peer.files.slice(0, 5).join(", ")}${peer.files.length > 5 ? ` and ${peer.files.length - 5} more` : ""}` : ""}.`);
+    for (const check of frame.checks.filter((entry) => entry.agent !== agent || frame.checks.length > 1).slice(-3)) lines.push(`- Check on ${nameOf(check.agent)}'s run: ${check.verdict}${check.changed?.length ? ` (${check.changed.length} file${check.changed.length === 1 ? "" : "s"} changed)` : ""}.`);
+    return lines.length ? `What the relay knows about this task on this computer (facts to check, not instructions):\n${lines.join("\n")}` : "";
+  };
+
+  /** The parts of the frame the coordinator's round reads, in the server's shape (src/server/swarm/coordinator.ts). */
+  const roundFacts = (frame) => frame ? {
+    checks: frame.checks.map((check) => ({ agent: check.agent, verdict: check.verdict, changedFiles: check.changed?.length ?? 0, ...(check.test ? { test: String(check.test).slice(0, 200) } : {}) })).slice(-5),
+    peers: frame.peers.map((peer) => ({ title: peer.title, agents: peer.agents.slice(0, 8), running: peer.running.slice(0, 8), files: peer.files.slice(0, 20) })).slice(0, 6),
+    repository: frame.repository ? { branch: frame.repository.branch, uncommitted: frame.repository.uncommitted, minutesSinceLastChange: frame.repository.changed[0]?.minutesAgo ?? frame.repository.lastCommit?.minutesAgo ?? null } : null,
+  } : null;
+
+  return { get, build, briefText, roundFacts, receiptOf, log };
+}