tryharness 0.7.9 → 0.7.13

package/lib/nudge.mjs

@@ -11,7 +11,13 @@ import { placeEnv } from "./places.mjs";
 // SessionStart hook (stdout lands in its context); the Pi extension and OpenCode plugin
 // build the same text in-process. Nothing waiting, or no daemon, prints nothing.
 
-export function nudgeText(agent, tasks, unread = [], goals = []) {
+// The swarm block (cards.mjs), when given, follows the queue: who else is in the person's swarm and what each is for.
+export function nudgeText(agent, tasks, unread = [], goals = [], swarm = "") {
+  const queue = queueText(agent, tasks, unread, goals);
+  return [queue, swarm].filter(Boolean).join("\n\n");
+}
+
+function queueText(agent, tasks, unread, goals) {
   const waiting = (tasks || []).filter((task) => task.status === "open" && (!task.target_agent || task.target_agent === agent));
   const held = (tasks || []).filter((task) => task.claimed_by === agent && (task.status === "claimed" || task.status === "needs_input"));
   if (!waiting.length && !held.length && !unread.length && !goals.length) return "";
@@ -38,31 +44,41 @@ export function queueDigest(agent, tasks, unread = [], goals = []) {
 
 export async function boardQueue(agent) {
   try {
-    const response = await daemonRequest({ command: "board.list", agent, unread: true }, 1_500);
-    return response?.ok ? { tasks: response.tasks, unread: response.unread || [], goals: response.goals || [] } : null;
+    const response = await daemonRequest({ command: "board.list", agent, unread: true, swarm: true }, 1_500);
+    return response?.ok ? { tasks: response.tasks, unread: response.unread || [], goals: response.goals || [], swarm: response.swarm || null } : null;
   } catch {
     return null;
   }
 }
 
-export async function boardNudge(agent) {
+// What this agent was last told, in the Harness home: the queue's digest and the swarm's.
+const toldFile = (agent, homeDir) => path.join(homeDir, `nudge-${agent}.json`);
+function lastTold(agent, homeDir) { try { return JSON.parse(fs.readFileSync(toldFile(agent, homeDir), "utf8")); } catch { return {}; } }
+function noteTold(agent, homeDir, told) { try { fs.writeFileSync(toldFile(agent, homeDir), JSON.stringify({ ...lastTold(agent, homeDir), ...told, at: new Date().toISOString() }), { mode: 0o600 }); } catch {} }
+
+/** What a session is told when it starts: its queue and the whole swarm. */
+export async function boardNudge(agent, homeDir = paths.home) {
   const queue = await boardQueue(agent);
-  return queue ? nudgeText(agent, queue.tasks, queue.unread, queue.goals) : "";
+  if (!queue) return "";
+  if (queue.swarm?.digest) noteTold(agent, homeDir, { swarm: queue.swarm.digest });
+  return nudgeText(agent, queue.tasks, queue.unread, queue.goals, queue.swarm?.text || "");
 }
 
 // Only what changed since this agent last saw its queue: a hook that runs on every prompt
-// prints once per change, never the same block again. The last digest lives in the Harness home.
+// prints once per change, never the same block again. The swarm is told again only when who is
+// in it, their facts or the person's notes changed, not each time an agent finishes something.
 export async function boardNudgeIfChanged(agent, homeDir = paths.home) {
   const queue = await boardQueue(agent);
   if (!queue) return "";
-  const { tasks, unread, goals } = queue;
+  const { tasks, unread, goals, swarm } = queue;
   const digest = queueDigest(agent, tasks, unread, goals);
-  const file = path.join(homeDir, `nudge-${agent}.json`);
-  let last = null;
-  try { last = JSON.parse(fs.readFileSync(file, "utf8")).digest; } catch {}
-  if (digest === last) return "";
-  try { fs.writeFileSync(file, JSON.stringify({ digest, at: new Date().toISOString() }), { mode: 0o600 }); } catch {}
-  return digest ? nudgeText(agent, tasks, unread, goals) : (last ? "Harness task board: nothing waits for you now." : "");
+  const last = lastTold(agent, homeDir);
+  const queueMoved = digest !== (last.digest ?? null);
+  const swarmMoved = Boolean(swarm?.digest) && swarm.digest !== last.swarm;
+  if (!queueMoved && !swarmMoved) return "";
+  noteTold(agent, homeDir, { digest, ...(swarm?.digest ? { swarm: swarm.digest } : {}) });
+  const told = !queueMoved ? "" : digest ? queueText(agent, tasks, unread, goals) : (last.digest ? "Harness task board: nothing waits for you now." : "");
+  return [told, swarmMoved ? swarm.text : ""].filter(Boolean).join("\n\n");
 }
 
 // The prompt hook also tells the daemon the person typed in this session: the agent process is the hook's parent, or

package/lib/onboard.mjs

@@ -1,22 +1,37 @@
 import { spawnSync } from "node:child_process";
-import readline from "node:readline";
+import pc from "picocolors";
 import { detectLocalAgents, setupHermes, setupOpenClaw, localWakes } from "./wakes.mjs";
+import { columns, createUi, wrap } from "./ui.mjs";
 
-// "Your swarm" in setup: every agent class with how Harness reaches it, the recommended way already chosen, the steps
-// numbered, and a real test at the end that passes only when the agent claims and reports a task. Also reachable on its
-// own as `npx tryharness agents`. Without a terminal to answer in, it only says what is set up and how to finish.
+// "Your swarm" in setup: every agent class with how Harness reaches it, the recommended way already chosen, and a real
+// test at the end that passes only when the agent claims and reports a task. Also reachable on its own as
+// `npx tryharness agents`. Without a terminal to answer in, it only says what is set up and how to finish.
 
 const SETUP = { openclaw: setupOpenClaw, hermes: setupHermes };
 const LABEL = { openclaw: "OpenClaw", hermes: "Hermes", "grok-bot": "Grok Bot" };
-const MEASURED = "measured on a real Grok: about 23s by email, 17s by webhook";
+const later = (agent) => `Later: ${pc.cyan(`npx tryharness agents setup ${agent}`)}`;
 
-export function createPrompter({ input = process.stdin, output = process.stdout } = {}) {
-  const ask = (question, { hidden = false } = {}) => new Promise((resolve) => {
-    const rl = readline.createInterface({ input, output, terminal: true });
-    if (hidden) rl._writeToOutput = (text) => { if (text.includes(question)) output.write(text); };
-    rl.question(question, (answer) => { rl.close(); if (hidden) output.write("\n"); resolve(answer.trim()); });
-  });
-  return { ask };
+// The Harness mark (src/main/home/landing/walkthrough/BrandMark.tsx) in box characters: dim corners, the bright one in
+// Harness teal, the wordmark beside it. Plain when the output is not a terminal or NO_COLOR is set.
+export function banner(version, { color = pc.isColorSupported } = {}) {
+  const c = pc.createColors(color), teal = (text) => (color ? `\x1b[38;5;36m${text}\x1b[39m` : text);
+  const rows = [
+    [c.dim("┌───"), "           ", teal("───┐")],
+    [c.dim("│"), "                 ", teal("│")],
+    [""],
+    ["      ", c.dim("┌──"), teal("───┐")],
+    ["      ", c.dim("│"), "     ", teal("│")],
+    ["      ", c.dim("└─────┘")],
+    [""],
+    [c.dim("│"), "                 ", c.dim("│")],
+    [c.dim("└───"), "           ", c.dim("───┘")],
+  ];
+  const side = { 3: c.bold("harness relay"), 4: "your personal swarm", 5: c.dim(`setup ${version}`) };
+  return rows.map((parts, index) => {
+    const line = parts.join("");
+    const width = line.replace(/\x1b\[[0-9;]*m/g, "").length;
+    return side[index] ? `  ${line}${" ".repeat(23 - width)}${side[index]}` : `  ${line}`.trimEnd();
+  }).join("\n");
 }
 
 const copy = (text) => {
@@ -26,106 +41,141 @@ const copy = (text) => {
 };
 
 /** Post a setup check for the agent and wait for its report: the same path real work takes. */
-export async function testAgent({ agent, daemonRequest, out = console.log, waitMs = 10 * 60_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+export async function testAgent({ agent, daemonRequest, ui = createUi(), waitMs = 10 * 60_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  const name = LABEL[agent] || agent;
   const posted = await daemonRequest({ command: "board.post", agent: "user", objective: "Setup check from Harness: reply ready", brief: "Harness is checking that it can wake you. Claim this task and report it done with the single word: ready. Do nothing else.", targetAgent: agent });
-  if (!posted?.ok) { out(`    ! the test task could not be posted: ${posted?.error || "no answer"}`); return false; }
-  const started = Date.now();
-  out(`    Test sent. Waiting for ${LABEL[agent] || agent} to answer (Ctrl-C stops waiting; the test task stays on your board).`);
+  if (!posted?.ok) { ui.warn(`The test task could not be posted: ${posted?.error || "no answer"}`); return false; }
+  const started = Date.now(), spin = ui.spinner();
+  spin.start(`Waiting for ${name} to answer a test task`);
   while (Date.now() - started < waitMs) {
     await sleep(2_000);
     const task = (await daemonRequest({ command: "board.get", agent: "user", id: posted.task.id }).catch(() => null))?.task;
-    if (task?.status === "done") { out(`    ✓ ${LABEL[agent] || agent} answered in ${Math.round((Date.now() - started) / 1000)}s. Ready.`); return true; }
-    if (task && ["failed", "needs_input"].includes(task.status)) { out(`    ! ${LABEL[agent] || agent} answered but the task is ${task.status}: ${task.result || ""}`); return false; }
+    if (task?.status === "done") { spin.stop(`${name} answered in ${Math.round((Date.now() - started) / 1000)}s. Ready.`); return true; }
+    if (task && ["failed", "needs_input"].includes(task.status)) { spin.stop(`${name} answered, but the task is ${task.status}${task.result ? `: ${task.result}` : ""}`, 2); return false; }
   }
-  out(`    ! No answer after ${Math.round(waitMs / 60_000)} minutes. Check that the agent is running, then: npx tryharness agents test ${agent}`);
+  spin.stop(`No answer after ${Math.round(waitMs / 60_000)} minutes. Check that ${name} is running, then: npx tryharness agents test ${agent}`, 2);
   return false;
 }
 
-async function setupLocal({ entry, runtimeRoot, prompter, daemonRequest, out }) {
+async function setupLocal({ entry, runtimeRoot, ui, daemonRequest }) {
   const name = LABEL[entry.agent];
+  const run = async () => {
+    const result = SETUP[entry.agent]({ runtimeRoot });
+    if (!result.ok) { ui.warn(result.detail); return; }
+    ui.success(result.detail);
+    await testAgent({ agent: entry.agent, daemonRequest, ui });
+  };
   if (localWakes()[entry.agent]) {
     const health = (await daemonRequest({ command: "wake.local" }).catch(() => null))?.agents?.[entry.agent];
-    if (!health || health.answering) { out(`  ✓ ${name}: woken on this computer by its own webhook`); return; }
-    out(`  ! ${name}: not answering wakes (${health.lastFailure}). Check that it is running.`);
-    if (!prompter || /^n/i.test(await prompter.ask(`    Set ${name} up again? [Y/n] `))) { out(`    Later: npx tryharness agents setup ${entry.agent}`); return; }
-    const result = SETUP[entry.agent]({ runtimeRoot });
-    out(`    ${result.ok ? "✓" : "!"} ${result.detail}`);
-    if (result.ok) await testAgent({ agent: entry.agent, daemonRequest, out });
+    if (!health || health.answering) { ui.success(`${name} is woken on this computer by its own webhook`); return; }
+    ui.warn(`${name} is not answering wakes (${health.lastFailure}). Check that it is running.`);
+    if (!ui.interactive || !(await ui.confirm({ message: `Set ${name} up again?`, initialValue: true }))) { ui.info(later(entry.agent)); return; }
+    await run();
     return;
   }
-  if (!prompter) { out(`  ! ${name}: found. Set it up with: npx tryharness agents setup ${entry.agent}`); return; }
-  out(`  ${name} found. Harness wakes it with a webhook on this computer (recommended, nothing to copy).`);
-  out(`    This adds Harness to ${name}'s MCP servers and turns on its webhook with a key made here${entry.agent === "openclaw" ? ", then restarts its gateway" : ""}.`);
-  if (/^n/i.test(await prompter.ask(`    Set up ${name} now? [Y/n] `))) { out(`    Skipped. Later: npx tryharness agents setup ${entry.agent}`); return; }
-  const result = SETUP[entry.agent]({ runtimeRoot });
-  out(`    ${result.ok ? "✓" : "!"} ${result.detail}`);
-  if (result.ok) await testAgent({ agent: entry.agent, daemonRequest, out });
+  if (!ui.interactive) { ui.info(`${name} found. ${later(entry.agent)}`); return; }
+  ui.step(`${name} found on this computer\n${pc.dim(`Harness adds itself to ${name}'s MCP servers and turns on its webhook with a key made here${entry.agent === "openclaw" ? ", then restarts its gateway" : ""}. Nothing to copy.`)}`);
+  if (!(await ui.confirm({ message: `Set up ${name} now?`, initialValue: true }))) { ui.info(`Skipped. ${later(entry.agent)}`); return; }
+  await run();
+}
+
+async function waitFor(check, waitMs = 10 * 60_000, everyMs = 3_000) {
+  const end = Date.now() + waitMs;
+  while (Date.now() < end) {
+    if (await check()) return true;
+    await new Promise((r) => setTimeout(r, everyMs));
+  }
+  return false;
 }
 
-async function setupGrok({ prompter, daemonRequest, out, clipboard }) {
-  const listed = await daemonRequest({ command: "wake.server", input: { action: "list" } }).catch((error) => ({ ok: false, error: error.message }));
-  if (!listed.ok) { out(`  ! Grok Bot: Harness could not be reached (${listed.error}). Later: npx tryharness agents setup grok-bot`); return; }
+async function setupGrok({ ui, daemonRequest, clipboard }) {
+  const list = () => daemonRequest({ command: "wake.server", input: { action: "list" } });
+  const listed = await list().catch((error) => ({ ok: false, error: error.message }));
+  if (!listed.ok) { ui.warn(`Harness could not be reached (${listed.error}). ${later("grok-bot")}`); return; }
   const current = (listed.wakes || []).find((wake) => wake.agent === "grok-bot");
   if (current) {
     const how = current.channel === "email" ? `email at ${current.address}` : "its webhook";
-    if (current.answering) { out(`  ✓ Grok Bot: woken by ${how}`); return; }
-    out(`  ! Grok Bot: not answering wakes by ${how} (${current.last_failure}).`);
-    if (!prompter || /^n/i.test(await prompter.ask("    Set it up again? [Y/n] "))) { out("    Later: npx tryharness agents setup grok-bot"); return; }
+    if (current.answering) { ui.success(`Grok Bot is woken by ${how}`); return; }
+    ui.warn(`Grok Bot is not answering wakes by ${how} (${current.last_failure})`);
+    if (!ui.interactive || !(await ui.confirm({ message: "Set it up again?", initialValue: true }))) { ui.info(later("grok-bot")); return; }
   }
-  if (!prompter) { out("  Grok Bot: not set up. Set it up with: npx tryharness agents setup grok-bot"); return; }
-  out(`  Grok Bot. How should Harness wake it? (${MEASURED})`);
-  out("    1) Email     nothing to copy back                          (recommended)");
-  out("    2) Webhook   a little faster; you paste its URL and key here");
-  out("    3) Not now");
-  const choice = (await prompter.ask("    Choose [1]: ")) || "1";
-  if (choice === "3") { out("    Skipped. Later: npx tryharness agents setup grok-bot"); return; }
-  const channel = choice === "2" ? "webhook" : "email";
+  if (!ui.interactive) { ui.info(`Grok Bot is not set up. ${later("grok-bot")}`); return; }
+  const channel = await ui.select({
+    message: "How should Harness wake Grok Bot?",
+    initialValue: "email",
+    options: [
+      { value: "email", label: "Email", hint: "recommended · about 23s · nothing to copy back" },
+      { value: "webhook", label: "Webhook", hint: "about 17s · you paste its URL and key here" },
+      { value: "skip", label: "Not now" },
+    ],
+  });
+  if (!channel || channel === "skip") { ui.info(`Skipped. ${later("grok-bot")}`); return; }
   const message = listed.messages?.["grok-bot"]?.[channel];
-  if (!message) { out("    ! Harness did not send the setup message; update tryharness and try again."); return; }
+  if (!message) { ui.warn("Harness did not send the setup message. Update tryharness and try again."); return; }
+  const setup = (listed.setup || []).find((entry) => entry.agent === "grok-bot");
+  const connected = Boolean(setup) && !setup.missing?.includes("connection");
   const copied = clipboard(message);
-  out(`    1. ${copied ? "This message is on your clipboard. Paste it into Grok:" : "Paste this message into Grok:"}`);
-  out(message.split("\n").map((line) => `       ${line}`).join("\n"));
-  out("    2. Grok opens Harness's approval page. Name the connection Grok Bot and approve.");
+  ui.note(wrap(message, Math.max(40, columns() - 8)).join("\n"), copied ? "Paste this into Grok · it is on your clipboard" : "Paste this into Grok");
+  if (connected) ui.success(`Grok is already connected to Harness as Grok Bot${setup.old_approval ? `\n${pc.dim("approved before it could register its own address, so it gives you its address instead")}` : ""}`);
+  else ui.info("Grok opens Harness's approval page. Name the connection Grok Bot and approve it.");
+
+  const save = async (input, done) => {
+    const saved = await daemonRequest({ command: "wake.server", input: { action: "save", agent: "grok-bot", ...input } });
+    if (!saved.ok) { ui.warn(`${saved.error}. Try again: npx tryharness agents setup grok-bot`); return false; }
+    ui.success(done(saved));
+    return true;
+  };
   if (channel === "webhook") {
-    out("    3. In Grok, open Routines, then Harness wake, and copy its webhook URL and key.");
-    const address = await prompter.ask("       Webhook URL: ");
-    const key = await prompter.ask("       Key (hidden): ", { hidden: true });
-    const saved = await daemonRequest({ command: "wake.server", input: { action: "save", agent: "grok-bot", channel: "webhook", address, key } });
-    if (!saved.ok) { out(`    ! ${saved.error}. Try again: npx tryharness agents setup grok-bot`); return; }
-    out("    ✓ Saved. The key is stored sealed on Harness and is never shown again.");
+    ui.info("In Grok, open Routines, then Harness wake, and copy its webhook URL and key.");
+    const address = await ui.text({ message: "Grok's webhook URL", placeholder: "https://", validate: (value) => (/^https:\/\/\S+$/.test(value.trim()) ? undefined : "Paste the https URL from Grok's routine") });
+    if (!address) { ui.info(`Skipped. ${later("grok-bot")}`); return; }
+    const key = await ui.password({ message: "Its key", validate: (value) => (value.trim() ? undefined : "Paste the key from Grok's routine") });
+    if (!key) { ui.info(`Skipped. ${later("grok-bot")}`); return; }
+    if (!(await save({ channel: "webhook", address: address.trim(), key }, () => "Saved. The key is stored sealed on Harness and never shown again."))) return;
   } else {
-    out("    3. Grok registers its own address with Harness. Waiting for it (Ctrl-C stops waiting)...");
-    const registered = await waitFor(async () => ((await daemonRequest({ command: "wake.server", input: { action: "list" } }).catch(() => null))?.wakes || []).some((wake) => wake.agent === "grok-bot"));
-    if (!registered) { out("    Not registered yet. When Grok has done it: npx tryharness agents test grok-bot"); return; }
-    out("    ✓ Grok registered its address.");
+    const ownAddress = (value) => (/^[^\s@]+@mail\.grokbot\.com$/i.test(value.trim()) ? undefined : "Grok's address ends in @mail.grokbot.com");
+    let address = "";
+    if (setup?.old_approval) {
+      address = await ui.text({ message: "Grok's email address", placeholder: "name@mail.grokbot.com", validate: ownAddress }) ?? "";
+      if (!address) { ui.info(`Skipped. ${later("grok-bot")}`); return; }
+    } else {
+      // Grok registers its own address; the person may type the one Grok gives instead, and the prompt closes when it registers.
+      let settled = false;
+      const registered = waitFor(async () => settled || ((await list().catch(() => null))?.wakes || []).some((wake) => wake.agent === "grok-bot"))
+        .then((ok) => (ok ? { ok, line: "Grok registered its address" } : { ok, line: "Grok has not registered yet. When it has: npx tryharness agents test grok-bot" }));
+      const answer = await ui.waitOrType({ message: "Waiting for Grok to register its address", placeholder: "or type the address Grok gives you", until: registered });
+      let outcome = answer.done;
+      if (answer.cancelled) { settled = true; ui.info(`Stopped waiting. ${later("grok-bot")}`); return; }
+      if (answer.value && ownAddress(answer.value)) { settled = true; ui.warn(`${ownAddress(answer.value)}. ${later("grok-bot")}`); return; }
+      if (answer.value) address = answer.value;
+      else if (!outcome) {
+        const spin = ui.spinner();
+        spin.start("Waiting for Grok to register its address");
+        outcome = await registered;
+        spin.stop(outcome.line, outcome.ok ? 0 : 2);
+      }
+      settled = true;
+      if (outcome && !outcome.ok) return;
+    }
+    if (address && !(await save({ channel: "email", address: address.trim() }, (saved) => `Saved. Harness wakes Grok at ${saved.wake?.address ?? address.trim()}`))) return;
   }
-  await testAgent({ agent: "grok-bot", daemonRequest, out });
-}
-
-async function waitFor(check, waitMs = 10 * 60_000, everyMs = 3_000) {
-  const end = Date.now() + waitMs;
-  while (Date.now() < end) {
-    if (await check()) return true;
-    await new Promise((r) => setTimeout(r, everyMs));
-  }
-  return false;
+  await testAgent({ agent: "grok-bot", daemonRequest, ui });
 }
 
 /** The whole "Your swarm" step. `only` limits it to one agent (npx tryharness agents setup <agent>). */
-export async function setupSwarm({ runtimeRoot, states = [], daemonRequest, prompter = process.stdin.isTTY ? createPrompter() : null, out = console.log, only = null, clipboard = copy }) {
+export async function setupSwarm({ runtimeRoot, states = [], daemonRequest, ui = createUi(), only = null, clipboard = copy }) {
   const want = (agent) => !only || only === agent;
-  out("\nYour swarm");
-  if (!only) {
-    out("  On this computer: Harness starts them when work is posted");
-    for (const state of states) out(`    ${!state.installed ? "–" : state.configured ? "✓" : "!"} ${state.agent}: ${state.detail}`);
+  if (!only && states.length) {
+    const width = Math.max(...states.map((state) => state.agent.length));
+    const rows = states.map((state) => `${!state.installed ? pc.dim("–") : state.configured ? pc.green("✓") : pc.yellow("!")} ${state.agent.padEnd(width)}  ${pc.dim(state.detail)}`);
+    ui.step(`Coding agents on this computer ${pc.dim("· Harness starts them when work is posted")}\n${rows.join("\n")}`);
   }
   const local = detectLocalAgents().filter((entry) => entry.found && want(entry.agent));
-  if (local.length) out("  Agent apps on this computer: woken by a webhook Harness sets up");
-  for (const entry of local) await setupLocal({ entry, runtimeRoot, prompter, daemonRequest, out });
-  if (only && LABEL[only] && only !== "grok-bot" && !local.length) out(`  ${LABEL[only]} was not found on this computer.`);
+  for (const entry of local) await setupLocal({ entry, runtimeRoot, ui, daemonRequest });
+  if (only && LABEL[only] && only !== "grok-bot" && !local.length) ui.warn(`${LABEL[only]} was not found on this computer.`);
   if (want("grok-bot")) {
-    out("  Cloud agents: woken by email or webhook");
-    await setupGrok({ prompter, daemonRequest, out, clipboard });
+    ui.step(`Grok Bot ${pc.dim("· runs in its own cloud, woken by email or webhook")}`);
+    await setupGrok({ ui, daemonRequest, clipboard });
   }
-  if (!only) out("  Built in: Bankr and Quotient run on Harness, nothing to set up");
+  if (!only) ui.info(`Bankr and Quotient run on Harness ${pc.dim("· nothing to set up")}`);
 }

package/lib/paths.mjs

@@ -16,6 +16,7 @@ export const paths = {
   log: path.join(harnessHome, "daemon.log"),
   phoneIdentity: path.join(harnessHome, "phone-identity.json"),
   runs: path.join(harnessHome, "runs"),
+  files: path.join(harnessHome, "files"),
   runtime: path.join(harnessHome, "runtime"),
   models: path.join(harnessHome, "models"),
   legacyBridgeConfig: path.join(harnessHome, "bridge.json"),

package/lib/phones.mjs

@@ -23,7 +23,7 @@ const PHONE_COMMANDS = new Set([
   "board.thread.read", "board.thread.post", "board.thread.send", "board.thread.discard", "board.thread.auto", "board.thread.end",
   "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",
+  "board.swarm.diff", "board.swarm.merge", "board.swarm.discard", "board.swarm.start_run", "board.swarm.agents", "board.swarm.note",
   // 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",
 ]);

package/lib/runtime-install.mjs

@@ -76,7 +76,7 @@ export function installRuntime({ sourceRoot, version }) {
       if (!fs.existsSync(source)) continue;
       fs.cpSync(source, path.join(staging, entry), { recursive: true, force: true });
     }
-    copyDependencyClosure(sourceRoot, staging, ["node-sqlite3-wasm", "ws", "onnxruntime-web", "@huggingface/tokenizers"]);
+    copyDependencyClosure(sourceRoot, staging, ["node-sqlite3-wasm", "ws", "onnxruntime-web", "@huggingface/tokenizers", "@clack/prompts", "@clack/core", "picocolors"]);
     fs.writeFileSync(path.join(staging, ".ready"), version + "\n", { mode: 0o600 });
     ensureDir(path.dirname(release));
     fs.rmSync(release, { recursive: true, force: true });

package/lib/sealed.mjs

@@ -96,6 +96,15 @@ export async function openBound(key, bound, sealed) {
   const plain = await subtle.decrypt({ name: "AES-GCM", iv: fromB64u(sealed.iv), additionalData: encoder.encode(`HSC1|${bound}`) }, key, fromB64u(sealed.ct));
   return JSON.parse(decoder.decode(plain));
 }
+// A file's bytes, sealed as they are (no JSON or base64 inside): bound to its thread and file id like a message.
+export async function sealBytes(key, bound, bytes) {
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv, additionalData: encoder.encode(`HSC1|${bound}`) }, key, bytes);
+  return { iv: b64u(iv), ct: b64u(new Uint8Array(ct)) };
+}
+export async function openBytes(key, bound, sealed) {
+  return Buffer.from(await subtle.decrypt({ name: "AES-GCM", iv: fromB64u(sealed.iv), additionalData: encoder.encode(`HSC1|${bound}`) }, key, fromB64u(sealed.ct)));
+}
 // What two people read to each other to check they hold each other's key: SHA-256 of the key, 20 hex digits in groups of four.
 export async function fingerprint(publicKey) {
   const digest = Buffer.from(await subtle.digest("SHA-256", fromB64u(publicKey))).toString("hex");

package/lib/store.mjs

@@ -3,7 +3,7 @@ import sqliteWasm from "node-sqlite3-wasm";
 import { parseSession } from "./parsers.mjs";
 import { provenanceFor } from "./provenance.mjs";
 
-const SCHEMA_VERSION = 9;
+const SCHEMA_VERSION = 10;
 const INDEX_FORMAT_VERSION = 2;
 const { Database } = sqliteWasm;
 
@@ -185,6 +185,20 @@ export function openStore(file) {
       version text not null,
       vector blob not null
     );
+    create table if not exists board_files (
+      id text primary key,
+      task_id text not null,
+      name text not null,
+      mime text not null,
+      bytes integer,
+      sha256 text,
+      author text not null,
+      cloud integer not null default 0,
+      remote_id text,
+      present integer not null default 0,
+      created_at text not null
+    );
+    create index if not exists board_files_task_idx on board_files(task_id, created_at);
   `);
   const sessionColumns = new Set(db.all("pragma table_info(sessions)").map((column) => column.name));
   if (!sessionColumns.has("parser_version")) {
@@ -689,6 +703,46 @@ export function openStore(file) {
     relayPeers() {
       return execute("all", "select handle, public_key, pinned_at from relay_peers order by pinned_at desc");
     },
+    // Files on a task. A file this machine has is present; one another person's computer is sending is named by its
+    // message first or arrives first, and is matched by the id that computer gave it (remote_id), never by ours.
+    addFile({ taskId, name, mime, bytes, sha256, author, cloud = false }) {
+      const id = randomUUID();
+      execute("run", `insert into board_files(id, task_id, name, mime, bytes, sha256, author, cloud, present, created_at) values(@id, @taskId, @name, @mime, @bytes, @sha256, @author, @cloud, 1, @now)`,
+        { id, taskId, name, mime, bytes, sha256, author, cloud: cloud ? 1 : 0, now: new Date().toISOString() });
+      execute("run", "update board_tasks set updated_at = ?, version = version + 1 where id = ?", new Date().toISOString(), taskId);
+      return this.file(id);
+    },
+    file(id) {
+      const row = execute("get", "select * from board_files where id = ?", String(id));
+      return row ? { ...row, bytes: row.bytes == null ? null : Number(row.bytes), cloud: Number(row.cloud) === 1, present: Number(row.present) === 1 } : null;
+    },
+    taskFiles(taskId) {
+      return execute("all", "select id from board_files where task_id = ? order by created_at asc", taskId).map((row) => this.file(row.id));
+    },
+    // The other computer's message names a file it sends: kept with the hash it promised, which its bytes must match.
+    expectFile({ taskId, remoteId, name, mime, sha256, author }) {
+      const known = execute("get", "select id, sha256, present from board_files where task_id = ? and remote_id = ?", taskId, remoteId);
+      if (known && Number(known.present) === 1 && known.sha256 !== sha256) return { ok: false, error: "a file arrived with other bytes than its message promised" };
+      if (known) {
+        execute("run", "update board_files set name = ?, mime = ?, sha256 = ?, author = ? where id = ?", name, mime, sha256, author, known.id);
+        return { ok: true, file: this.file(known.id) };
+      }
+      const id = randomUUID();
+      execute("run", `insert into board_files(id, task_id, name, mime, sha256, author, remote_id, present, created_at) values(@id, @taskId, @name, @mime, @sha256, @author, @remoteId, 0, @now)`,
+        { id, taskId, name, mime, sha256, author, remoteId, now: new Date().toISOString() });
+      return { ok: true, file: this.file(id) };
+    },
+    receiveFile({ taskId, remoteId, sha256, bytes, author }) {
+      const known = execute("get", "select id, sha256, present from board_files where task_id = ? and remote_id = ?", taskId, remoteId);
+      if (known && Number(known.present) === 1) return { ok: true, duplicate: true, file: this.file(known.id) };
+      if (known && known.sha256 && known.sha256 !== sha256) return { ok: false, error: "a file arrived with other bytes than its message promised" };
+      const id = known?.id || randomUUID();
+      if (known) execute("run", "update board_files set sha256 = ?, bytes = ?, present = 1 where id = ?", sha256, bytes, id);
+      else execute("run", `insert into board_files(id, task_id, name, mime, bytes, sha256, author, remote_id, present, created_at) values(@id, @taskId, 'file', 'application/octet-stream', @bytes, @sha256, @author, @remoteId, 1, @now)`,
+        { id, taskId, bytes, sha256, author, remoteId, now: new Date().toISOString() });
+      execute("run", "update board_tasks set updated_at = ?, version = version + 1 where id = ?", new Date().toISOString(), taskId);
+      return { ok: true, file: this.file(id) };
+    },
     getThread(taskId) {
       const row = execute("get", "select * from board_threads where task_id = ?", taskId);
       return row ? { ...row, auto_send: Number(row.auto_send) === 1 } : null;
@@ -713,11 +767,11 @@ export function openStore(file) {
       this.addContribution({ id: `msg:${id}`, taskId, kind: "message", author: sender, text, source: `message:${id}` });
       return { ok: true, message: this.threadMessages(taskId).find((message) => message.id === id) };
     },
-    postMessage({ id, taskId, sender, text, refs = [], flagReason = null }) {
+    postMessage({ id, taskId, sender, text, refs = [], flagReason = null, hold = false }) {
       const thread = this.getThread(taskId);
       if (!thread) return { ok: false, error: "no thread on this task" };
       if (thread.closed_at) return { ok: false, error: "the thread is closed" };
-      const state = flagReason ? "flagged" : thread.auto_send ? "sent" : "held";
+      const state = flagReason ? "flagged" : thread.auto_send && !hold ? "sent" : "held";
       const now = new Date().toISOString();
       execute("run", `insert into board_messages(id, task_id, seq, direction, sender, recipient, text, refs, state, flag_reason, created_at, sent_at)
         values(@id, @taskId, @seq, 'out', @sender, @recipient, @text, @refs, @state, @flagReason, @now, @sentAt)`,
@@ -819,6 +873,14 @@ export function openStore(file) {
     agentsSeen() {
       return execute("all", "select agent, last_seen_at from board_agents order by last_seen_at desc");
     },
+    // Each agent's work on the board, newest first, for its card (cards.mjs): what it holds and finished, and when it
+    // could start (the person's Start, else the post) and reported.
+    agentWork() {
+      return execute("all", `select coalesce(claimed_by, target_agent) as agent, status, target_agent is not null as targeted,
+        coalesce(run_authorized_at, created_at) as started_at, reported_at from board_tasks
+        where kind in ('task', 'wake') and removed_at is null and coalesce(claimed_by, target_agent) is not null
+        order by updated_at desc limit 5000`);
+    },
     listTasks({ agent, status, all = false, limit = 20 } = {}) {
       const clauses = ["b.removed_at is null"];
       const params = { limit: Math.max(1, Math.min(100, Number(limit) || 20)) };

package/lib/swarm.mjs

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { readRunSteps } from "./runner.mjs";
-import { member, nameOf } from "./members.mjs";
+import { nameOf, resolveMember } from "./members.mjs";
+import { setNote, swarmBlock, swarmCards, swarmDigest } from "./cards.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
@@ -11,9 +12,6 @@ import { member, nameOf } from "./members.mjs";
 
 const PROCESS_NAMES = { "claude-code": "claude", codex: "codex", pi: "pi", opencode: "opencode" };
 const SAY_LIMIT = 4_000;
-// How a member hears that work is waiting for it, by its roster wake.
-const ANSWERS = { run: "starts as soon as it may", email: "woken by email when work is posted", webhook: "woken when work is posted", "local-webhook": "woken when work is posted",
-  schedule: "picks work up on its own schedule", none: "only when the person next talks to it" };
 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.
@@ -155,10 +153,11 @@ export function createSwarm({ store, roomAgents, mentionsIn, wakeFor, notifyBoar
       const mine = request.teamOnly ? store.goals({ all: true }).filter((thread) => thread.goal.team.includes(agent)).map((thread) => thread.id) : null;
       return { ok: true, threads: store.searchThreads(query, { goalIds: mine, k: 8 }), sessions: request.teamOnly ? [] : store.search({ query, limit: 5 }) };
     }
-    // Who can be asked, and how each answers: open to every caller, so an agent picks a name instead of guessing one.
+    // Who can be asked: every other agent's card (cards.mjs), and the same cards as the block an agent is told when its
+    // session starts. Open to every caller, so an agent picks a name instead of guessing one.
     if (command === "board.swarm.agents") {
-      const seen = new Map(store.agentsSeen().map((row) => [row.agent, row.last_seen_at]));
-      return { ok: true, agents: roster().filter((entry) => entry.id !== agent).map((entry) => ({ ...entry, name: nameOf(entry.id), answers: ANSWERS[member(entry.id)?.wake] ?? "when it next looks", lastSeen: seen.get(entry.id) ?? null })) };
+      const agents = swarmCards(store, roster().filter((entry) => entry.id !== agent));
+      return { ok: true, agents, text: swarmBlock(agents), digest: swarmDigest(agents) };
     }
     // 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
@@ -186,6 +185,12 @@ 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" };
+    // 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 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") {