@ccmsg/cli 0.1.0

package/src/sessions/workspace.ts

@@ -0,0 +1,140 @@
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
+import type { WorkspaceFolder } from "@ccmsg/protocol";
+
+/** The folders a session's editor workspace names, read where the editor
+ * writes them.
+ *
+ * Not folded out of the transcript, because the transcript does not carry them:
+ * the harness records what was said and done in a session, and no record of any
+ * kind names an editor workspace. The old daemon read them the same way, from
+ * the workspace file beside the session's working directory, and that file is
+ * the only place the folders are stated.
+ *
+ * A session that has no workspace file names no folders, which is what an empty
+ * list means to the contract and admits no `workspace` path at all. */
+export function workspaceFolders(cwd: string | undefined): WorkspaceFolder[] {
+  if (cwd === undefined || !isAbsolute(cwd)) return [];
+  const folders: WorkspaceFolder[] = [];
+  const seen = new Set<string>();
+  for (const file of workspaceFiles(cwd)) {
+    for (const spec of specs(file)) {
+      // Relative to the workspace file, which is how an editor reads them.
+      const real = directory(resolve(dirname(file), spec.path));
+      if (real === undefined || overbroad(real) || seen.has(real)) continue;
+      seen.add(real);
+      folders.push({ name: spec.name ?? basename(real), path: real });
+    }
+  }
+  return folders;
+}
+
+/** The workspace files directly beside the session's working directory, in a
+ * fixed order so the same directory always states its folders the same way. */
+function workspaceFiles(cwd: string): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(cwd);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => name.endsWith(WORKSPACE_SUFFIX))
+    .sort()
+    .map((name) => resolve(cwd, name));
+}
+
+/** What one workspace file declares: the `folders` array, and of each entry the
+ * path it names and the name it may give that path. */
+function specs(file: string): { path: string; name?: string }[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(uncommented(readFileSync(file, "utf8")));
+  } catch {
+    // Written by hand and half-saved, or not a workspace file after all.
+    return [];
+  }
+  if (typeof parsed !== "object" || parsed === null) return [];
+  const declared = (parsed as Record<string, unknown>)["folders"];
+  if (!Array.isArray(declared)) return [];
+  const specs: { path: string; name?: string }[] = [];
+  for (const entry of declared) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const row = entry as Record<string, unknown>;
+    const path = row["path"];
+    if (typeof path !== "string" || path.length === 0) continue;
+    const name = row["name"];
+    specs.push({
+      path,
+      ...(typeof name === "string" && name.length > 0 ? { name } : {}),
+    });
+  }
+  return specs;
+}
+
+/** A workspace file is JSON with comments and trailing commas, which the
+ * editors that write it accept. Stripped rather than parsed by a second
+ * grammar: what survives is the JSON the file already is. Strings are tracked
+ * so that a `//` inside a path is not mistaken for a comment. */
+function uncommented(text: string): string {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i] as string;
+    if (inString) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    const next = text[i + 1];
+    if (char === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") i += 1;
+      out += "\n";
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end < 0 ? text.length : end + 1;
+      continue;
+    }
+    out += char;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+}
+
+/** What the filesystem calls a folder that is one. A path naming a file, or
+ * nothing at all, names no folder and is dropped. */
+function directory(path: string): string | undefined {
+  try {
+    const real = realpathSync(path);
+    return statSync(real).isDirectory() ? real : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether admitting a folder would admit far more than a workspace.
+ *
+ * The root and the home directory and anything above them are refused: a
+ * workspace file naming one of those turns the `workspace` surface into the
+ * whole filesystem, and the folders are an allowlist rather than a hint. */
+function overbroad(real: string): boolean {
+  if (real === sep || dirname(real) === real) return true;
+  const home = directory(homedir());
+  return home !== undefined && (real === home || home.startsWith(withSep(real)));
+}
+
+function withSep(path: string): string {
+  return path.endsWith(sep) ? path : path + sep;
+}
+
+const WORKSPACE_SUFFIX = ".code-workspace";

package/src/topics/handlers.ts

@@ -0,0 +1,42 @@
+import type { TopicSubscribeArgs, TopicSubscribeResult } from "@ccmsg/protocol";
+import { type HandlerInput, OpError } from "../dispatch/index.ts";
+import type { SubscribeOutcome, Topics } from "./topics.ts";
+
+/** The two ops that reach the topic mechanism. They carry no logic: dispatch
+ * has already validated and allowed the call, so each one names a topic, hands
+ * it to `Topics`, and turns the outcome into the contract's own answer. */
+export function topicHandlers(topics: Topics) {
+  return {
+    topic_subscribe: (input: HandlerInput): TopicSubscribeResult => {
+      const topic = topicOf(input);
+      answer(topics.subscribe(input.conn, topic), topic);
+      return { topic };
+    },
+    topic_unsubscribe: (input: HandlerInput): TopicSubscribeResult => {
+      const topic = topicOf(input);
+      answer(topics.unsubscribe(input.conn, topic), topic);
+      return { topic };
+    },
+  };
+}
+
+/** Safe to read: the op's schema accepted the frame before the handler ran. */
+function topicOf(input: HandlerInput): string {
+  return (input.args as unknown as TopicSubscribeArgs).topic;
+}
+
+function answer(outcome: SubscribeOutcome, topic: string): void {
+  if (outcome === "ok") return;
+  throw new OpError(outcome, refusal(outcome, topic));
+}
+
+function refusal(outcome: Exclude<SubscribeOutcome, "ok">, topic: string): string {
+  switch (outcome) {
+    case "topic_unknown":
+      return `no such topic: ${topic}`;
+    case "forbidden":
+      return `${topic} is not open to this connection`;
+    case "capability_unavailable":
+      return `${topic} needs a capability this instance does not have`;
+  }
+}

package/src/topics/index.ts

@@ -0,0 +1,2 @@
+export * from "./handlers.ts";
+export * from "./topics.ts";

package/src/topics/topics.ts

@@ -0,0 +1,290 @@
+import {
+  type Capability,
+  type InstanceId,
+  type Sid,
+  TOPIC_ATTRIBUTES,
+  type TopicAttributes,
+  type TopicKind,
+  topicGranularity,
+  topicKind,
+} from "@ccmsg/protocol";
+import type { Requester } from "../dispatch/index.ts";
+
+/** What a subscribe decided. `ok` and the three refusals the contract names
+ * for the op, so the caller turns an outcome into an error without deciding
+ * anything of its own. */
+export type SubscribeOutcome = "ok" | "topic_unknown" | "forbidden" | "capability_unavailable";
+
+/** One value on a topic, and the instance that produced it. */
+export interface TopicValue {
+  readonly instance: InstanceId;
+  readonly data: unknown;
+}
+
+/** Whoever owns the values behind a kind of topic, driven by whether anyone is
+ * listening.
+ *
+ * Subscription is the only thing that starts or stops it (daemon-v2 §6.3):
+ * `start` runs when a topic goes from no subscribers to one, `stop` when it
+ * goes back to none. Both are given the full topic name, because the resource
+ * is per name — one tail per `transcript:<sid>`, not one per kind.
+ *
+ * `snapshot` is asked for the current value, because the owner is where the
+ * current value lives (§3.3): the topic mechanism sees changes go past and a
+ * change is not a value. For a topic whose frames are elements or an append,
+ * the last change is one message or one chunk, while the current value is
+ * every message or the tail as it now stands — only the owner can say it.
+ * It answers one entry per originating instance, and none at all for a topic
+ * with no value to state.
+ *
+ * The subscribing connection is handed to `snapshot` because one topic's
+ * current value differs by who is asking: `inbox` names one topic for the
+ * instance, and what is on it for a session is what was said to that session
+ * (§4.3). Owners whose value is the same for everyone ignore the argument. */
+export interface UpstreamResource {
+  start(topic: string): void;
+  stop(topic: string): void;
+  snapshot(topic: string, conn: Requester): readonly TopicValue[];
+}
+
+/** The rest of the cluster, as the topic mechanism sees it (§7.4).
+ *
+ * Two things, both about topics that carry a whole value per instance: what
+ * the other instances have already stated, and whether anyone here is
+ * listening — because what a subscriber asks of this instance is what this
+ * instance asks of its peers. The mesh implements it; an instance without one
+ * has no other instance to hear from. */
+export interface RemoteTopics {
+  snapshot(topic: string): readonly TopicValue[];
+  demand(topic: string, wanted: boolean): void;
+}
+
+/** One instance's topics: subscribers, the way a value reaches them, and the
+ * suppression every topic shares.
+ *
+ * There is no class per topic. A topic is a name, a set of connections and the
+ * form of the last frame sent under it, so the whole of daemon-v2 §6.1 is this
+ * one object and "this topic has no suppression" cannot happen (M5). What it
+ * does not hold is the current value: that belongs to whoever owns it (§3.3),
+ * and is asked for when a subscriber needs it. */
+export class Topics {
+  /** Subscribers per topic name. A connection appears in as many sets as it
+   * has subscriptions, and leaves all of them when it closes (§6.3). */
+  readonly #subscribers = new Map<string, Set<Requester>>();
+  /** The form of the last frame sent, per topic name and then per originating
+   * instance — the only thing suppression needs, and the only thing kept.
+   * Per instance because a whole value from one instance does not replace
+   * another's (§6.2), so neither does it make the other a repeat. */
+  readonly #lastSent = new Map<string, Map<InstanceId, string>>();
+  readonly #upstream = new Map<TopicKind, UpstreamResource>();
+  /** The connections a close listener has already been registered on. Weak
+   * because the entry says nothing once the connection is gone. */
+  readonly #closers = new WeakSet<Requester>();
+
+  constructor(
+    private readonly self: InstanceId,
+    private readonly capabilities: ReadonlySet<Capability>,
+    private readonly remote?: RemoteTopics,
+  ) {}
+
+  /** Bind the resource that feeds a kind of topic. */
+  attach(kind: TopicKind, resource: UpstreamResource): void {
+    this.#upstream.set(kind, resource);
+  }
+
+  /** The one way a value reaches subscribers (§6.1).
+   *
+   * `instance` is where the value was produced: this instance for a value of
+   * our own, and the originating peer for one mesh relayed to us, which the
+   * frame carries onward unchanged (§7.4).
+   *
+   * `to` narrows the frame to the connections of one session. It exists for
+   * `inbox`, whose topic name is one for the instance while its value belongs
+   * to a session: without it, delivering to one session would push the message
+   * to every subscriber. It changes who receives the frame and nothing else —
+   * the frame, and the suppression before it, are the same ones every topic
+   * goes through (M5). */
+  publish(topic: string, data: unknown, instance: InstanceId = this.self, to?: Sid): void {
+    const kind = topicKind(topic);
+    if (kind === undefined) return;
+    if (replaces(topic)) {
+      // The suppression, written once for every topic it applies to (M5). The
+      // contract's granularity is the whole of the rule, and only a frame that
+      // replaces the value it repeats can be dropped for repeating it: a delta
+      // is an occurrence — an inbox message offered again, a `kv` entry
+      // restated — and dropping it would lose the offer, not a duplicate.
+      const wire = serialize(data);
+      const sent = this.#sent(topic);
+      if (sent.get(instance) === wire) return;
+      sent.set(instance, wire);
+    }
+    const frame = this.#frame(topic, instance, data, false);
+    for (const conn of this.#subscribers.get(topic) ?? []) {
+      if (holds(conn, to)) conn.send(frame);
+    }
+  }
+
+  subscribe(conn: Requester, topic: string): SubscribeOutcome {
+    const kind = topicKind(topic);
+    if (kind === undefined) return "topic_unknown";
+    // Read at the declared type rather than at the literal one the table
+    // infers, so the two checks below are the table's rule and not this
+    // topic's own row.
+    const attrs: TopicAttributes = TOPIC_ATTRIBUTES[kind];
+    const identity = conn.identity;
+    // Who may hear a topic is the same question the op table answers for ops,
+    // asked of the topic table (§11.2). A connection with no settled identity
+    // has no role to compare, and cannot reach the op that gets here anyway.
+    if (identity.state !== "settled" || !attrs.roles.includes(identity.role)) return "forbidden";
+    if (attrs.capability !== undefined && !this.capabilities.has(attrs.capability)) {
+      return "capability_unavailable";
+    }
+
+    let subscribers = this.#subscribers.get(topic);
+    if (subscribers === undefined) {
+      subscribers = new Set();
+      this.#subscribers.set(topic, subscribers);
+      // Before the connection joins, so a value the resource produces while
+      // starting is held rather than pushed as a change to a subscriber that
+      // has not had its snapshot yet.
+      this.#upstream.get(kind)?.start(topic);
+      // The subscription travels with the same trigger the local resource has:
+      // one listener starts it, none stops it (§6.3, §7.4).
+      this.remote?.demand(topic, true);
+    }
+    if (!subscribers.has(conn)) {
+      subscribers.add(conn);
+      // One listener for the connection rather than one per subscription: a
+      // client that subscribes and unsubscribes as it moves between views does
+      // so any number of times on one connection, and a listener registered
+      // per subscription would be kept for every one of them until it closed.
+      // What the single listener releases is every subscription still held,
+      // which is what a close means (§6.3).
+      if (!this.#closers.has(conn)) {
+        this.#closers.add(conn);
+        conn.onClose(() => this.dropAll(conn));
+      }
+    }
+    // The owner states the current value. A topic with no owner attached yet
+    // answers nothing, as does one with no value to state (§6.2, event), and
+    // in both cases the subscriber starts at the next thing that happens.
+    for (const value of this.#upstream.get(kind)?.snapshot(topic, conn) ?? []) {
+      conn.deferSend(this.#frame(topic, value.instance, value.data, true));
+    }
+    // What the other instances last stated, under their own names. A whole
+    // value per instance means the subscriber folds these beside ours instead
+    // of choosing between them (§6.2), and an instance that has gone is still
+    // among them until its value is given up (§7.5).
+    for (const value of this.remote?.snapshot(topic) ?? []) {
+      conn.deferSend(this.#frame(topic, value.instance, value.data, true));
+    }
+    return "ok";
+  }
+
+  /** Drop one subscription. Repeating it changes nothing, which is what lets
+   * the close listener and an explicit unsubscribe both end a subscription. */
+  unsubscribe(conn: Requester, topic: string): SubscribeOutcome {
+    const kind = topicKind(topic);
+    if (kind === undefined) return "topic_unknown";
+    const subscribers = this.#subscribers.get(topic);
+    if (subscribers === undefined || !subscribers.delete(conn)) return "ok";
+    if (subscribers.size > 0) return "ok";
+    this.#subscribers.delete(topic);
+    // Nothing is listening, so the resource stops. What it last sent is
+    // forgotten with it: comparing against a frame from before the resource
+    // stopped would suppress the first frame after it starts again.
+    this.#lastSent.delete(topic);
+    this.#upstream.get(kind)?.stop(topic);
+    this.remote?.demand(topic, false);
+    return "ok";
+  }
+
+  /** Drop every subscription one connection holds.
+   *
+   * What shutdown calls (§8.5 step 2) before it tells the connections
+   * anything: a resource runs while it has a listener (§6.3), so taking the
+   * listeners away is what stops the upstream watches — through the same
+   * `unsubscribe` a closing connection goes through, rather than a second way
+   * to release the same thing. */
+  dropAll(conn: Requester): void {
+    const held: string[] = [];
+    for (const [topic, subscribers] of this.#subscribers) {
+      if (subscribers.has(conn)) held.push(topic);
+    }
+    for (const topic of held) this.unsubscribe(conn, topic);
+  }
+
+  /** How many connections hold a subscription to a topic, counting only those
+   * of one session when `to` names one.
+   *
+   * What delivery asks before it publishes: a message reaches its session
+   * through this topic or it does not reach it at all, so whether anyone is
+   * listening for that session decides between handing it over and holding it
+   * (§4.2). */
+  subscriberCount(topic: string, to?: Sid): number {
+    let count = 0;
+    for (const conn of this.#subscribers.get(topic) ?? []) {
+      if (holds(conn, to)) count += 1;
+    }
+    return count;
+  }
+
+  #sent(topic: string): Map<InstanceId, string> {
+    const sent = this.#lastSent.get(topic) ?? new Map<InstanceId, string>();
+    this.#lastSent.set(topic, sent);
+    return sent;
+  }
+
+  /** The wire shape of a topic frame, built here and nowhere else so snapshot
+   * and change cannot drift apart (§11.1). */
+  #frame(topic: string, instance: InstanceId, data: unknown, snapshot: boolean): object {
+    return snapshot
+      ? { ev: "topic", topic, snapshot: true, instance, data }
+      : { ev: "topic", topic, instance, data };
+  }
+}
+
+/** What a scoped topic names: the sid of `session_status:<sid>`, the session
+ * of `transcript:<sid>`, the namespace of `kv:<ns>`. Which kind of topic it is
+ * has already been decided by whoever holds the name; this reads the parameter
+ * out of it, in one place for every owner that is per name (§6.3). */
+export function topicParam(topic: string): string | undefined {
+  const separator = topic.indexOf(":");
+  if (separator < 0) return undefined;
+  const param = topic.slice(separator + 1);
+  return param.length > 0 ? param : undefined;
+}
+
+/** Whether a connection is one of the session's, for a frame addressed to a
+ * session. A connection with no sid settled holds none, so a person watching
+ * the topic does not receive what was said to someone else. */
+function holds(conn: Requester, to: Sid | undefined): boolean {
+  if (to === undefined) return true;
+  const identity = conn.identity;
+  return identity.state === "settled" && identity.sid === to;
+}
+
+/** Whether a frame on this topic replaces the value it carries, which is the
+ * question suppression asks (§6.1).
+ *
+ * The two whole-value granularities do: a payload equal to the last one leaves
+ * the subscriber holding what it already holds. The others do not — an
+ * `element` frame adds or restates one entry, an `append` frame carries a
+ * chunk, an `event` frame is an occurrence — so two equal frames are two
+ * things happening, and the second is news. */
+function replaces(topic: string): boolean {
+  const granularity = topicGranularity(topic);
+  return granularity === "whole" || granularity === "per_instance_whole";
+}
+
+/** The comparison behind suppression, in one place for every topic (M5).
+ *
+ * A topic payload is the JSON the frame will carry, so its serialized form is
+ * exactly what a subscriber would receive: comparing that answers "would this
+ * frame tell the subscriber anything new" without walking the value, and it
+ * cannot disagree with what goes on the wire. It is sensitive to key order,
+ * which is not a defect here — the values come from a domain that builds each
+ * topic's payload in one place, so the same value serializes the same way. */
+function serialize(data: unknown): string {
+  return JSON.stringify(data ?? null);
+}

package/src/transcript/files.ts

@@ -0,0 +1,201 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { Sid } from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+
+/** Where the harness keeps transcripts under a config home: one directory per
+ * working directory, one `<sid>.jsonl` in it. */
+const PROJECTS = "projects";
+const SUFFIX = ".jsonl";
+
+/** A session id as the harness names files by. Validated before it is joined
+ * to a path, so a sid is a name rather than a route: no separator and no dot
+ * can appear in it, which makes traversal unrepresentable rather than
+ * unlikely. */
+const SID = /^[0-9a-fA-F-]{8,64}$/;
+
+/** The agent id and run id shapes the harness writes under a session's own
+ * directory, and the name a teammate is addressed by. Each is validated on the
+ * same footing as a sid, for the same reason: all three name a file. */
+const AGENT_ID = /^a[A-Za-z0-9_-]{5,120}$/;
+const RUN_ID = /^wf_[0-9a-f]{8}-[0-9a-f]{3}$/;
+const TEAMMATE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Which transcript an op means.
+ *
+ * The caller never supplies a path: a sid resolves to the file the session
+ * announced, or to the one under this instance's own config home, and the
+ * three optional names below resolve to files under that session's own
+ * directory. Only the config home this instance answers for is ever looked in
+ * (M6) — nothing searches for another one. */
+export interface TranscriptFilesDeps {
+  readonly configHome: string;
+  /** Where a connected session said its transcript is (§5.1). A session that
+   * never greeted has none, and the walk below answers for it. */
+  readonly announced: (sid: Sid) => string | undefined;
+}
+
+export class TranscriptFiles {
+  constructor(private readonly deps: TranscriptFilesDeps) {}
+
+  /** The session's own transcript. */
+  session(sid: Sid): string {
+    const announced = this.deps.announced(sid);
+    if (announced !== undefined && isFile(announced)) return announced;
+    const found = this.find(sid);
+    if (found === undefined) throw new OpError("not_found", `no transcript is held for ${sid}`);
+    return found;
+  }
+
+  /** The transcript an op's arguments name: the session's own, or one of the
+   * agents that ran below it.
+   *
+   * `agent_id` and `teammate` are two ways of naming the same kind of file and
+   * cannot be combined — a request carrying both names two files and is a
+   * caller's mistake rather than a choice this makes for them. */
+  locate(sid: Sid, names: AgentNames = {}): string {
+    const file = this.session(sid);
+    if (names.agent_id !== undefined && names.teammate !== undefined) {
+      throw new OpError("invalid_args", "agent_id and teammate name two different transcripts");
+    }
+    if (names.agent_id === undefined && names.teammate === undefined) {
+      if (names.run_id !== undefined) {
+        throw new OpError("invalid_args", "run_id names the run an agent_id belongs to");
+      }
+      return file;
+    }
+    const under = agentsDir(file, names.run_id);
+    if (names.agent_id !== undefined) {
+      return existing(join(under, `agent-${name(names.agent_id, AGENT_ID, "agent_id")}${SUFFIX}`));
+    }
+    return this.teammate(under, name(names.teammate ?? "", TEAMMATE, "teammate"));
+  }
+
+  /** A teammate's transcript, found by the name it is addressed by.
+   *
+   * The name a teammate carries in conversation is not its filename, so the
+   * directory's own records are read for it rather than the name being
+   * substituted into a path. */
+  private teammate(under: string, wanted: string): string {
+    let names: string[];
+    try {
+      names = readdirSync(under);
+    } catch {
+      throw new OpError("not_found", `no agent has run under this session`);
+    }
+    for (const each of names) {
+      if (!each.endsWith(".meta.json")) continue;
+      let document: unknown;
+      try {
+        document = JSON.parse(readFileSync(join(under, each), "utf8"));
+      } catch {
+        continue;
+      }
+      const named = (document as { name?: unknown } | null)?.name;
+      if (named !== wanted) continue;
+      return existing(join(under, `${each.slice(0, -".meta.json".length)}${SUFFIX}`));
+    }
+    throw new OpError("not_found", `no teammate of this session is addressed as ${wanted}`);
+  }
+
+  /** Every transcript under this instance's config home, newest first.
+   *
+   * The one enumeration a search and a fork sweep both start from. It states
+   * the file and what a `stat` already said about it, so neither has to stat
+   * again to decide whether to open it. */
+  all(): TranscriptFile[] {
+    const found: TranscriptFile[] = [];
+    const projects = join(this.deps.configHome, PROJECTS);
+    for (const project of names(projects)) {
+      const dir = join(projects, project);
+      for (const entry of names(dir)) {
+        if (!entry.endsWith(SUFFIX)) continue;
+        const sid = entry.slice(0, -SUFFIX.length);
+        if (!SID.test(sid)) continue;
+        const file = join(dir, entry);
+        const stat = statOf(file);
+        if (stat === undefined) continue;
+        found.push({
+          sid,
+          file,
+          project,
+          size: stat.size,
+          created_at: Math.round(stat.birthtimeMs || stat.ctimeMs),
+          updated_at: Math.round(stat.mtimeMs),
+        });
+      }
+    }
+    found.sort((a, b) => b.updated_at - a.updated_at || a.file.localeCompare(b.file));
+    return found;
+  }
+
+  private find(sid: Sid): string | undefined {
+    if (!SID.test(sid)) return undefined;
+    const projects = join(this.deps.configHome, PROJECTS);
+    for (const project of names(projects)) {
+      const file = join(projects, project, `${sid}${SUFFIX}`);
+      if (isFile(file)) return file;
+    }
+    return undefined;
+  }
+}
+
+export interface AgentNames {
+  readonly agent_id?: string;
+  readonly run_id?: string;
+  readonly teammate?: string;
+}
+
+/** One transcript on disk, with what the enumeration already learned of it. */
+export interface TranscriptFile {
+  readonly sid: Sid;
+  readonly file: string;
+  /** The project directory's name, which is the working directory flattened.
+   * A lossy spelling — separators and dots all become dashes — so it prefilters
+   * a search and never decides it. */
+  readonly project: string;
+  readonly size: number;
+  readonly created_at: number;
+  readonly updated_at: number;
+}
+
+/** Where the agents of one session write, beside its own transcript. */
+function agentsDir(sessionFile: string, runId?: string): string {
+  const dir = join(dirname(sessionFile), basename(sessionFile, SUFFIX), "subagents");
+  if (runId === undefined) return dir;
+  return join(dir, "workflows", name(runId, RUN_ID, "run_id"));
+}
+
+/** One path segment, checked against the shape its kind has. The check runs
+ * before the join, so a name that could leave the directory never becomes part
+ * of a path at all. */
+function name(value: string, shape: RegExp, field: string): string {
+  if (!shape.test(value)) throw new OpError("invalid_args", `${field} is not a name of that kind`);
+  return value;
+}
+
+function existing(file: string): string {
+  if (!isFile(file)) throw new OpError("not_found", "no transcript is held for that agent");
+  return file;
+}
+
+function names(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function statOf(file: string) {
+  try {
+    const stat = statSync(file);
+    return stat.isFile() ? stat : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isFile(file: string): boolean {
+  return statOf(file) !== undefined;
+}