@adecore/agents 0.21.1 → 0.22.0

package/src/chat/external-sessions.ts

@@ -0,0 +1,177 @@
+import { join } from 'node:path';
+import { clipText } from '@adecore/agent-contracts';
+import { isForkOrSubagent } from '../usage/readers/codex.ts';
+import { claudeProjectSlug, spokenText } from './claude-transcript.ts';
+
+/* What the listing may do to the file system; a fake in tests, `node:fs` in a host. */
+export interface SessionFs {
+    /* The names in a folder; empty when it is not there. */
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{ mtimeMs: number } | null>;
+    /* The first `maxBytes` of a file as text; the last line may be cut short. */
+    readHead(path: string, maxBytes: number): Promise<string>;
+}
+
+/* A conversation a CLI keeps on disk, started outside the app that lists it. */
+export interface ExternalSession {
+    provider: 'claude' | 'codex';
+    sessionId: string;
+    /* The first thing the person said, on one line. */
+    title: string;
+    updatedAt: number;
+    cwd: string;
+}
+
+const TITLE_LENGTH = 120;
+// Claude writes hook output and attachments ahead of the first prompt, and Codex its instructions.
+const HEAD_BYTES = 256 * 1024;
+const CLAUDE_MAX_FILES = 200;
+
+function titleOf(text: string): string {
+    return clipText(text.replace(/\s+/g, ' ').trim(), TITLE_LENGTH);
+}
+
+function records(head: string): Array<Record<string, unknown>> {
+    const lines = head.split('\n');
+    // The head ends wherever the byte limit fell, so its last line may not parse.
+    return lines.flatMap((line) => {
+        if (line === '') {
+            return [];
+        }
+        try {
+            const parsed: unknown = JSON.parse(line);
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? [parsed as Record<string, unknown>] : [];
+        } catch {
+            return [];
+        }
+    });
+}
+
+const CLAUDE_BOOKKEEPING = new Set(['summary', 'file-history-snapshot', 'queue-operation']);
+
+/* A reminder or the wrapper of a slash command is written as a user line too, but nobody said it. */
+function claudePrompt(entry: Record<string, unknown>): string | null {
+    if (CLAUDE_BOOKKEEPING.has(String(entry.type)) || entry.type !== 'user' || entry.isSidechain === true || entry.isMeta === true) {
+        return null;
+    }
+    const message = typeof entry.message === 'object' && entry.message !== null ? (entry.message as Record<string, unknown>) : {};
+    const said = spokenText(message.content);
+    if (said === null || said.trim() === '' || said.startsWith('<command-') || said.startsWith('<local-command-')) {
+        return null;
+    }
+    return said;
+}
+
+/*
+ * The conversations Claude Code kept for a folder, newest first. Only the folder's own directory is
+ * read, and only the `.jsonl` files in it, so the transcripts of subagents in `<session>/subagents` stay out.
+ * A file without a prompt somebody said is no conversation.
+ */
+export async function listClaudeSessions({ projectsDir, folder, fs }: { projectsDir: string; folder: string; fs: SessionFs }): Promise<ExternalSession[]> {
+    const dir = join(projectsDir, claudeProjectSlug(folder));
+    const names = (await fs.readdir(dir)).filter((name) => name.endsWith('.jsonl'));
+    const stats = await Promise.all(names.map(async (name) => ({ name, stat: await fs.stat(join(dir, name)) })));
+    const newest = stats
+        .flatMap(({ name, stat }) => (stat === null ? [] : [{ name, mtimeMs: stat.mtimeMs }]))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, CLAUDE_MAX_FILES);
+    const sessions: ExternalSession[] = [];
+    for (const { name, mtimeMs } of newest) {
+        const prompt = records(await fs.readHead(join(dir, name), HEAD_BYTES))
+            .map(claudePrompt)
+            .find((said) => said !== null);
+        if (prompt !== undefined && prompt !== null) {
+            sessions.push({ provider: 'claude', sessionId: name.slice(0, -'.jsonl'.length), title: titleOf(prompt), updatedAt: mtimeMs, cwd: folder });
+        }
+    }
+    return sessions;
+}
+
+function codexPrompt(entry: Record<string, unknown>): string | null {
+    const payload = typeof entry.payload === 'object' && entry.payload !== null ? (entry.payload as Record<string, unknown>) : null;
+    if (payload === null) {
+        return null;
+    }
+    if (entry.type === 'event_msg' && payload.type === 'user_message' && typeof payload.message === 'string') {
+        return payload.message.trim() === '' ? null : payload.message;
+    }
+    return null;
+}
+
+/* The newest names first; the folders are named by year, month and day, and the files by when they began. */
+function newestFirst(names: string[]): string[] {
+    return [...names].sort().reverse();
+}
+
+async function rolloutFiles(sessionsDir: string, fs: SessionFs, max: number): Promise<string[]> {
+    const files: string[] = [];
+    for (const year of newestFirst(await fs.readdir(sessionsDir))) {
+        for (const month of newestFirst(await fs.readdir(join(sessionsDir, year)))) {
+            for (const day of newestFirst(await fs.readdir(join(sessionsDir, year, month)))) {
+                const names = newestFirst(
+                    (await fs.readdir(join(sessionsDir, year, month, day))).filter((name) => name.startsWith('rollout-') && name.endsWith('.jsonl'))
+                );
+                for (const name of names) {
+                    files.push(join(sessionsDir, year, month, day, name));
+                    if (files.length >= max) {
+                        return files;
+                    }
+                }
+            }
+        }
+    }
+    return files;
+}
+
+/*
+ * The conversations Codex kept for a folder, newest first, out of the newest `maxFiles` rollouts. A
+ * rollout counts when its first line, the session's metadata, names this folder and is no fork or subagent.
+ */
+export async function listCodexSessions({
+    sessionsDir,
+    folder,
+    fs,
+    maxFiles = 400
+}: {
+    sessionsDir: string;
+    folder: string;
+    fs: SessionFs;
+    maxFiles?: number;
+}): Promise<ExternalSession[]> {
+    const sessions: ExternalSession[] = [];
+    for (const path of await rolloutFiles(sessionsDir, fs, maxFiles)) {
+        const entries = records(await fs.readHead(path, HEAD_BYTES));
+        const meta = entries[0];
+        const payload =
+            meta?.type === 'session_meta' && typeof meta.payload === 'object' && meta.payload !== null ? (meta.payload as Record<string, unknown>) : null;
+        if (payload === null || payload.cwd !== folder || typeof payload.id !== 'string' || isForkOrSubagent(payload)) {
+            continue;
+        }
+        const prompt = entries.map(codexPrompt).find((said) => said !== null);
+        if (prompt === undefined || prompt === null) {
+            continue;
+        }
+        const stat = await fs.stat(path);
+        sessions.push({ provider: 'codex', sessionId: payload.id, title: titleOf(prompt), updatedAt: stat?.mtimeMs ?? 0, cwd: folder });
+    }
+    return sessions;
+}
+
+/* A `node:fs` behind the seam, for a host that lists the real thing. */
+export async function nodeSessionFs(): Promise<SessionFs> {
+    const { readdir, stat, open } = await import('node:fs/promises');
+    return {
+        readdir: async (path) => readdir(path).catch(() => []),
+        stat: async (path) => stat(path).catch(() => null),
+        readHead: async (path, maxBytes) => {
+            const handle = await open(path, 'r');
+            try {
+                const buffer = Buffer.alloc(maxBytes);
+                const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+                return buffer.subarray(0, bytesRead).toString('utf8');
+            } finally {
+                await handle.close();
+            }
+        }
+    };
+}

