catherd-cli 0.2.1 → 1.1.0

package/src/services/milestones.ts

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import type { RunRecord } from "../domain/record.ts";
+import { git } from "../infra/git.ts";
+import { nonBlankLines } from "../infra/store.ts";
+import { listDispatches } from "./dispatches.ts";
+import { readAgentRuns, readRecords, readRoutes, type Run, runPaths } from "./run-store.ts";
+
+// Spec 1.1 §6 and §10: what a milestone has been through, read from the run's own records. `land` gates on
+// it, and the protocol's next step is derived from it.
+
+/** Where a milestone name may end inside a longer name: the end, '-', '.', '_' or whitespace (M1-fix, M1.2). */
+const MILESTONE_END = String.raw`(?=$|[-._\s])`;
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** `name` names milestone `m` as a word: verifier-M1 and M1-verifier do; verifier-M10 and verifier-M1fix do not. */
+export const namesMilestone = (name: string, m: string): boolean =>
+  new RegExp(`(^|[^A-Za-z0-9])${escapeRe(m)}${MILESTONE_END}`).test(name);
+
+/** `name` is milestone `m`'s reviewer: reviewer-<m>, the milestone ending as in namesMilestone (reviewer-M10 is not M1's). */
+export const reviewsMilestone = (name: string, m: string): boolean =>
+  new RegExp(`^reviewer-${escapeRe(m)}${MILESTONE_END}`).test(name);
+
+const inMilestone = (lane: string | null | undefined, m: string): boolean =>
+  typeof lane === "string" && lane.startsWith(`${m}.`);
+
+/**
+ * When the milestone's lanes started: its earliest route row or lane dispatch; null when neither exists
+ * (a milestone with no lanes, such as a docs pass), and every record of the run then counts.
+ */
+export function milestoneStart(run: Run, m: string): string | null {
+  const times = [
+    ...readRoutes(run)
+      .filter((r) => inMilestone(r.lane, m))
+      .map((r) => r.at),
+    ...listDispatches(run)
+      .filter((d) => inMilestone(d.admit.lane, m))
+      .map((d) => d.admit.admittedAt),
+  ].filter((t) => !Number.isNaN(Date.parse(t)));
+  return times.sort()[0] ?? null;
+}
+
+const since = (at: string, start: string | null) => start === null || Date.parse(at) >= Date.parse(start);
+
+/** The milestone's reviewer: its dispatch record, or null for a native Claude subagent (record_agent_run). */
+export interface MilestoneReviewer {
+  name: string;
+  at: string;
+  record: RunRecord | null;
+}
+
+/**
+ * The milestone's latest passing reviewer since its lanes started: a dispatch named reviewer-<m>…, status
+ * ok; or a record_agent_run row with role reviewer and the same name, status ok. Null when there is none.
+ */
+export function milestoneReviewer(
+  run: Run,
+  m: string,
+  start = milestoneStart(run, m),
+): MilestoneReviewer | null {
+  const found: MilestoneReviewer[] = [
+    ...readRecords(run)
+      .records.filter((r) => reviewsMilestone(r.name, m) && r.status === "ok" && since(r.endedAt, start))
+      .map((r) => ({ name: r.name, at: r.endedAt, record: r })),
+    ...readAgentRuns(run)
+      .filter(
+        (a) =>
+          a.role === "reviewer" && reviewsMilestone(a.name, m) && a.status === "ok" && since(a.at, start),
+      )
+      .map((a) => ({ name: a.name, at: a.at, record: null })),
+  ];
+  return found.sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).at(-1) ?? null;
+}
+
+/** A reviewer record for the milestone since its lanes started (see milestoneReviewer). */
+export const reviewerPassed = (run: Run, m: string, start = milestoneStart(run, m)): boolean =>
+  milestoneReviewer(run, m, start) !== null;
+
+/** The verifier's contract puts `VERDICT: PASS` or `VERDICT: FAIL` on the reply's first line (role-prompts.ts). */
+const VERDICT_PASS = /^VERDICT: PASS\b/;
+
+/** A headless verifier's reply: its first non-blank line, trimmed; null when there is no reply to read. */
+export function replyVerdict(run: Run, r: RunRecord): string | null {
+  const file = join(run.dir, r.replyPath);
+  if (!r.replyPath || !existsSync(file)) return null;
+  return (
+    readFileSync(file, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .find(Boolean) ?? null
+  );
+}
+
+/** A headless verifier's reply opens with VERDICT: PASS: its first non-blank line; no reply is no verdict. */
+export function replyPasses(run: Run, r: RunRecord): boolean {
+  const first = replyVerdict(run, r);
+  return first !== null && VERDICT_PASS.test(first);
+}
+
+/** The milestone's latest verifier attempt: a native Claude subagent or a headless dispatch, passed or not. */
+export interface MilestoneVerifier {
+  name: string;
+  at: string;
+  headless: boolean;
+  passed: boolean;
+  /** what the attempt said: a native row's status, or a headless reply's first non-blank line ("no reply") */
+  verdict: string;
+}
+
+/**
+ * The milestone's latest verifier attempt since its lanes started, whatever it said: a record_agent_run row
+ * with role verifier whose name names the milestone (the skill records a FAIL as failed), passing when its
+ * status is ok; or a headless verifier's dispatch record of the same shape, passing when it exited ok and its
+ * reply opens VERDICT: PASS (status ok means only the CLI exited). A later FAIL undoes an earlier PASS. Null
+ * when there is none.
+ */
+export function milestoneVerifier(
+  run: Run,
+  m: string,
+  start = milestoneStart(run, m),
+): MilestoneVerifier | null {
+  const found: MilestoneVerifier[] = [
+    ...readAgentRuns(run)
+      .filter((a) => a.role === "verifier" && namesMilestone(a.name, m) && since(a.at, start))
+      .map((a) => ({
+        name: a.name,
+        at: a.at,
+        headless: false,
+        passed: a.status === "ok",
+        verdict: a.status,
+      })),
+    ...readRecords(run)
+      .records.filter((r) => r.role === "verifier" && namesMilestone(r.name, m) && since(r.endedAt, start))
+      .map((r) => {
+        const first = replyVerdict(run, r);
+        const passed = r.status === "ok" && first !== null && VERDICT_PASS.test(first);
+        const said = first === null ? "no reply" : first.length > 80 ? `${first.slice(0, 80)}…` : first;
+        return {
+          name: r.name,
+          at: r.endedAt,
+          headless: true,
+          passed,
+          verdict: r.status === "ok" ? said : `${r.status}, ${said}`,
+        };
+      }),
+  ];
+  // a stable sort: attempts at the same instant keep their file order, the later row winning
+  return found.sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).at(-1) ?? null;
+}
+
+/** The milestone's latest verifier attempt since its lanes started passed (see milestoneVerifier). */
+export const verifierPassed = (run: Run, m: string, start = milestoneStart(run, m)): boolean =>
+  milestoneVerifier(run, m, start)?.passed === true;
+
+/** The commits of the landed milestones, oldest first, from the ledger. */
+export function landedCommits(run: Run): string[] {
+  return nonBlankLines(runPaths(run.dir).ledger)
+    .slice(1)
+    .map((row) => row.split(" | ")[2]?.trim() ?? "")
+    .filter((c) => /^[0-9a-f]{7,40}$/.test(c));
+}
+
+/** The milestones the ledger holds, in landing order. */
+export function landedMilestones(run: Run): string[] {
+  return nonBlankLines(runPaths(run.dir).ledger)
+    .slice(1)
+    .map((row) => row.split(" | ")[0]?.trim() ?? "")
+    .filter(Boolean);
+}
+
+/**
+ * The files the milestone's commit range changed: from the previous landed commit (else the commit's own
+ * parent) to `commit`. Throws E_IO_UNEXPECTED when git cannot say.
+ */
+export async function milestoneFiles(run: Run, commit: string): Promise<string[]> {
+  const base = landedCommits(run).at(-1);
+  const repo = run.meta.repo;
+  const r = base
+    ? await git(repo, ["diff", "--name-only", base, commit])
+    : await git(repo, ["show", "--name-only", "--format=", "--first-parent", commit]);
+  if (r.kind !== "ok")
+    throw new CatherdError("E_IO_UNEXPECTED", `git could not list the files ${commit} changed`, {
+      fix: `check that git works in ${repo}`,
+    });
+  return r.out.split("\n").filter(Boolean);
+}
+
+/** `rev`'s full commit hash in the run's repo. Throws E_IO_UNEXPECTED when git cannot say. */
+export async function fullCommit(run: Run, rev: string): Promise<string> {
+  const r = await git(run.meta.repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
+  const sha = r.kind === "ok" ? r.out.trim() : "";
+  if (!sha)
+    throw new CatherdError("E_IO_UNEXPECTED", `git could not resolve ${rev} in ${run.meta.repo}`, {
+      fix: `check that git works in ${run.meta.repo}`,
+    });
+  return sha;
+}
+
+/** the repo's own docs/ folder, or a doc extension anywhere: app/docs/page.tsx is code */
+const DOC = /^docs\/|\.(md|mdx|markdown|txt|rst|adoc)$/i;
+/** .txt files that configure a build or pin dependencies: not docs */
+const TXT_MANIFEST = /(^|\/)(requirements[^/]*|constraints[^/]*|CMakeLists)\.txt$/i;
+const SOURCE =
+  /\.(ts|tsx|js|jsx|mjs|cjs|go|py|rs|java|kt|kts|swift|rb|php|c|h|cc|cpp|hpp|cs|m|scala|sh|bash|zsh|sql|vue|svelte|css|scss|sass|less|html|dart|ex|exs|erl|zig|lua)$/i;
+
+export const isDocPath = (p: string): boolean => DOC.test(p) && !TXT_MANIFEST.test(p);
+export const isSourcePath = (p: string): boolean => SOURCE.test(p) && !isDocPath(p);

package/src/services/notifier.ts

@@ -0,0 +1,296 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { errorMessage } from "../domain/errors.ts";
+import { envelope, formatNotices, type Notice, type NoticePriority, priorityOf } from "../domain/notice.ts";
+import type { RunRecord } from "../domain/record.ts";
+import { awaitsCollect, dispatchPaths } from "../infra/dispatch-dir.ts";
+import { tryLock } from "../infra/filelock.ts";
+import { log } from "../infra/log.ts";
+import { type SendResult, sendToInbox } from "../infra/peer-inbox.ts";
+import { writeJsonAtomic } from "../infra/store.ts";
+import { type Settled, settledHooks, type Stalled, stallHooks } from "./dispatch-service.ts";
+import { type Dispatch, listDispatches, readFailover } from "./dispatches.ts";
+import type { Deps } from "./ports.ts";
+import { listRuns, readRecords, type Run } from "./run-store.ts";
+import { currentSession, ownsRun } from "./sessions.ts";
+
+/**
+ * Spec §3.4: runs only inside the MCP server, the session's child and so its only sender (§3.2). For every run this
+ * session owns, a dispatch that is settled with its record still unread is announced to the session's peer inbox;
+ * notices that arrive within the window of each other go as one message; a message that went out is written down
+ * (`notified.json`), so a restart never sends it twice, and claimed while it goes, so two servers of one session never
+ * both send it. Ownership is asked again under the claim and once more after the message went: a run another session
+ * claimed meanwhile is left unmarked, so its new owner announces it too (a copy to the session that gave the run up is
+ * acceptable, a notice lost to the owner is not); a notice whose claim another server holds is tried again after the
+ * window until it is sent, read, marked or no longer this session's. Disk stays the truth: a notice that cannot be
+ * sent is dropped (its claim freed), and the record waits, unread, for `result` or `peek`.
+ */
+
+export interface NotifierOptions {
+  /** notices this close to each other go as one message (spec: 3 s); tests shorten it */
+  coalesceMs?: number;
+  /** the sender; tests may replace it */
+  send?: (
+    target: { socketPath: string | null; token: string | null },
+    content: string,
+    p: NoticePriority,
+  ) => Promise<SendResult>;
+}
+
+export interface Notifier {
+  /** the settled hook: queues the dispatch's notice when this session should hear of it */
+  onSettled(s: Settled): void;
+  /** the stall hook: queues a stalled role's notice, once per dispatch */
+  onStall(s: Stalled): void;
+  /** spec §3.4 "a scan on start": every unread, un-notified record of a run this session owns */
+  scan(): Promise<void>;
+  /** resolves once nothing is queued and no message is on its way */
+  idle(): Promise<void>;
+  /** removes the hook and drops what is queued */
+  stop(): void;
+}
+
+const notified = (dir: string): boolean => existsSync(dispatchPaths(dir).notified);
+
+function replyOf(run: Run, r: RunRecord): string {
+  try {
+    return readFileSync(join(run.dir, r.replyPath), "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Spec §3.5/§3.6: one finished role's notice, with what failover did in place of a limit's status. */
+export function finishedNotice(run: Run, d: Dispatch, r: RunRecord): Notice {
+  const fo = readFailover(d.dir);
+  let status: string = r.status;
+  if (r.status === "limit") {
+    const why = fo?.standIn
+      ? `failed over to ${fo.standIn.rung}`
+      : fo?.hints.some((h) => h.startsWith("failover: run "))
+        ? "its stand-in is a Claude agent: result(run, name) has the hint"
+        : fo?.hints.some((h) => h.startsWith("failover: "))
+          ? "paused: the stand-in was refused"
+          : "paused: no stand-in";
+    status = `limit on ${r.rung}; ${why}`;
+  }
+  const urgent = r.status === "limit" || r.replyStatus === "blocked" || r.replyStatus === "refused";
+  return {
+    kind: "finished",
+    runId: run.id,
+    runTitle: run.meta.title,
+    dispatchId: r.dispatchId,
+    name: r.name,
+    role: r.role,
+    lane: r.lane,
+    rung: r.rung,
+    status,
+    replyStatus: r.replyStatus,
+    secs: r.secs,
+    changedOwned: r.changedOwned.length,
+    reply: replyOf(run, r),
+    priority: urgent ? "next" : "later",
+  };
+}
+
+/** Spec §3.6: a live role that went quiet, once, at `next`. */
+export function stalledNotice(run: Run, d: Dispatch, quietMs: number, now: number): Notice {
+  return {
+    kind: "stalled",
+    runId: run.id,
+    runTitle: run.meta.title,
+    dispatchId: d.admit.dispatchId,
+    name: d.admit.name,
+    role: d.admit.role,
+    lane: d.admit.lane,
+    rung: d.admit.rung,
+    status: `stalled: no output for ${Math.max(1, Math.round(quietMs / 60_000))} min`,
+    replyStatus: null,
+    secs: Math.max(0, Math.round((now - Date.parse(d.admit.admittedAt)) / 1000)),
+    changedOwned: 0,
+    reply: "",
+    priority: "next",
+  };
+}
+
+interface Queued {
+  /** its key in the queue */
+  key: string;
+  /** the run it is about: its owner may change before the message goes */
+  run: Run;
+  notice: Notice;
+  /** the mark a message that went out leaves */
+  mark: string;
+  /** whether it is still news when the message goes */
+  due: () => boolean;
+}
+
+/** Starts the notifier for this process's session and hooks it to every settled dispatch. */
+export function startNotifier(deps: Deps, o: NotifierOptions = {}): Notifier {
+  const window = o.coalesceMs ?? 3_000;
+  const send = o.send ?? sendToInbox;
+  const queue = new Map<string, Queued>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let firstAt = 0;
+  let flight: Promise<void> = Promise.resolve();
+  let stopped = false;
+
+  /** This session's id, when there is one and it owns the run. */
+  const owned = (run: Run): boolean => ownsRun(deps, run);
+
+  const flush = (): void => {
+    timer = null;
+    const batch = [...queue.values()];
+    queue.clear();
+    // a delivery that throws (the notified.json write, say) is logged and never stops the ones after it
+    flight = flight
+      .then(() => deliver(batch))
+      .catch((e: unknown) =>
+        log("warn", "notify", { error: errorMessage(e), dispatches: batch.map((q) => q.notice.dispatchId) }),
+      );
+  };
+
+  const schedule = (): void => {
+    const now = Date.now();
+    if (timer === null) firstAt = now;
+    else clearTimeout(timer);
+    // quiet for `window`, but never held past five windows: a steady trickle still goes out
+    timer = setTimeout(flush, Math.max(0, Math.min(window, firstAt + 5 * window - now)));
+  };
+
+  async function deliver(batch: Queued[]): Promise<void> {
+    if (!deps.session) return;
+    // Each notice is claimed before it goes (an exclusive lock on its mark, freed if its holder dies): two servers
+    // of one session, a replacement starting while the old one still watches, never both send it. Whether it is
+    // still news is asked under the claim: the other may have announced it just before letting go.
+    const claims: (() => void)[] = [];
+    const due: Queued[] = [];
+    const busy: Queued[] = [];
+    try {
+      for (const q of batch) {
+        // read (or announced) meanwhile, or the run moved to another session (whose server tells it)
+        if (!q.due() || !owned(q.run)) continue;
+        const release = tryLock(q.mark);
+        // another server is announcing it: asked again after the window, since that server may leave it unmarked
+        // (the run moved to this session while its message was on its way)
+        if (!release) {
+          busy.push(q);
+          continue;
+        }
+        claims.push(release);
+        // asked again under the claim: the run may have moved, or the notice gone out, while it was taken
+        if (q.due() && owned(q.run)) due.push(q);
+      }
+      if (due.length === 0) return;
+      const notices = due.map((q) => q.notice);
+      const r = await send(
+        { socketPath: deps.session.socketPath, token: deps.session.token },
+        envelope(formatNotices(notices)),
+        priorityOf(notices),
+      ).catch((e: unknown): SendResult => ({ outcome: "error", reason: errorMessage(e) }));
+      if (r.outcome !== "sent") {
+        log("warn", "notify", {
+          outcome: r.outcome,
+          reason: r.reason,
+          dispatches: notices.map((n) => n.dispatchId),
+        });
+        return;
+      }
+      const at = new Date(deps.now()).toISOString();
+      // a run that moved while the message was on its way is left unmarked: its new owner announces it too
+      const marked = due.filter((q) => owned(q.run));
+      for (const q of marked) writeJsonAtomic(q.mark, { schema: 1, msgId: r.msgId, at });
+      const unmarked = due.filter((q) => !marked.includes(q)).map((q) => q.notice.dispatchId);
+      log("info", "notify", { msgId: r.msgId, dispatches: notices.map((n) => n.dispatchId), unmarked });
+    } finally {
+      for (const release of claims) release();
+      requeue(busy);
+    }
+  }
+
+  /** Queues again the notices another server held the claim on; the next pass drops those no longer due or owned. */
+  function requeue(busy: Queued[]): void {
+    if (stopped || busy.length === 0) return;
+    for (const q of busy) if (!queue.has(q.key)) queue.set(q.key, q);
+    schedule();
+  }
+
+  const enqueue = (run: Run, d: Dispatch, record: RunRecord): void => {
+    if (queue.has(record.dispatchId) || notified(d.dir) || !awaitsCollect(d.dir) || !owned(run)) return;
+    queue.set(record.dispatchId, {
+      key: record.dispatchId,
+      run,
+      notice: finishedNotice(run, d, record),
+      mark: dispatchPaths(d.dir).notified,
+      due: () => awaitsCollect(d.dir) && !notified(d.dir),
+    });
+    schedule();
+  };
+
+  const onStall = (s: Stalled): void => {
+    try {
+      const p = dispatchPaths(s.d.dir);
+      const key = `${s.d.admit.dispatchId} stall`;
+      if (queue.has(key) || existsSync(p.stallNotified) || existsSync(p.exit) || !owned(s.run)) return;
+      queue.set(key, {
+        key,
+        run: s.run,
+        notice: stalledNotice(s.run, s.d, s.quietMs, deps.now()),
+        mark: p.stallNotified,
+        // it finished meanwhile: its record is the news now
+        due: () => !existsSync(p.stallNotified) && !existsSync(p.exit),
+      });
+      schedule();
+    } catch (e) {
+      log("warn", "notify", { run: s.run.id, name: s.d.admit.name, error: errorMessage(e) });
+    }
+  };
+
+  const onSettled = (s: Settled): void => {
+    try {
+      enqueue(s.run, s.d, s.record);
+    } catch (e) {
+      log("warn", "notify", { run: s.run.id, name: s.d.admit.name, error: errorMessage(e) });
+    }
+  };
+
+  const n: Notifier = {
+    onSettled,
+    onStall,
+    async scan() {
+      if (!currentSession(deps)) return;
+      for (const run of listRuns().runs) {
+        try {
+          if (!owned(run)) continue;
+          const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+          for (const d of listDispatches(run)) {
+            const r = records.get(d.admit.dispatchId);
+            // a limit not yet failed over is reconcile's to settle first: its hook announces it then
+            if (r && !(r.status === "limit" && !readFailover(d.dir))) enqueue(run, d, r);
+          }
+        } catch (e) {
+          log("warn", "notify", { run: run.id, error: errorMessage(e) });
+        }
+      }
+    },
+    async idle() {
+      for (;;) {
+        if (timer === null && queue.size === 0) {
+          await flight;
+          if (timer === null && queue.size === 0) return;
+        } else await Bun.sleep(5);
+      }
+    },
+    stop() {
+      stopped = true;
+      settledHooks.delete(onSettled);
+      stallHooks.delete(onStall);
+      if (timer !== null) clearTimeout(timer);
+      timer = null;
+      queue.clear();
+    },
+  };
+  settledHooks.add(onSettled);
+  stallHooks.add(onStall);
+  return n;
+}

package/src/services/peek.ts

@@ -0,0 +1,103 @@
+import { assertId } from "../domain/ids.ts";
+import { noticeHeader } from "../domain/notice.ts";
+import { awaitsCollect } from "../infra/dispatch-dir.ts";
+import { claim } from "./dispatch-service.ts";
+import { type Dispatch, type DispatchState, listDispatches, liveDispatches } from "./dispatches.ts";
+import { lastActivity } from "./finalize.ts";
+import { finishedNotice } from "./notifier.ts";
+import type { Deps } from "./ports.ts";
+import { type Reentry, reentry } from "./reentry.ts";
+import { findRun, listRuns, readAgentRuns, readRecords, type Run } from "./run-store.ts";
+import { currentSession, runOwner } from "./sessions.ts";
+import { readNotes } from "./state.ts";
+
+export interface PeekRole {
+  name: string;
+  role: string;
+  rung: string;
+  state: DispatchState;
+  /** since admission */
+  secs: number;
+  /** the last command, file edit or message line, else the last event's name; null before any event */
+  lastEvent: string | null;
+}
+
+/** Spec 1.1 §8/§10: the open owner questions come first, then the run, its protocol step and the verifier's step. */
+export interface PeekRun extends Reentry {
+  run: string;
+  title: string;
+  /** the session that owns the run now, null when none has */
+  owner: string | null;
+  live: PeekRole[];
+  /** each finished record not yet read, as the first line of its message */
+  unread: { name: string; dispatchId: string; header: string }[];
+  /** the latest native Claude run recorded with record_agent_run */
+  native: { name: string; role: string; rung: string; status: string; at: string } | null;
+  /** the run's next step (state.md's last line) */
+  next: string;
+}
+
+function peekRun(deps: Deps, run: Run, name: string | undefined): PeekRun {
+  const now = deps.now();
+  const mine = (d: Dispatch) => name === undefined || d.admit.name === name;
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const agents = readAgentRuns(run).filter((a) => name === undefined || a.name === name);
+  const native = agents.at(-1);
+  const r = reentry(run, now);
+  return {
+    questions: r.questions,
+    run: run.id,
+    title: run.meta.title,
+    owner: runOwner(run)?.sessionId ?? null,
+    live: liveDispatches(run, now)
+      .filter(mine)
+      .map((d) => ({
+        name: d.admit.name,
+        role: d.admit.role,
+        rung: d.admit.rung,
+        state: d.state,
+        secs: Math.max(0, Math.round((now - Date.parse(d.admit.admittedAt)) / 1000)),
+        lastEvent: lastActivity(d),
+      })),
+    unread: listDispatches(run)
+      .filter(mine)
+      .flatMap((d) => {
+        const r = records.get(d.admit.dispatchId);
+        return r && awaitsCollect(d.dir)
+          ? [{ name: r.name, dispatchId: r.dispatchId, header: noticeHeader(finishedNotice(run, d, r)) }]
+          : [];
+      }),
+    native: native
+      ? { name: native.name, role: native.role, rung: native.rung, status: native.status, at: native.at }
+      : null,
+    next: readNotes(run).next,
+    protocol: r.protocol,
+    verifier: r.verifier,
+  };
+}
+
+/**
+ * Spec §3.7 `peek(run?, name?)`: never waits, never marks a record read. With a run it makes this session the
+ * run's owner (spec §3.3) and watches the roles another session's server launched; without one it shows every run
+ * this session owns, else the newest run.
+ */
+export async function peek(
+  deps: Deps,
+  i: { run?: string; name?: string },
+): Promise<{ runs: PeekRun[]; hints: string[] }> {
+  if (i.name !== undefined) assertId("role name", i.name);
+  let runs: Run[];
+  if (i.run) {
+    const run = findRun(i.run);
+    // ownership now; what the run's earlier owner left is taken care of after the call returns
+    await claim(deps, run, { background: true });
+    runs = [run];
+  } else {
+    const all = listRuns().runs;
+    const me = currentSession(deps);
+    const owned = me ? all.filter((r) => runOwner(r)?.sessionId === me.sessionId) : [];
+    runs = owned.length ? owned : all.slice(0, 1);
+  }
+  const hints = runs.length === 0 ? ["no runs yet: run_start(repo, title, a_lines) starts one"] : [];
+  return { runs: runs.map((r) => peekRun(deps, r, i.name)), hints };
+}