@ccmsg/cli 0.12.0 → 0.14.0

package/src/sessions/fork.ts

@@ -1,7 +1,8 @@
-import { readFileSync, statSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { ForkOrigin, Sid } from "@ccmsg/protocol";
 import { readRecord, type TranscriptFiles } from "../transcript/index.ts";
+import { breathe, due } from "../transcript/scan.ts";
 
 /** How large a transcript may be and still be swept.
  *
@@ -36,18 +37,21 @@ const SWEEP_MAX_BYTES = 64 * 1024 * 1024;
  * Absent covers a session that is no fork, one whose ancestor file is gone,
  * and that undecidable pair. Nothing left on disk tells them apart, and none
  * of them has a seam to place. */
-export function forkOrigin(sid: Sid, files: TranscriptFiles): ForkOrigin | undefined {
+export async function forkOrigin(
+  sid: Sid,
+  files: TranscriptFiles,
+): Promise<ForkOrigin | undefined> {
   const file = files.session(sid);
-  const ours = recordIds(file);
+  const ours = await recordIds(file);
   const head = ours?.[0];
   if (ours === undefined || head === undefined) return undefined;
   const mine = new Set(ours);
 
   const dir = dirname(file);
   let best: { sid: Sid; copied: number } | undefined;
-  for (const candidate of files.all()) {
+  for (const candidate of await files.all()) {
     if (candidate.file === file || dirname(candidate.file) !== dir) continue;
-    const theirs = recordIds(candidate.file);
+    const theirs = await recordIds(candidate.file);
     if (theirs === undefined || theirs[0] !== head) continue;
     const copied = run(ours, new Set(theirs));
     const back = run(theirs, mine);
@@ -55,7 +59,7 @@ export function forkOrigin(sid: Sid, files: TranscriptFiles): ForkOrigin | undef
     // than their copy; an equal one says the records cannot tell, and creation
     // order is what is left.
     if (copied === 0 || back > copied) continue;
-    if (back === copied && !older(candidate.file, file)) continue;
+    if (back === copied && !(await older(candidate.file, file))) continue;
     // Sibling forks of one ancestor share a prefix too, so several files can
     // match; the longest run is the nearest ancestor and the true seam.
     if (best === undefined || copied > best.copied) best = { sid: candidate.sid, copied };
@@ -81,28 +85,31 @@ function run(ids: readonly string[], other: ReadonlySet<string>): number {
  * A creation time of zero is a filesystem that does not record one, which is
  * not an ancient file: two of those are simply not ordered, and the pair they
  * belong to gets no answer. */
-function older(candidate: string, file: string): boolean {
-  const theirs = bornAt(candidate);
-  const ours = bornAt(file);
+async function older(candidate: string, file: string): Promise<boolean> {
+  const theirs = await bornAt(candidate);
+  const ours = await bornAt(file);
   if (theirs === undefined || ours === undefined) return false;
   return theirs < ours;
 }
 
 /** Every record id in a file, in order. Undefined for a file too large to
  * sweep or one that could not be read. */
-function recordIds(file: string): string[] | undefined {
+async function recordIds(file: string): Promise<string[] | undefined> {
   let text: string;
   try {
-    if (statSync(file).size > SWEEP_MAX_BYTES) return undefined;
-    text = readFileSync(file, "utf8");
+    if ((await stat(file)).size > SWEEP_MAX_BYTES) return undefined;
+    text = await readFile(file, "utf8");
   } catch {
     return undefined;
   }
   const ids: string[] = [];
+  let read = 0;
   for (const line of text.split("\n")) {
     // Most of a transcript's bytes sit in a handful of very large records, and
     // parsing one to learn it carries no id is the cost this avoids.
     if (line === "" || !line.includes('"uuid"')) continue;
+    read += 1;
+    if (due(read)) await breathe();
     const uuid = readRecord(line)?.uuid;
     if (uuid !== undefined) ids.push(uuid);
   }
@@ -117,9 +124,9 @@ function recordIds(file: string): string[] | undefined {
  * millisecond the contract states instants in either — two transcripts written
  * moments apart share one, and the whole use of this value is telling which
  * came first. */
-function bornAt(file: string): number | undefined {
+async function bornAt(file: string): Promise<number | undefined> {
   try {
-    const born = statSync(file).birthtimeMs;
+    const born = (await stat(file)).birthtimeMs;
     return born > 0 ? born : undefined;
   } catch {
     return undefined;

package/src/sessions/handlers.ts

@@ -122,9 +122,11 @@ export function sessionHandlers(deps: SessionOpsDeps) {
      * cycle, happen where the config is read. */
     "dump.presets.read": (): DumpPresetsReadResult => ({ presets: [...deps.presets] }),
 
-    "session.fork.origin.read": (input: HandlerInput): SessionForkOriginReadResult => {
+    "session.fork.origin.read": async (
+      input: HandlerInput,
+    ): Promise<SessionForkOriginReadResult> => {
       const args = input.args as unknown as SessionForkOriginReadArgs;
-      const origin = forkOrigin(args.sid, deps.files);
+      const origin = await forkOrigin(args.sid, deps.files);
       return origin === undefined ? {} : { origin };
     },
 
@@ -135,7 +137,7 @@ export function sessionHandlers(deps: SessionOpsDeps) {
       return { removed: deps.forget(args.sid) };
     },
 
-    "transcript.read": (input: HandlerInput): TranscriptReadResult => {
+    "transcript.read": async (input: HandlerInput): Promise<TranscriptReadResult> => {
       const args = input.args as unknown as TranscriptReadArgs;
       if (!sees(args.sid, viewer(input))) {
         // The role sets the visible range, not the permission (DESIGN §2.2): outside
@@ -144,8 +146,8 @@ export function sessionHandlers(deps: SessionOpsDeps) {
         // the caller was not entitled to ask.
         throw new OpError("not_found", `no transcript is known for ${args.sid}`);
       }
-      const file = deps.files.locate(args.sid, args);
-      return readSlice(args.sid, file, args.before, args.max_bytes);
+      const file = await deps.files.locate(args.sid, args);
+      return await readSlice(args.sid, file, args.before, args.max_bytes);
     },
 
     /** The same transcript, as the items it was read into.
@@ -153,12 +155,12 @@ export function sessionHandlers(deps: SessionOpsDeps) {
      * The role narrows it the way it narrows the raw read: what a role may see
      * is one rule whatever is being read, and a caller that cannot see a
      * session cannot see it in either vocabulary. */
-    "transcript.items.read": (input: HandlerInput): TranscriptItemsReadResult => {
+    "transcript.items.read": async (input: HandlerInput): Promise<TranscriptItemsReadResult> => {
       const args = input.args as unknown as TranscriptItemsReadArgs;
       if (!sees(args.sid, viewer(input))) {
         throw new OpError("not_found", `no transcript is known for ${args.sid}`);
       }
-      return itemsRead(args, { files: deps.files, presets: deps.presets });
+      return await itemsRead(args, { files: deps.files, presets: deps.presets });
     },
   };
 }

package/src/sessions/items.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import type {
   DumpPreset,
   TranscriptItemsReadArgs,
@@ -8,15 +8,14 @@ import { OpError } from "../dispatch/index.ts";
 import type { TranscriptFiles } from "../transcript/index.ts";
 import {
   bounded,
-  classify,
   type Item,
   ledger,
-  located,
   select,
   selection,
   within,
 } from "../transcript/items/index.ts";
 import { READ_LIMIT } from "../transcript/read.ts";
+import { classified } from "../transcript/scan.ts";
 
 /** How many items one read may carry.
  *
@@ -52,23 +51,26 @@ export interface ItemsReadDeps {
  * is. That is what makes a link answerable: a result inside the range whose
  * call fell before it still names the call, and the caller can ask for the
  * call by the id it was given. */
-export function itemsRead(
+export async function itemsRead(
   args: TranscriptItemsReadArgs,
   deps: ItemsReadDeps,
-): TranscriptItemsReadResult {
+): Promise<TranscriptItemsReadResult> {
   bounded(args);
-  const file = deps.files.locate(
+  const file = await deps.files.locate(
     args.sid,
     args.agent_id === undefined ? {} : { agent_id: args.agent_id },
   );
   let text: string;
   try {
-    text = readFileSync(file, "utf8");
+    text = await readFile(file, "utf8");
   } catch {
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
   const keep = selection(args.types === undefined ? {} : { types: args.types }, deps.presets);
-  const { items } = select(within(classify(located(text), deps.files.subjectOf(file)), args), keep);
+  const { items } = select(
+    within(await classified(text, await deps.files.subjectOf(file)), args),
+    keep,
+  );
   const page = paged(items, args.limit, backwards(args));
   return {
     items: page.items,

package/src/sessions/last-live.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import {
   LAST_LIVE_RETENTION_MS,
@@ -53,6 +54,9 @@ const VERSION = 1;
 export class LastLiveStore {
   #entries = new Map<Sid, StoredEntry>();
 
+  /** The writes already asked for, as one chain. */
+  #written: Promise<void> = Promise.resolve();
+
   /** `id` is this instance's own: every entry this store holds is by
    * definition an observation *this* instance made, so `instance` is forced
    * to it on both ends (load and record) rather than trusted from whatever
@@ -114,6 +118,12 @@ export class LastLiveStore {
     return true;
   }
 
+  /** Settle once every write asked for so far has landed. What a stop waits on,
+   * and what a reader of the file has to wait for to see the last change. */
+  async flush(): Promise<void> {
+    await this.#written;
+  }
+
   #prune(now: Timestamp): boolean {
     let dropped = false;
     for (const [sid, entry] of this.#entries) {
@@ -125,13 +135,26 @@ export class LastLiveStore {
   }
 
   /** Written whole through a temporary file, so a daemon killed mid-write
-   * leaves the previous list rather than half of this one. */
+   * leaves the previous list rather than half of this one.
+   *
+   * A session appearing or going is an ordinary event of a running instance, so
+   * the write does not hold it still (DR-0015). The body is taken here, before
+   * anything is awaited, and each write is chained onto the one before it: what
+   * lands last is what the list said last, and two of them cannot be sharing
+   * one temporary file. */
   #save(): void {
     const document: Document = { version: VERSION, sessions: [...this.#entries.values()] };
     const temporary = `${this.file}.${process.pid}.tmp`;
-    mkdirSync(dirname(this.file), { recursive: true });
-    writeFileSync(temporary, `${JSON.stringify(document)}\n`);
-    renameSync(temporary, this.file);
+    this.#written = this.#written.then(async () => {
+      try {
+        await mkdir(dirname(this.file), { recursive: true });
+        await writeFile(temporary, `${JSON.stringify(document)}\n`);
+        await rename(temporary, this.file);
+      } catch {
+        // A list that could not be written costs the Paused and Disappeared
+        // rows of the next run, and nothing of this one.
+      }
+    });
   }
 }
 

package/src/sessions/registry.ts

@@ -1,4 +1,5 @@
-import { realpathSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import {
   type AgentInfo,
@@ -22,7 +23,7 @@ import {
 import { type HandlerInput, OpError, type Requester } from "../dispatch/index.ts";
 import { within } from "../files/index.ts";
 import { HARNESS, type Harness } from "../harness/index.ts";
-import { clusterView } from "../mesh/instances.ts";
+import { meshView } from "../mesh/instances.ts";
 import type { TranscriptFacts } from "../transcript/index.ts";
 import { Elements, type TopicValue, type UpstreamResource } from "../topics/index.ts";
 import { classify, type SessionInputs } from "./classify.ts";
@@ -243,6 +244,13 @@ export class Sessions implements UpstreamResource {
     this.#reclaim(this.#live);
   }
 
+  /** Settle the list of lost sessions on disk. The writes happen as sessions
+   * come and go (DR-0015); this is for whoever has to see the file as it stands
+   * rather than as it was a moment ago — a stop, or a reader of the file. */
+  async flush(): Promise<void> {
+    await this.#lastLive.flush();
+  }
+
   /** Drop the `last_live` entry of every session that is live, which is what
    * keeps one session off both lists.
    *
@@ -258,10 +266,10 @@ export class Sessions implements UpstreamResource {
    * can speak about, and where everything this instance knows about where that
    * session lives comes from. The greeting names its sid because the op it
    * arrived under is the one whose schema asks for one. */
-  helloSession = (input: HandlerInput): HelloResult => {
+  helloSession = async (input: HandlerInput): Promise<HelloResult> => {
     const args = input.args as unknown as HelloSessionArgs;
     this.#greetable(input, args.protocol_version);
-    this.register(args.sid, args);
+    await this.register(args.sid, args);
     input.conn.onClose(() => this.release(args.sid));
     return this.#greeted(input);
   };
@@ -315,8 +323,8 @@ export class Sessions implements UpstreamResource {
       instance: this.deps.self,
       ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
       // The same view the `instances` topic carries, worked out in one place
-      // so a greeting and a subscription cannot state two different clusters.
-      instances: clusterView(this.deps.self, this.deps.endpoint, this.deps.mesh),
+      // so a greeting and a subscription cannot state two different meshs.
+      instances: meshView(this.deps.self, this.deps.endpoint, this.deps.mesh),
       capabilities: [...this.deps.capabilities],
       version: this.deps.version,
       started_at: this.deps.startedAt,
@@ -609,15 +617,15 @@ export class Sessions implements UpstreamResource {
    * silence for a retraction would let each of them erase what the last one
    * knew, and the session would be described by whichever process spoke most
    * recently rather than by everything it has said. */
-  private register(sid: Sid, args: HelloSessionArgs): void {
-    const now = Date.now();
+  private async register(sid: Sid, args: HelloSessionArgs): Promise<void> {
+    const stated = await metaOf(this.deps, args, (refused) => {
+      this.deps.log?.("transcript_path not taken", { sid, path: args.transcript_path, refused });
+    });
+    // Read after the path has been settled, so that what this writes is built
+    // on the session as it stands now rather than as it stood before.
     const held = this.#connected.get(sid);
-    const meta = {
-      ...this.#stated.get(sid),
-      ...metaOf(this.deps, args, (refused) => {
-        this.deps.log?.("transcript_path not taken", { sid, path: args.transcript_path, refused });
-      }),
-    };
+    const now = Date.now();
+    const meta = { ...this.#stated.get(sid), ...stated };
     this.#connected.set(sid, {
       sid,
       connected_at: held?.connected_at ?? now,
@@ -841,17 +849,17 @@ export class Sessions implements UpstreamResource {
  * simply does not act on a description it cannot stand behind. Why a path was
  * not taken is told to `refused`, which is the operator's answer to a field
  * that is simply absent from what `peers` says. */
-function metaOf(
+async function metaOf(
   deps: Pick<SessionsDeps, "configHome" | "harness">,
   args: HelloSessionArgs,
   refused: (reason: string) => void,
-): SessionMeta {
+): Promise<SessionMeta> {
   const meta: Record<string, string> = {};
   for (const field of META_FIELDS) {
     const value = args[field];
     if (value === undefined) continue;
     if (field === "transcript_path") {
-      const taken = ownTranscript(value, deps);
+      const taken = await ownTranscript(value, deps);
       if (typeof taken === "string") meta[field] = taken;
       else refused(taken.refused);
       continue;
@@ -884,27 +892,36 @@ function metaOf(
  * comparison is between two paths resolved by one rule. The config home is not
  * treated that way — an instance answers for a home it is running out of, and
  * one that is not there names no tree to be inside of. */
-function ownTranscript(
+async function ownTranscript(
   named: string,
   deps: Pick<SessionsDeps, "configHome" | "harness">,
-): string | Refused {
+): Promise<string | Refused> {
   if (!isAbsolute(named)) return { refused: "not an absolute path" };
   let tree: string | undefined;
   try {
-    const home = realpathSync(deps.configHome);
-    tree = resolveAsFarAsItGoes(join(home, HARNESS[deps.harness].transcripts));
+    const home = await realpath(deps.configHome);
+    tree = await resolveAsFarAsItGoes(join(home, HARNESS[deps.harness].transcripts));
   } catch {
     return { refused: "the config home is not there" };
   }
-  const settled = resolveAsFarAsItGoes(named);
+  const settled = await resolveAsFarAsItGoes(named);
   if (tree === undefined || settled === undefined || !within(settled, tree)) {
     return { refused: "outside this config home's transcript tree" };
   }
-  const stat = statSync(settled, { throwIfNoEntry: false });
-  if (stat !== undefined && !stat.isFile()) return { refused: "not a file" };
+  const known = await stated(settled);
+  if (known !== undefined && !known.isFile()) return { refused: "not a file" };
   return settled;
 }
 
+/** What is at a path, or nothing where there is nothing at it. */
+async function stated(path: string): Promise<Stats | undefined> {
+  try {
+    return await stat(path);
+  } catch {
+    return undefined;
+  }
+}
+
 /** Why a stated path was not taken, in the words the log states it in. */
 interface Refused {
   readonly refused: string;
@@ -917,12 +934,12 @@ interface Refused {
  * kept as it was spelled. The result is compared against the tree as a whole,
  * which is what makes a `..` among the unwritten segments land wherever it
  * actually points rather than pass for being spelled inside. */
-function resolveAsFarAsItGoes(path: string): string | undefined {
+async function resolveAsFarAsItGoes(path: string): Promise<string | undefined> {
   const unwritten: string[] = [];
   let at = path;
   for (;;) {
     try {
-      return join(realpathSync(at), ...unwritten);
+      return join(await realpath(at), ...unwritten);
     } catch {
       const parent = dirname(at);
       // The root itself always resolves, so this is a path that named

package/src/sessions/search.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { parse, sep } from "node:path";
 import type {
   InstanceId,
@@ -9,6 +9,7 @@ import type {
 } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
 import { readRecord, type TranscriptFile, type TranscriptFiles } from "../transcript/index.ts";
+import { breathe, due } from "../transcript/scan.ts";
 
 /** What one search may read, and what it may answer with.
  *
@@ -57,7 +58,10 @@ export interface SearchDeps {
  * directory listing and a `stat` already say — the session id, the working
  * directory as the project directory spells it, when the file was last touched
  * — and only what survives that is read. */
-export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearchResult {
+export async function search(
+  args: SessionSearchArgs,
+  deps: SearchDeps,
+): Promise<SessionSearchResult> {
   if ((args.config_dirs ?? [deps.configHome]).every((dir) => dir !== deps.configHome)) {
     // Every config home the caller named is one this instance does not know,
     // which the contract says to ignore — leaving nothing to search.
@@ -72,7 +76,7 @@ export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearch
   const hits: SessionSearchHit[] = [];
   let budget = SCAN_BUDGET_BYTES;
   let truncated = false;
-  for (const candidate of deps.files.all()) {
+  for (const candidate of await deps.files.all()) {
     if (sid !== undefined && !candidate.sid.toLowerCase().includes(sid)) continue;
     if (candidate.updated_at < since) continue;
     if (!looksLike(candidate.project, cwdWords)) continue;
@@ -84,7 +88,7 @@ export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearch
       break;
     }
     budget -= candidate.size;
-    const hit = read(candidate, clauses, wanted, deps);
+    const hit = await read(candidate, clauses, wanted, deps);
     // The working directory the project directory only approximates: a hit is
     // kept when the transcript's own `cwd` holds every word asked for.
     if (hit !== undefined && holds(hit.cwd, cwdWords)) hits.push(hit);
@@ -169,15 +173,15 @@ function compile(args: SessionSearchArgs): { clauses: Clause[]; budgets: Budget[
  * The pass is one: the records that carry the query also carry the working
  * directory, the title and what the session last ran as, so a hit is built
  * from the reading that decided it rather than from a second one. */
-function read(
+async function read(
   candidate: TranscriptFile,
   clauses: readonly Clause[],
   wanted: { user: boolean; agent: boolean },
   deps: SearchDeps,
-): SessionSearchHit | undefined {
+): Promise<SessionSearchHit | undefined> {
   let text: string;
   try {
-    text = readFileSync(candidate.file, "utf8");
+    text = await readFile(candidate.file, "utf8");
   } catch {
     // Gone since it was listed, which is a session that ended mid-search.
     return undefined;
@@ -188,8 +192,13 @@ function read(
   let model: string | undefined;
   let effort: string | undefined;
   let createdAt: number | undefined;
+  let read = 0;
   for (const line of text.split("\n")) {
     if (line === "") continue;
+    read += 1;
+    // The file arrived in one `await` and reading it is CPU from here on, so
+    // the pass hands the loop back as it goes rather than at the file's end.
+    if (due(read)) await breathe();
     const record = readRecord(line);
     if (record === undefined) continue;
     cwd ??= record.cwd;

package/src/sessions/status.ts

@@ -5,7 +5,7 @@ import type {
   SessionStatusSnapshot,
   Sid,
 } from "@ccmsg/protocol";
-import { canonical, within } from "../files/containment.ts";
+import { canonicalSync, within } from "../files/containment.ts";
 import type { TopicValue, UpstreamResource } from "../topics/index.ts";
 import { topicParam } from "../topics/index.ts";
 import type { TranscriptFacts } from "../transcript/index.ts";
@@ -43,7 +43,7 @@ export function sessionStatusOf(
   sid: Sid;
 } {
   const stopped = stoppedOn(facts);
-  const root = where.root === undefined ? undefined : canonical(where.root);
+  const root = where.root === undefined ? undefined : canonicalSync(where.root);
   return {
     sid,
     todos: [...facts.todos],
@@ -54,7 +54,7 @@ export function sessionStatusOf(
     external_files:
       root === undefined
         ? []
-        : facts.named_files.filter((file) => !within(canonical(file.path), root)),
+        : facts.named_files.filter((file) => !within(canonicalSync(file.path), root)),
     workspace_folders: workspaceFolders(where.cwd),
     ...(stopped === undefined ? {} : { api_error: stopped }),
   };

package/src/topics/egress.ts

@@ -6,9 +6,9 @@ import type { Requester } from "../dispatch/index.ts";
  * list cannot see a change arrive sooner than the display draws it, so frames
  * closer together than a few display frames are spent on nothing, while a wait
  * long enough to be read as lag starts around a quarter of a second. Towards
- * the cluster: a relayed frame waits once per hop, so the delay a subscriber
+ * the mesh: a relayed frame waits once per hop, so the delay a subscriber
  * sees is this value times the hops between it and the instance that produced
- * the value — at 100 ms a two-hop cluster still answers inside the window a
+ * the value — at 100 ms a two-hop mesh still answers inside the window a
  * person reads as immediate, which a longer period would leave.
  *
  * It is not a poll. Nothing is looked at when the period elapses: the timer is