package/src/chat/fake-claude.ts

@@ -146,6 +146,40 @@ export function fakeClaude(io: FakeIo): FakeProgram {
     // What a background agent asked; its answer comes in after the turn that launched it, whenever a person gives one.
     let backgroundAsk: { requestId: string; command: string } | null = null;
     let slow = false;
+    // The two foreground subagents of `two subagents` that have not settled; the turn stays open until both have.
+    const openTwo = new Set<string>();
+
+    const settleTwo = (name: 'a-one' | 'a-two', stopped: boolean): void => {
+        const toolUseId = name === 'a-one' ? 'toolu_two_a' : 'toolu_two_b';
+        if (!openTwo.delete(name)) {
+            return;
+        }
+        if (stopped) {
+            out({ type: 'system', subtype: 'task_updated', task_id: name, patch: { status: 'killed', end_time: 0 }, session_id: sessionId });
+            out({
+                type: 'system',
+                subtype: 'task_notification',
+                task_id: name,
+                tool_use_id: toolUseId,
+                status: 'stopped',
+                output_file: '',
+                summary: 'Stopped',
+                session_id: sessionId
+            });
+        }
+        out({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: [{ type: 'tool_result', tool_use_id: toolUseId, content: stopped ? 'Stopped' : `${name} done`, is_error: stopped }]
+            },
+            session_id: sessionId
+        });
+        if (openTwo.size === 0) {
+            assistantText('summarized B');
+            result();
+        }
+    };
 
     // The rest of a background agent once its request was answered: its call's result, its report, and the turn the CLI opens about it.
     const finishBackgroundAgent = (command: string, allowed: boolean, message: string | undefined): void => {
@@ -193,6 +227,43 @@ export function fakeClaude(io: FakeIo): FakeProgram {
             io.exit(1);
             return;
         }
+        // Two foreground subagents beside each other; the turn ends once both settled: a-two when the test runs what is put off, a-one by a `stop_task`.
+        if (text === 'two subagents') {
+            openTwo.add('a-one').add('a-two');
+            for (const [name, toolUseId] of [
+                ['a-one', 'toolu_two_a'],
+                ['a-two', 'toolu_two_b']
+            ] as const) {
+                out({
+                    type: 'assistant',
+                    message: {
+                        id: `msg_${nonce}_${++messageCounter}`,
+                        model,
+                        role: 'assistant',
+                        content: [
+                            { type: 'tool_use', id: toolUseId, name: 'Agent', input: { description: name, subagent_type: 'general-purpose', prompt: name } }
+                        ],
+                        usage
+                    },
+                    session_id: sessionId
+                });
+                out({
+                    type: 'system',
+                    subtype: 'task_started',
+                    task_id: name,
+                    tool_use_id: toolUseId,
+                    description: name,
+                    subagent_type: 'general-purpose',
+                    is_backgrounded: false,
+                    spawn_depth: 1,
+                    task_type: 'local_agent',
+                    prompt: name,
+                    session_id: sessionId
+                });
+            }
+            io.later(() => settleTwo('a-two', false));
+            return;
+        }
         if (text === 'crash loudly') {
             io.err(`${'warming up\n'.repeat(2000)}Error: the fake lost its key\n    at handleUser (fake-claude.ts)\n`);
             io.exit(1);
@@ -952,8 +1023,11 @@ export function fakeClaude(io: FakeIo): FakeProgram {
             } else if (frame.type === 'control_response') {
                 handleControlResponse(frame.response as Record<string, unknown>);
             } else if (frame.type === 'control_request') {
-                const request = frame.request as { subtype: string };
+                const request = frame.request as { subtype: string; task_id?: string };
                 out({ type: 'control_response', response: { subtype: 'success', request_id: frame.request_id, response: {} } });
+                if (request.subtype === 'stop_task' && (request.task_id === 'a-one' || request.task_id === 'a-two')) {
+                    settleTwo(request.task_id, true);
+                }
                 if (request.subtype === 'interrupt' && slow) {
                     slow = false;
                     assistantText('[interrupted]');

package/src/chat/limit-resume.ts

@@ -5,13 +5,8 @@ export const LIMIT_RETRY_DELAYS_MS: readonly number[] = [60_000, 5 * 60_000, 15
 
 /* The last turn of a thread, when it stopped on a limit. */
 export function limitedTurn(items: readonly ChatItem[]): (ChatTurnItem & { limit: ChatTurnLimit }) | null {
-    for (let i = items.length - 1; i >= 0; i--) {
-        const item = items[i]!;
-        if (item.kind === 'turn') {
-            return item.state === 'error' && item.limit !== undefined ? (item as ChatTurnItem & { limit: ChatTurnLimit }) : null;
-        }
-    }
-    return null;
+    const last = items.findLast((item) => item.kind === 'turn');
+    return last?.kind === 'turn' && last.state === 'error' && last.limit !== undefined ? (last as ChatTurnItem & { limit: ChatTurnLimit }) : null;
 }
 
 /* How many turns in a row, up to and including this one, stopped on a limit: the tries a person did not step in between. */

package/src/chat/thread-search.ts

@@ -0,0 +1,87 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+
+/* One message of a thread that holds the query, cut to a line around the match. */
+export interface ThreadHit {
+    itemId: string;
+    author: 'person' | 'agent';
+    snippet: string;
+    /* Where the match sits in `snippet`, in UTF-16 units. */
+    matchStart: number;
+    matchLength: number;
+    createdAt: number;
+    turnId: string | null;
+}
+
+export interface ThreadSearchOptions {
+    limit: number;
+}
+
+// Characters kept on each side of the match.
+const CONTEXT = 60;
+
+// Emphasis and code markers carry no meaning in a one-line snippet, where they only read as noise.
+function plain(text: string): string {
+    return text.replace(/\*{1,3}|_{2,}|`+/g, '').replace(/\s+/g, ' ');
+}
+
+// Moves a cut forward to the start of the next word, never past `limit`, so a snippet does not open on half a word.
+function wordStart(text: string, from: number, limit: number): number {
+    if (from === 0 || /\s/.test(text[from - 1]!) || /\s/.test(text[from]!)) {
+        return from;
+    }
+    const space = text.slice(from, limit).search(/\s/);
+    return space === -1 ? from : from + space + 1;
+}
+
+// Moves a cut back to the end of the previous word, never before `limit`.
+function wordEnd(text: string, to: number, limit: number): number {
+    if (to === text.length || /\s/.test(text[to - 1]!) || /\s/.test(text[to]!)) {
+        return to;
+    }
+    const space = text.slice(limit, to).search(/\s\S*$/);
+    return space === -1 ? to : limit + space;
+}
+
+function snippetOf(text: string, index: number, length: number): { snippet: string; matchStart: number; matchLength: number } {
+    const from = wordStart(text, Math.max(0, index - CONTEXT), index);
+    const to = wordEnd(text, Math.min(text.length, index + length + CONTEXT), index + length);
+    const before = `${from > 0 ? '…' : ''}${plain(text.slice(from, index))}`;
+    const match = plain(text.slice(index, index + length));
+    const after = `${plain(text.slice(index + length, to))}${to < text.length ? '…' : ''}`;
+    return { snippet: `${before}${match}${after}`, matchStart: before.length, matchLength: match.length };
+}
+
+/*
+ * The messages of a thread that hold `query`, oldest first, one hit per message. Only what a person
+ * and the agent said counts: what a subagent said (`parentToolUseId`) is not part of the conversation.
+ */
+export function searchThreadItems(items: readonly ChatItem[], query: string, { limit }: ThreadSearchOptions): ThreadHit[] {
+    if (query === '' || limit <= 0) {
+        return [];
+    }
+    const pattern = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+    const hits: ThreadHit[] = [];
+    for (const item of items) {
+        if (item.kind !== 'user' && item.kind !== 'assistant') {
+            continue;
+        }
+        if (item.kind === 'assistant' && item.parentToolUseId) {
+            continue;
+        }
+        const found = pattern.exec(item.text);
+        if (found === null) {
+            continue;
+        }
+        hits.push({
+            itemId: item.id,
+            author: item.kind === 'user' ? 'person' : 'agent',
+            ...snippetOf(item.text, found.index, found[0].length),
+            createdAt: item.createdAt,
+            turnId: item.turnId
+        });
+        if (hits.length >= limit) {
+            break;
+        }
+    }
+    return hits;
+}

package/src/chat/thread.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 import { ChatError } from './errors.ts';
 import { requestSummaries } from './request-summary.ts';
-import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 
 /*
  * The state of one chat as the client sees it. Every mutation answers the event that describes

package/src/chat/visual-store.ts

@@ -113,6 +113,13 @@ function tooLarge(bytes: number): never {
     );
 }
 
+function refuseOversized(html: string): void {
+    const bytes = Buffer.byteLength(html, 'utf8');
+    if (bytes > VISUAL_LIMITS.bytes) {
+        tooLarge(bytes);
+    }
+}
+
 /*
  * The visuals of every chat. The list of a chat is one file beside its record under `<home>/chats`;
  * each page is a file in the chat's attachment folder, `<id>.html`, so whatever serves an attachment
@@ -164,9 +171,7 @@ export class VisualStore {
         if (html.trim() === '') {
             refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
         }
-        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
-            tooLarge(Buffer.byteLength(html, 'utf8'));
-        }
+        refuseOversized(html);
         return this.writeWorkspaceFile(chatId, name, html);
     }
 
@@ -178,9 +183,7 @@ export class VisualStore {
     async publish(chatId: string, input: VisualInput): Promise<ChatVisual> {
         const { title, html, maxHeight, layout, heights } = checked(input);
         // Before the bootstrap is added, so a page far too large is never copied first.
-        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
-            tooLarge(Buffer.byteLength(html, 'utf8'));
-        }
+        refuseOversized(html);
         const page = Buffer.from(injectVisualBootstrap(html), 'utf8');
         if (page.byteLength > VISUAL_LIMITS.bytes) {
             tooLarge(page.byteLength);

package/src/chat/wake-chat.ts

@@ -2,7 +2,10 @@ import type { ChatItem } from '@adecore/agent-contracts';
 import type { ChatCore } from './chat-core.ts';
 import type { ChatSession } from './chat-session.ts';
 
-/* A chat the host may open a turn in, as the outbox handlers see it: what its thread holds, and the one call that opens one, false while a turn or an owed resume is in the way. */
+/*
+ * A chat the host may open a turn in, as the outbox handlers see it. `wake` answers false while a
+ * turn or an owed resume is in the way.
+ */
 export interface WakeChat {
     items(): ChatItem[];
     persist?(): Promise<void>;

package/src/context/refusal.ts

@@ -1,8 +1,7 @@
 /*
  * How every no reads: `refused`, the code a script branches on and the sentence a model reads, and
- * under it a line per thing the actor can do instead. One row per line, and a line is a row of
- * tab-separated fields of its own, so only a newline is taken out of it: that would split the row in
- * two, and everything under the first row is read as advice.
+ * under it a line per thing the actor can do instead. A line keeps its tabs but loses its newlines,
+ * since everything under the first row is read as advice.
  */
 
 /* A field that goes into a tab-separated line; a tab or a newline in a title would split the row. */
@@ -24,10 +23,7 @@ export function refusalBody(code: string, message: string, lines: readonly strin
     return [`refused\t${first}`, ...rest].join('\n');
 }
 
-/*
- * The same without the word that names it, for a host that adds the prefix in its CLI:
- * The context CLI puts the prefix on, so a CLI of an older build still prints one refusal.
- */
+/* Without the `refused` prefix, for a host whose CLI adds it, so a CLI of an older build still prints one refusal. */
 export function refusalRows(code: string, message: string, lines: readonly string[] = []): string {
     return rows(code, message, lines).join('\n');
 }

package/src/context/verb.ts

@@ -382,11 +382,7 @@ export function requiredField(needs: string): z.ZodString {
     return z.string({ error: needs }).min(1, needs);
 }
 
-/*
- * What a refusal lists, or one line saying the set is empty. A refusal that promises the groups of a
- * canvas and then prints nothing reads as a daemon that lost them, where the truth is that there are
- * none, which is a different thing to do something about.
- */
+/* A refusal that promises a list and prints nothing reads as a host that lost it, where there is none. */
 export function orNote(lines: string[], note: string): string[] {
     return lines.length === 0 ? [`note\t${note}`] : lines;
 }

package/src/host/agent-host.ts

@@ -24,8 +24,8 @@ function isAgentRequest(type: string): type is AgentRequestType {
 
 /*
  * The chats of an app that has no daemon: it answers the agent requests over any `FramePort` and
- * sends the agent events back on it, frames checked on arrival. One port is one client. Closing the host writes every thread and ends every CLI; a chat
- * goes on at the next start through its CLI's own session.
+ * sends the agent events back on it, frames checked on arrival. One port is one client. A chat
+ * closed with the host goes on at the next start through its CLI's own session.
  */
 export class AgentHost<Core extends ChatCore = ChatCore> {
     readonly chats: Core;

package/src/host/handlers.ts

@@ -63,7 +63,7 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
             chats.send(
                 payload.chatId,
                 payload.text,
-                { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats },
+                { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats, quoteSource: payload.quoteSource },
                 payload.attachments
             ),
         'chat.uiChoice': (payload, clientId) => chats.choose(payload, clientId),
@@ -116,7 +116,6 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
     };
 }
 
-/* The accounts are the person's settings of this host. */
 export function accountHandlers(accounts: ProviderAccountsService): { [T in AccountRequestType]: AgentHandler<T> } {
     return {
         'accounts.list': () => accounts.snapshot(),

package/src/host/wiring.ts

@@ -9,12 +9,12 @@ import { VisualStore } from '../chat/visual-store.ts';
 import type { ClaudeBackendOptions } from '../chat/claude-backend.ts';
 import { ClaudeTitleReader } from '../chat/claude-title.ts';
 import { DEFAULT_CODEX_CLIENT, type CodexClientInfo } from '../chat/codex-transport.ts';
+import { errorText } from '../error-text.ts';
 import type { AgentEvent } from '../events.ts';
 import { definedEnv } from '../providers/accounts/launch.ts';
 import { ProviderAccountsService } from '../providers/accounts/service.ts';
 import type { AccountsHost } from '../providers/accounts/variables.ts';
 import { createClaudeProvider } from '../providers/claude-provider.ts';
-import { errorText } from '../error-text.ts';
 import { createCodexProvider } from '../providers/codex-provider.ts';
 import { codexRulesPathIn, defaultCodexHome, installCodexRules, type CodexRules } from '../providers/codex-rules.ts';
 import { ProviderRegistry, type ProviderRegistryOptions } from '../providers/registry.ts';

package/src/lineage.ts

@@ -30,8 +30,8 @@ function openedByAgent(entry: Lineage): boolean {
 }
 
 /*
- * Lineage lives in `lineage` under the host's data folder, outside the agent-writable project, so agents
- * cannot reset their own depth. Persisting it also prevents a restart of the host from resetting recursion limits.
+ * Lives under the host's data folder, outside the agent-writable project, so an agent cannot reset its
+ * own depth; on disk, so a restart of the host does not reset it either.
  */
 export class AgentLineageStore {
     readonly dir: string;
@@ -140,7 +140,6 @@ export class AgentLineageStore {
         return entry?.relation === 'fork' ? entry.openedBy : null;
     }
 
-    /* The forks made from a chat. */
     forksOf(nodeId: string): string[] {
         return [...this.opened.all()].filter((entry) => entry.relation === 'fork' && entry.openedBy === nodeId).map((entry) => entry.nodeId);
     }

package/src/messages/deliver-message.ts

@@ -24,13 +24,11 @@ export interface DeliverMessageDeps {
 }
 
 /*
- * Opens the turn a message earns a chat. The messages themselves are not carried here: they wait in
- * the notice store and the turn's preamble takes them (`NoticeNotes`), the same channel a person's
- * own prompt reads them through, so one message is heard once whichever of the two opens the turn.
+ * Opens the turn a message earns a chat. The messages wait in the notice store and the turn's preamble
+ * takes them (`NoticeNotes`), as a person's own prompt does, so a message is heard once either way.
  *
- * One attempt, never `wait`. A chat that turned out to be in a turn reads the message in front of its
- * next one, which is what a message to a busy chat has always done; holding the entry instead would
- * make the host start turns nobody asked for long after the news was worth anything.
+ * One attempt, never `wait`: a chat already in a turn reads the message in front of its next one, and
+ * holding the entry would start turns nobody asked for long after the news mattered.
  */
 export function deliverMessageHandler(deps: DeliverMessageDeps) {
     return async (entry: DeliverMessageEntry): Promise<OutboxOutcome> => {
@@ -46,11 +44,8 @@ export function deliverMessageHandler(deps: DeliverMessageDeps) {
         if (chat === null) {
             return;
         }
-        /*
-         * No note of its own, and the preamble stays off the thread. A person read the message as it
-         * landed (`showNotices`), so anything the turn adds about it only says the same thing again;
-         * the label on the turn already names who it came from.
-         */
+        // No note and no preamble on the thread: a person read the message as it landed (`showNotices`),
+        // and the label on the turn names who it came from.
         chat.wake({
             text: deps.words.prompt(waiting.length),
             label: deps.words.label(waiting),

package/src/messages/deliver-notice.ts

@@ -33,11 +33,10 @@ export interface ChatDelivery {
 }
 
 /*
- * Whether the turn a chat is running was itself opened by a message. This is the whole of the stop:
- * two agents that read each other would otherwise wake each other for as long as they kept writing,
- * and nothing about that started with a person. It rides on the turn, so it survives a restart.
+ * Whether the turn a chat is running was itself opened by a message, which stops two agents that
+ * read each other from waking each other forever. It rides on the turn, so it survives a restart.
  * Between turns the last one counts, since work it left running (a background subagent) may still
- * write, and a turn the CLI opened by itself goes on with the step of the turn before it.
+ * write, and a turn the CLI opened by itself takes the step of the turn before it.
  */
 export function turnFromMessage(items: readonly ChatItem[], activeTurnId: string | null): boolean {
     const from = activeTurnId === null ? items.findLastIndex((item) => item.kind === 'turn') : items.findIndex((item) => item.id === activeTurnId);
@@ -76,10 +75,9 @@ export function chatNoticeTargets(chats: Pick<ChatCore, 'get' | 'hasStored'>): C
 
 /*
  * One message on its way to a chat, and whether the chat owes a turn on it. A chat between turns gets
- * one, the way a settled task gives one: a person watching two agents cannot tell a message from an
- * assignment, and a message nobody starts a turn for sits there until someone happens to prompt that
- * chat. One step deep, so the turn a message opened wakes nobody with a message of its own. A node the
- * host runs something else in, such as a terminal, is the host's to deliver to before this.
+ * one, as for a settled task, or the message sits there until someone happens to prompt that chat.
+ * One step deep: the turn a message opened wakes nobody with a message of its own. A node that runs
+ * something else, such as a terminal, is the host's to deliver to before this.
  */
 export async function deliverToChat(store: Pick<NoticeStore, 'put'>, targets: ChatNoticeTargets, notice: Omit<Notice, 'createdAt'>): Promise<ChatDelivery> {
     const waiting = await store.put(notice);
@@ -105,10 +103,8 @@ export interface NoticeChat {
 }
 
 /*
- * What a chat has to show a person, in its thread, the moment a message lands and not when the model
- * gets round to it: without this a message left for a busy node is a file on disk and nothing else.
- * An id no chat holds shows nothing and marks nothing, so the chat that opens on that id later still
- * has all of it.
+ * Shows a person the message in the chat's thread the moment it lands, not when the model gets round
+ * to it. An id no chat holds shows and marks nothing, so a chat that opens on it later still has all of it.
  */
 export async function showNotices(store: Pick<NoticeStore, 'show'>, chat: NoticeChat, words: Pick<MessageWords, 'shown'>, targetId: string): Promise<void> {
     if (!(await chat.has(targetId))) {

package/src/messages/notice-store.ts

@@ -7,10 +7,8 @@ import { RecordDirectory } from '../record-directory.ts';
 export const MAX_NOTICES = 10;
 
 /*
- * A message nobody picked up in this long is dropped rather than delivered. It is news about work
- * happening now ("the build is green"), and a model reading it six hours late would act on
- * something that has moved on. The cap alone would not do it: one message in a queue of one waits
- * for ever.
+ * A message is news about work happening now ("the build is green"), and a model reading it six hours
+ * late would act on something that moved on. The cap alone would leave a queue of one waiting forever.
  */
 export const NOTICE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
 
@@ -131,7 +129,7 @@ export class NoticeStore {
         return this.now() - notice.createdAt < NOTICE_MAX_AGE_MS;
     }
 
-    /* The queue of one node, emptied here and on disk both; an empty one leaves no file behind. */
+    /* In memory and on disk both; an empty queue leaves no file behind. */
     private async persist(targetId: string, queue: Notice[]): Promise<void> {
         if (queue.length === 0) {
             await this.queues.remove(targetId);