@ccmsg/cli 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/files/containment.ts

@@ -1,4 +1,3 @@
-import { realpathSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import type { FileKind, Role, Sid } from "@ccmsg/protocol";
@@ -28,7 +27,7 @@ export interface SessionRoots {
 
 /** Who states a session's allowlists. */
 export interface RootsSource {
-  roots(sid: Sid): SessionRoots | undefined;
+  roots(sid: Sid): Promise<SessionRoots | undefined>;
 }
 
 /** One path, decided.
@@ -71,7 +70,7 @@ export class Containment {
 
   /** A path named by kind, as an op's arguments give it. */
   async locate(args: PathArgs, viewer: Viewer = {}): Promise<Located> {
-    const roots = this.rootsFor(args.sid, viewer);
+    const roots = await this.rootsFor(args.sid, viewer);
     const named = await this.absolute(args, roots);
     const real = await canonical(named);
     return { ...(await this.admit(args.kind, real, roots)), named };
@@ -85,7 +84,7 @@ export class Containment {
   async identify(sid: Sid, path: string, viewer: Viewer = {}): Promise<Located | undefined> {
     let roots: SessionRoots;
     try {
-      roots = this.rootsFor(sid, viewer);
+      roots = await this.rootsFor(sid, viewer);
     } catch {
       return undefined;
     }
@@ -108,7 +107,7 @@ export class Containment {
    * rather than as forbidden — the path is reachable, and only writing there
    * is not. */
   async inbox(sid: Sid, path: string, viewer: Viewer = {}): Promise<Located> {
-    const roots = this.rootsFor(sid, viewer);
+    const roots = await this.rootsFor(sid, viewer);
     const cwd = roots.cwd;
     if (cwd === undefined || !isAbsolute(cwd)) {
       throw new OpError("path_forbidden", `${sid} states no working directory to write into`);
@@ -128,14 +127,14 @@ export class Containment {
     return this.locate({ sid: args.sid, kind: args.kind, path: args.path ?? "" }, viewer);
   }
 
-  private rootsFor(sid: Sid, viewer: Viewer): SessionRoots {
+  private async rootsFor(sid: Sid, viewer: Viewer): Promise<SessionRoots> {
     if (!sees(sid, viewer)) {
       throw new OpError(
         "path_forbidden",
         `the files of ${sid} are outside this connection's range`,
       );
     }
-    const roots = this.source.roots(sid);
+    const roots = await this.source.roots(sid);
     if (roots === undefined) {
       throw new OpError("path_forbidden", `nothing is known about the files of ${sid}`);
     }
@@ -256,22 +255,6 @@ export async function canonical(path: string): Promise<string> {
   }
 }
 
-/** The synchronous form required while `session.status` states its value synchronously (DESIGN §6); an asynchronous topic value uses `canonical` as the single path. */
-export function canonicalSync(path: string): string {
-  const absolute = resolve(path);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    const parent = dirname(absolute);
-    if (parent === absolute) return absolute;
-    try {
-      return join(realpathSync(parent), basename(absolute));
-    } catch {
-      return absolute;
-    }
-  }
-}
-
 /** Whether a resolved path is the root or below it. Shared with the launcher,
  * whose roots come from config rather than from a session: what "inside" means
  * is the same question, and two spellings of it could come apart. */

package/src/instance/instance.ts

@@ -51,7 +51,7 @@ import {
   SessionStatus,
 } from "../sessions/index.ts";
 import { topicHandlers, Topics } from "../topics/index.ts";
-import { TranscriptFiles, Transcripts } from "../transcript/index.ts";
+import { FoldCache, TranscriptFiles, Transcripts } from "../transcript/index.ts";
 import {
   type AuthorizedUpgrade,
   ConnRegistry,
@@ -502,6 +502,9 @@ export class Instance {
     this.#transcripts = new Transcripts({
       self: this.self,
       pathOf: (sid) => transcriptFiles.path(sid),
+      // What a past reading of each transcript reached, so a transcript is
+      // read from its beginning once rather than once per start.
+      cache: new FoldCache(join(paths.cacheDir, "transcripts")),
       publish: (topic, data) => {
         this.#topics.publish(topic, data);
       },
@@ -536,7 +539,7 @@ export class Instance {
       },
       ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }),
       onChanged: () => {
-        this.#status.refresh();
+        void this.#status.refresh();
         // A session that is live again is one route (a) can be tried against,
         // which is what the inbox is waiting for (DESIGN §6.7).
         void this.#delivery.retry();
@@ -559,12 +562,15 @@ export class Instance {
       release: (sid) => {
         this.#transcripts.release(sid);
       },
+      ready: (sid) => this.#transcripts.ready(sid),
       publish: (topic, data) => {
         this.#topics.publish(topic, data);
       },
     });
 
-    const inbox = new Inbox(inboxPath(paths.stateDir));
+    const inbox = new Inbox(inboxPath(paths.stateDir), (msg, fields) => {
+      this.log.write(msg, fields);
+    });
     inbox.load();
     this.#persisted.push(inbox);
     // Route (a) is the harness's own way in (DESIGN §6.5): Claude Code's messaging
@@ -662,10 +668,11 @@ export class Instance {
     // greeting says where the session works, and the fold says which folders
     // its editor names and which files outside them its transcript named.
     const files = new Containment({
-      roots: (sid): SessionRoots | undefined => {
+      roots: async (sid): Promise<SessionRoots | undefined> => {
         const where = this.#sessions.where(sid);
         if (where.root === undefined && where.cwd === undefined) return undefined;
-        const status = sessionStatusOf(sid, this.#transcripts.facts(sid), where);
+        await this.#transcripts.ready(sid);
+        const status = await sessionStatusOf(sid, this.#transcripts.facts(sid), where);
         return {
           ...where,
           workspace_folders: status.workspace_folders.map((folder) => folder.path),

package/src/instance/paths.ts

@@ -41,6 +41,11 @@ export interface InstancePaths {
   /** Where a file is put before it is overwritten by the checked copy. */
   readonly rejectedDir: string;
   readonly stateDir: string;
+  /** Where what was derived from a file is kept so it need not be derived
+   * again. Everything here can be rebuilt from the file it came from, so the
+   * directory may be emptied at any moment and the only cost is the work of
+   * deriving it once more. */
+  readonly cacheDir: string;
   /** The address clients connect to. A symlink to whichever `socketReal` is
    * currently serving, so a client's path outlives the process behind it. */
   readonly socket: string;
@@ -148,6 +153,7 @@ export function resolvePathsFor(configHome: string, env: Env = process.env): Ins
     satisfiedFile: join(stateRoot, STATE_CONFIG_DIR, SATISFIED_FILE),
     rejectedDir: join(stateRoot, REJECTED_DIR),
     stateDir,
+    cacheDir: appDir(env, "CCMSG_CACHE_DIR", "XDG_CACHE_HOME", [".cache"], key),
     socketDir,
     socket: join(socketDir, SOCKET_NAME),
     socketReal: join(socketDir, realSocketName(process.pid)),

package/src/messaging/inbox.ts

@@ -4,10 +4,12 @@ import { dirname, join } from "node:path";
 import {
   INBOX_MAX_PER_SID,
   INBOX_RETENTION_MS,
-  type InboxMessage,
+  InboxMessage,
   type InboxRemovedReason,
-  type Sid,
+  isValid,
+  Sid,
   type Timestamp,
+  validationErrors,
 } from "@ccmsg/protocol";
 
 export const INBOX_FILE = "inbox.jsonl";
@@ -50,7 +52,12 @@ export class Inbox {
    * subscribed for them to be news to. */
   #onRemoved?: (mid: string, reason: InboxRemovedReason) => void;
 
-  constructor(private readonly file: string) {}
+  constructor(
+    private readonly file: string,
+    /** Where a line the replay could not keep is named. Absent in the tests
+     * that are about the holding rather than about what is said of it. */
+    private readonly log: (message: string, fields: Record<string, unknown>) => void = () => {},
+  ) {}
 
   /** Hear about messages leaving. */
   onRemoved(told: (mid: string, reason: InboxRemovedReason) => void): void {
@@ -79,6 +86,7 @@ export class Inbox {
         // The last line of a file the daemon was killed while writing.
         continue;
       }
+      if (record.v === "add" && !this.#stateable(record.sid, record.message)) continue;
       this.#replay(record);
     }
     this.#expire(now);
@@ -168,6 +176,30 @@ export class Inbox {
     return highest;
   }
 
+  /** Whether a line read back is a message the contract can state.
+   *
+   * The file outlives the contract that wrote it, and what is held is answered
+   * to a person as rows of the `inbox` topic — so a single line the contract
+   * has since outgrown, replayed as if it were current, is a frame the reader
+   * refuses and a whole view lost for it. An instance states only what the
+   * contract can say, about its own file as much as about anything else.
+   *
+   * Dropped rather than mended: the message is the sender's words and the
+   * contract is what says how they are spelled, so there is nothing here that
+   * could write a spelling the contract would accept without inventing it. It
+   * leaves through the compaction that follows the replay, which writes back
+   * only what is held; nothing is appended and no removal is stated, since a
+   * replay has nobody subscribed to hear one and no `mid` the contract would
+   * take to name it by. */
+  #stateable(sid: unknown, message: unknown): boolean {
+    const why = isValid(Sid, sid)
+      ? validationErrors(InboxMessage, message)
+      : [`sid: ${JSON.stringify(sid)} is no session id`];
+    if (why.length === 0) return true;
+    this.log("dropped an inbox record the contract cannot state", { sid, why });
+    return false;
+  }
+
   #replay(record: Record_): void {
     if (record.v === "add") {
       const held = this.#held.get(record.sid) ?? [];

package/src/sessions/fork.ts

@@ -41,7 +41,7 @@ export async function forkOrigin(
   sid: Sid,
   files: TranscriptFiles,
 ): Promise<ForkOrigin | undefined> {
-  const file = files.session(sid);
+  const file = await files.session(sid);
   const ours = await recordIds(file);
   const head = ours?.[0];
   if (ours === undefined || head === undefined) return undefined;

package/src/sessions/harness.ts

@@ -171,8 +171,9 @@ export class HarnessSessions implements OwnSessions {
    * here too: a pid from a poll that has not run is a number belonging to
    * nobody.
    *
-   * Read in place because the directory is a handful of small files of this
-   * uid's own config home (M6) — a syscall or two per session, not a wait. */
+   * Read in place because the answer may not depend on anybody waiting: what
+   * this states is that a session exists, and a reading that could be waited
+   * for would make it something the callers above cannot ask (DESIGN §4.2). */
   scan(): ReadonlyMap<Sid, AgentInfo> {
     const rows = new Map<Sid, AgentInfo>();
     const names = this.#watch.names().filter((name) => STATE_FILE.test(name));
@@ -248,9 +249,8 @@ class DirectoryWatch {
     this.#timer = undefined;
   }
 
-  /** What is in the directory now. Read in place because it is a handful of
-   * small entries of this uid's own config home (M6) — a syscall or two, not a
-   * wait. */
+  /** What is in the directory now, read in place for the reason `scan()` is:
+   * it is the same answer, and the callers above it cannot wait for one. */
   names(): string[] {
     try {
       return readdirSync(this.dir);

package/src/sessions/status.ts

@@ -5,7 +5,7 @@ import type {
   SessionStatusSnapshot,
   Sid,
 } from "@ccmsg/protocol";
-import { canonicalSync, within } from "../files/containment.ts";
+import { canonical, 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";
@@ -35,15 +35,26 @@ export function stoppedOn(facts: TranscriptFacts): SessionApiError | undefined {
  * root is known. A session that stated no root contributes none of them rather
  * than all of them: the list is the allowlist an `external` read is checked
  * against, so not knowing where the session works has to admit nothing. */
-export function sessionStatusOf(
+export async function sessionStatusOf(
   sid: Sid,
   facts: TranscriptFacts,
   where: SessionWhere = {},
-): SessionStatusSnapshot & {
-  sid: Sid;
-} {
+): Promise<
+  SessionStatusSnapshot & {
+    sid: Sid;
+  }
+> {
   const stopped = stoppedOn(facts);
-  const root = where.root === undefined ? undefined : canonicalSync(where.root);
+  const root = where.root === undefined ? undefined : await canonical(where.root);
+  const named =
+    root === undefined
+      ? []
+      : await Promise.all(
+          facts.named_files.map(async (file) => ({
+            file,
+            real: await canonical(file.path),
+          })),
+        );
   return {
     sid,
     todos: [...facts.todos],
@@ -54,8 +65,8 @@ export function sessionStatusOf(
     external_files:
       root === undefined
         ? []
-        : facts.named_files.filter((file) => !within(canonicalSync(file.path), root)),
-    workspace_folders: workspaceFolders(where.cwd),
+        : named.filter((each) => !within(each.real, root)).map((each) => each.file),
+    workspace_folders: await workspaceFolders(where.cwd),
     ...(stopped === undefined ? {} : { api_error: stopped }),
   };
 }
@@ -81,6 +92,10 @@ export interface SessionStatusDeps {
   /** The tail behind a session's fold, asked for and let go by name. */
   readonly hold: (sid: Sid) => void;
   readonly release: (sid: Sid) => void;
+  /** When the fold of a held session has read the whole transcript. What this
+   * owner states rests on the fold, so it waits on this before stating it
+   * (CT-Q8). */
+  readonly ready: (sid: Sid) => Promise<void>;
   /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
 }
@@ -105,6 +120,15 @@ export class SessionStatus implements UpstreamResource {
    * convergence happens once rather than in the middle of itself. */
   #converging = false;
   #pending = false;
+  /** Which pass is the one entitled to state a value.
+   *
+   * Stating one waits on a reading, and two readings started in either order
+   * can finish in either order — so the later pass read the later facts, and
+   * the earlier one must not publish behind it. Every pass takes a number and
+   * gives up the moment a later one has taken a higher one: what a subscriber
+   * is told is what the most recent reading said, and never what an older one
+   * caught up to saying (DR-0015 §2.5). */
+  #stating = 0;
 
   constructor(private readonly deps: SessionStatusDeps) {}
 
@@ -112,16 +136,16 @@ export class SessionStatus implements UpstreamResource {
 
   start(topic: string): void {
     this.#wanted.add(topic);
-    this.refresh();
+    void this.refresh();
   }
 
   stop(topic: string): void {
     this.#wanted.delete(topic);
-    this.refresh();
+    void this.refresh();
   }
 
-  snapshot(topic: string): readonly TopicValue[] {
-    const data = this.value(topic);
+  async snapshot(topic: string): Promise<readonly TopicValue[]> {
+    const data = await this.value(topic);
     return data === undefined ? [] : [{ instance: this.deps.self, data }];
   }
 
@@ -129,7 +153,7 @@ export class SessionStatus implements UpstreamResource {
    * says, and which sessions exist, are the two things that move either.
    *
    * Called by whoever changes one of them, rather than on a timer (M3). */
-  refresh(): void {
+  async refresh(): Promise<void> {
     if (this.#converging) {
       this.#pending = true;
       return;
@@ -143,8 +167,15 @@ export class SessionStatus implements UpstreamResource {
     } finally {
       this.#converging = false;
     }
-    for (const topic of this.#wanted) {
-      const data = this.value(topic);
+    // The topics as they stand now: stating one waits on a reading, and a
+    // subscription arriving during that wait must not be iterated into.
+    const stating = [...this.#wanted];
+    this.#stating += 1;
+    const mine = this.#stating;
+    for (const topic of stating) {
+      const data = await this.value(topic);
+      // A later pass has read later facts; this one has nothing to add.
+      if (mine !== this.#stating) return;
       if (data !== undefined) this.deps.publish(topic, data);
     }
   }
@@ -169,12 +200,17 @@ export class SessionStatus implements UpstreamResource {
 
   /** What a topic of this owner currently says, for a snapshot and for a
    * change alike — built here and nowhere else, so the two cannot drift. */
-  private value(topic: string): unknown {
-    if (topic === "session.errors") return this.errors();
+  private async value(topic: string): Promise<unknown> {
+    if (topic === "session.errors") {
+      // Every session's fold, so the list is of the transcripts as they read
+      // rather than of the ones that happen to have been read by now.
+      await Promise.all(this.deps.sessions().map((sid) => this.deps.ready(sid)));
+      return this.errors();
+    }
     const sid = topicParam(topic);
-    return sid === undefined
-      ? undefined
-      : sessionStatusOf(sid, this.deps.facts(sid), this.deps.where(sid));
+    if (sid === undefined) return undefined;
+    await this.deps.ready(sid);
+    return await sessionStatusOf(sid, this.deps.facts(sid), this.deps.where(sid));
   }
 
   /** Bring the held tails in line with what the subscriptions need. */

package/src/sessions/workspace.ts

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 import type { WorkspaceFolder } from "@ccmsg/protocol";
@@ -14,15 +14,15 @@ import type { WorkspaceFolder } from "@ccmsg/protocol";
  *
  * 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[] {
+export async function workspaceFolders(cwd: string | undefined): Promise<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)) {
+  for (const file of await workspaceFiles(cwd)) {
+    for (const spec of await 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;
+      const real = await directory(resolve(dirname(file), spec.path));
+      if (real === undefined || (await overbroad(real)) || seen.has(real)) continue;
       seen.add(real);
       folders.push({ name: spec.name ?? basename(real), path: real });
     }
@@ -32,10 +32,10 @@ export function workspaceFolders(cwd: string | undefined): WorkspaceFolder[] {
 
 /** 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[] {
+async function workspaceFiles(cwd: string): Promise<string[]> {
   let entries: string[];
   try {
-    entries = readdirSync(cwd);
+    entries = await readdir(cwd);
   } catch {
     return [];
   }
@@ -47,10 +47,10 @@ function workspaceFiles(cwd: string): string[] {
 
 /** 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 }[] {
+async function specs(file: string): Promise<{ path: string; name?: string }[]> {
   let parsed: unknown;
   try {
-    parsed = JSON.parse(uncommented(readFileSync(file, "utf8")));
+    parsed = JSON.parse(uncommented(await readFile(file, "utf8")));
   } catch {
     // Written by hand and half-saved, or not a workspace file after all.
     return [];
@@ -113,10 +113,10 @@ function uncommented(text: string): string {
 
 /** 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 {
+async function directory(path: string): Promise<string | undefined> {
   try {
-    const real = realpathSync(path);
-    return statSync(real).isDirectory() ? real : undefined;
+    const real = await realpath(path);
+    return (await stat(real)).isDirectory() ? real : undefined;
   } catch {
     return undefined;
   }
@@ -127,9 +127,9 @@ function directory(path: string): string | undefined {
  * 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 {
+async function overbroad(real: string): Promise<boolean> {
   if (real === sep || dirname(real) === real) return true;
-  const home = directory(homedir());
+  const home = await directory(homedir());
   return home !== undefined && (real === home || home.startsWith(withSep(real)));
 }
 

package/src/topics/handlers.ts

@@ -7,9 +7,9 @@ import type { SubscribeOutcome, Topics } from "./topics.ts";
  * it to `Topics`, and turns the outcome into the contract's own answer. */
 export function topicHandlers(topics: Topics) {
   return {
-    "topic.subscribe": (input: HandlerInput): TopicSubscribeResult => {
+    "topic.subscribe": async (input: HandlerInput): Promise<TopicSubscribeResult> => {
       const topic = topicOf(input);
-      answer(topics.subscribe(input.conn, topic), topic);
+      answer(await topics.subscribe(input.conn, topic), topic);
       return { topic };
     },
     "topic.unsubscribe": (input: HandlerInput): TopicSubscribeResult => {