pi-optchat 0.8.1 → 0.8.2

package/README.md

@@ -100,6 +100,8 @@ Ask in plain words, for example: "Spawn an agent to investigate this repository
 - Children also get the Pi built-in extensions the main session loaded: MCP, codemode and tool search. Your MCP servers (`~/.pi/agent/mcp.json`, the project's `.pi/mcp.json`) work in subagents, with the sign-ins you made in Pi. If MCP is off in the main session (`--no-mcp`, `-builtin:mcp` in settings, or an extension that replaces `/mcp`), it is off in subagents too. Each subagent opens its own server connections (stdio servers start once per subagent) and closes them when it ends.
 - Each child reports to its parent as soon as it finishes, as one message starting `[id]`. A stopped or failed child reports its stop or error text. Turn **Group subagent reports** on to have the children of one spawn report together: when the last of them finishes, their reports reach the parent as one message, `[id] report` each, in spawn order. Each finished report is journaled right away, so if Pi dies before the rest finish, the reports it already has are delivered at the next start. Messages sent with `tell_parent`, connected windows and their handoffs are never held back, and a child resumed with `tell` reports on its own. The parent stays alive to receive reports; it never polls.
 - In the main chat, subagent messages and reports appear in a dark grey box labelled `↳ subagent <id> · still running` or `· report`, so they don't look like something you typed. The model still receives them as ordinary user messages; memory logs them as kind `work` (older logs hold them as `user` messages starting `[id]`). (One exception: reports recovered at startup, before your first message in the session, still show as plain user messages.)
+- Every report ends with `Full chat: zoom("<id>")`, so the agent can check it against what the child actually did: `zoom` with a run ID returns that child's chat so far as `kind|text` lines (its task without the memory view, replies, tool calls, tool results cut to their first and last ~500 characters, and what it was told), in 25,000-character pages that say which `offset` to go on from. It works on running children too; a subagent can read only its own descendants' chats, as with `tell`. The report box leaves the trailer out.
+- While any subagent runs, each new input to the main agent (your message, a report, a `tell_parent` message, the restart note, a connected window's message) ends with one status line, `[OptChat status] Agents at work now: 8f28e694 "Review PR #123 carefully", …` (id and the first words of each task), so it knows what is still out without asking. It is rebuilt each time and never stored. It isn't repeated on the calls after a tool result within one turn, and nothing is sent while no agent runs. The main prompt says what the label means, so the model doesn't take it for the user. It comes after the cached view and turn, with the turn's cache mark on the block before it, so it costs no cache.
 - The parent can send a running child guidance with `tell`, and the child can message its parent mid-run with `tell_parent` (a question, an early finding). It reaches the parent like a report, marked "still running": between tool calls if the parent is busy, or waking it if it's waiting.
 - `tell` to a finished child resumes it: the same agent (ID, parent, model, directory) reopens its saved transcript, gets the message as a new prompt, and sends a new report. This also works for children from earlier Pi sessions. Only the agent that started the child can resume it, and the resumed child takes one active slot. Connected windows can't be resumed, and a child whose transcript is missing must be spawned fresh.
 - By default only the main agent starts subagents. Set **Subagent levels** in `/optchat settings` to let them delegate further (3 means child, grandchild, great-grandchild).
@@ -121,7 +123,7 @@ An **Agents | Usage | Activity** bar sits below the input.
 
 Set a different shortcut with `OPTCHAT_INSPECT_KEY=ctrl+shift+a pi`. If another extension supplies a custom editor, OptChat leaves its Down key alone; use the shortcut or commands instead.
 
-**Agents** lists runs as a tree with state, elapsed time, current tool, and last activity. Navigate with **Up/Down**, **Page Up/Down**, **Home/End**, and press **M** to pick the subagent model. Press **D** twice to delete the selected agent and the agents it started, with their transcripts. An agent that is still working is stopped first, and its stop report reaches its parent before it is deleted. The report tells the parent that you dropped the task, so it does not delegate it again. The main agent can no longer resume a deleted agent. Deleting a connected window that is still open stops it like closing the window; its handoff still reaches the main agent, but the transcript the handoff points to is deleted.
+**Agents** lists runs as a tree with state, elapsed time, current tool, and last activity. Navigate with **Up/Down**, **Page Up/Down**, **Home/End**, and press **M** to pick the subagent model. Press **D** twice to delete the selected agent and the agents it started, with their transcripts. An agent that is still working is stopped first, and its stop report reaches its parent before it is deleted. The report tells the parent that you dropped the task, so it does not delegate it again. Deleting a finished agent sends no report, so memory logs `[id] deleted by the user` right away, without a model turn. The main agent can no longer resume a deleted agent. Deleting a connected window that is still open stops it like closing the window; its handoff still reaches the main agent, but the transcript the handoff points to is deleted.
 
 **Enter** swaps the screen to that agent's conversation, drawn with Pi's own chat components, so it reads like the main chat: its task, replies, and collapsed tool calls, following live output. Typing and **Enter** send it guidance. Guidance from the main agent and reports from the agent's own agents show in labelled boxes, so only your own messages look typed. **Escape** goes back to the main chat.
 
@@ -211,6 +213,8 @@ Each profile folder is a local Git repository, committed after each turn and on
 
 To delete a profile, delete its folder. Your original Pi sessions are kept in Pi's normal session directory.
 
+Memory reaches disk through one seam, `Store` in `src/store.ts`: the log, summary nodes, saved view and images, which is what would travel between machines. Runs, recovery journals, imports and their pointer, usage, settings and `AGENTS.md` stay local files. `FileStore` (the layout above) is the only store today; another, such as Postgres, would implement the same few operations, and its lease (take, heartbeat, release) is optional: without one, OptChat keeps its machine-local profile lock. Import records (`imports/*.json`, the staging generations and the `active-memory.json` pointer) are per machine, so a second machine with the same `~/.claude` or Codex history on disk may offer those sessions for import again.
+
 ## Windows
 
 The same install and commands work on Windows, and the offline tests run there too. What differs:
@@ -234,7 +238,7 @@ The same install and commands work on Windows, and the offline tests run there t
 
 ## How it differs from the recipe
 
-`src/prompts.ts` holds every prompt sent to a model (the recipe's four, the subagent instruction paragraphs, the compaction task and its retry, the handoff prompt, the import note), each with a comment on where it goes; tool descriptions stay with their tools. The recipe's prompts are lightly adapted. The main agent's turn rules are the revised recipe's (2026-10-08) word for word, without its paragraph on computers, with reports starting "[id] " instead of "[Name]", and with one added sentence: don't poll anything slow (CI, a deploy) yourself, hand the watching to a subagent; the view doc keeps the original's description of the view, drops its "No message appears in full" line (untrue with Previous exchange on) and its list of when to zoom, adds one sentence on zooming out from a message to the summaries above it, and ends with the revised recipe's rule that the view is the truth and zoom the only way through it; the compactor prompt is the revised recipe's intro, view and Compactions sections, with OptChat's kinds (`talk` for replies, subagent reports as `work`) and without its turn-only sections, and with its value list reworded so the size limit is a ceiling rather than a target (bare approvals are recorded as the decision they made, lines don't narrate what wasn't seen yet, and a tool result is described by what its output shows rather than by a cause guessed from an exit code or an empty match; an A/B found less filler and no recall loss, see #129); unlike the recipe, the compactor doesn't get your instructions, since an A/B found they added nothing (#112); and the subagent prompt is the original's plus a closing note on time: report progress on long tasks with tell_parent, and say so before waiting on something slow, so the main agent can go on. OptChat keeps the recipe's numbers: 512-byte summary nodes (by default summaries up to 640 bytes are accepted without a retry, as long as they are smaller than what they replace; see Summary size tolerance), a memory view that grows a line per message and, past 128,000 bytes, merges in one batch down to 64,000 (so between batches it only grows at its end and each turn reads the last one's view from the cache; the view is saved and reloaded as it was), binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Compactions get their own view, as in the 2026-10-08 revision of the recipe: the memory view merged further, to between 16,000 and 32,000 bytes with the same sawtooth, ending at the line being built. A message's summary starts once fewer than 8 lines before it are unsummarized, so up to 8 compactions run at once on one cached view. An import logs its messages the same way, waiting only while 8 messages and due merges are unbuilt, so the merges keep up. Where the recipe ends a compaction's view at the first line not summarized yet, OptChat shows that line as a placeholder and keeps the lines after it: cutting there also hid the short lines that follow, such as an echo's own tool call, and an A/B on real turns scored those summaries lower (see #101). The compactor's task and its "Too long" retry are the recipe's, verbatim, with a 512-dash ruler for the size. Anthropic requests split the view into blocks of 4 lines with cache marks on the last whole one and on the blocks 20 and 40 before it, so a turn that adds up to 240 lines of tool calls and results still reads the last view from the cache, and when that view is not cached yet, one compactor call goes first and the others wait until it starts answering, so they read the cache instead of each writing it. See `docs/victor-recipe.md` for notes.
+`src/prompts.ts` holds every prompt sent to a model (the recipe's four, the subagent instruction paragraphs, the compaction task and its retry, the handoff prompt, the import note), each with a comment on where it goes; tool descriptions stay with their tools. The recipe's prompts are lightly adapted. The main agent's turn rules are the revised recipe's (2026-10-08) word for word, without its paragraph on computers, with reports starting "[id] " instead of "[Name]", and with two added sentences: don't poll anything slow (CI, a deploy) yourself, hand the watching to a subagent, and a message starting "[OptChat status]" is OptChat's own note, not the user; the view doc keeps the original's description of the view, drops its "No message appears in full" line (untrue with Previous exchange on) and its list of when to zoom, adds one sentence on zooming out from a message to the summaries above it, and ends with the revised recipe's rule that the view is the truth and zoom the only way through it; the compactor prompt is the revised recipe's intro, view and Compactions sections, with OptChat's kinds (`talk` for replies, subagent reports as `work`) and without its turn-only sections, and with its value list reworded so the size limit is a ceiling rather than a target (bare approvals are recorded as the decision they made, lines don't narrate what wasn't seen yet, and a tool result is described by what its output shows rather than by a cause guessed from an exit code or an empty match; an A/B found less filler and no recall loss, see #129); unlike the recipe, the compactor doesn't get your instructions, since an A/B found they added nothing (#112); and the subagent prompt is the original's plus a closing note on time: report progress on long tasks with tell_parent, and say so before waiting on something slow, so the main agent can go on. OptChat keeps the recipe's numbers: 512-byte summary nodes (by default summaries up to 640 bytes are accepted without a retry, as long as they are smaller than what they replace; see Summary size tolerance), a memory view that grows a line per message and, past 128,000 bytes, merges in one batch down to 64,000 (so between batches it only grows at its end and each turn reads the last one's view from the cache; the view is saved and reloaded as it was), binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Compactions get their own view, as in the 2026-10-08 revision of the recipe: the memory view merged further, to between 16,000 and 32,000 bytes with the same sawtooth, ending at the line being built. A message's summary starts once fewer than 8 lines before it are unsummarized, so up to 8 compactions run at once on one cached view. An import logs its messages the same way, waiting only while 8 messages and due merges are unbuilt, so the merges keep up. Where the recipe ends a compaction's view at the first line not summarized yet, OptChat shows that line as a placeholder and keeps the lines after it: cutting there also hid the short lines that follow, such as an echo's own tool call, and an A/B on real turns scored those summaries lower (see #101). The compactor's task and its "Too long" retry are the recipe's, verbatim, with a 512-dash ruler for the size. Anthropic requests split the view into blocks of 4 lines with cache marks on the last whole one and on the blocks 20 and 40 before it, so a turn that adds up to 240 lines of tool calls and results still reads the last view from the cache, and when that view is not cached yet, one compactor call goes first and the others wait until it starts answering, so they read the cache instead of each writing it. See `docs/victor-recipe.md` for notes.
 
 Each run's context is the memory view, the previous exchange, and your new message. Deliberate additions (the ones that change the recipe's behaviour are settings, see [Settings](#settings)):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-optchat",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "type": "module",
   "pi": {
     "extensions": [

package/src/agents.ts

@@ -11,9 +11,9 @@ import { memoryTools, searchTool } from './tools.ts';
 import { type Memory } from './memory.ts';
 import type { ModelChoice } from './compactor.ts';
 import { cachePayload } from './cache.ts';
-import { CUT_OFF, RunHistory, transition, sessionMessages, type RunInfo, type RunState, type FinishReason } from './runs.ts';
+import { CUT_OFF, RunHistory, isRunning, transition, sessionMessages, type RunInfo, type RunState, type FinishReason } from './runs.ts';
 import { UsageLedger } from './usage.ts';
-import { textContent } from './transcript.ts';
+import { fullChat, textContent } from './transcript.ts';
 import { Type } from 'typebox';
 import { result } from './tools.ts';
 import type { HandoffEvidence } from './handoff.ts';
@@ -107,6 +107,13 @@ export class Children {
     const file = this.history.records.get(id)?.sessionFile;
     return file ? sessionMessages(file) : [];
   }
+  /** A run's messages for zoom, live or finished; undefined for no such run. A subagent `reader` sees only its own descendants, as with tell. */
+  transcript(id: string, reader?: string) {
+    const known = reader ? this.history.descendants(reader).some(run => run.id === id) : this.running.has(id) || this.history.records.has(id);
+    return known ? this.messages(id) : undefined;
+  }
+  /** Runs at work now: running, waiting for children, or stopping; not paused. */
+  get working() { return [...this.running.values()].filter(live => isRunning(live.info)).map(live => live.info); }
   subscribe(listener: () => void) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
   private changed() { for (const listener of this.listeners) listener(); }
   private save(info: RunInfo) { this.history.save(info); this.changed(); }
@@ -235,7 +242,7 @@ export class Children {
     await loader.reload();
     const { session } = await (this.options.createSession ?? createAgentSession)({ cwd: directory, resourceLoader: loader, settingsManager,
       model: o.model, thinkingLevel: o.thinking, sessionManager: o.sessionManager,
-      customTools: [...memoryTools(() => this.memory), ...(memorySearch ? [searchTool(() => this.memory)] : []), ...(delegates ? this.delegationTools(id, directory, subagentLevels, maxAgents) : []), this.parentTool(id, parentId, connected)],
+      customTools: [...memoryTools(() => this.memory, run => this.transcript(run, id)), ...(memorySearch ? [searchTool(() => this.memory)] : []), ...(delegates ? this.delegationTools(id, directory, subagentLevels, maxAgents) : []), this.parentTool(id, parentId, connected)],
       excludeTools: delegates ? [] : ['spawn', 'tell'],
     });
     // Callers track the session only after this returns: clean up here if its extensions fail to start.
@@ -376,7 +383,8 @@ export class Children {
     if (this.deleting.has(info.id)) info.report = 'Deleted by the user while it was working. The user dropped this task on purpose: do not redo it or delegate it again unless they ask.';
     // A metadata failure must not suppress delivery of the actual result.
     try { this.save(info); } catch (error) { this.warn(`Could not save run metadata: ${String(error)}`); }
-    let text = `[${info.id}] ${info.report}`;
+    // A deleted run's transcript is gone.
+    let text = `[${info.id}] ${info.report}${this.deleting.has(info.id) ? '' : `\n\n${fullChat(info.id)}`}`;
     const batch = live.batch;
     let count: number | undefined;
     if (batch) {
@@ -583,7 +591,7 @@ export class Children {
           : `No transcript available. Run metadata: ${join(this.profileDirectory, 'runs', `${record.id}.optchat.json`)}`;
         return `[${record.id}] ${record.state}${record.parentId ? ` · parent ${record.parentId}` : ''}\n${location}${transcriptError ? `\nTranscript read failed: ${transcriptError}` : ''}`;
       }).join('\n');
-      handoff.text = `[${run.id}] Connected conversation ${handoff.reason === 'complete' ? 'completed by user' : `interrupted (${handoff.reason})`}. This describes the conversation ending, not proof that every task succeeded.\n${summary}\n${source}`;
+      handoff.text = `[${run.id}] Connected conversation ${handoff.reason === 'complete' ? 'completed by user' : `interrupted (${handoff.reason})`}. This describes the conversation ending, not proof that every task succeeded.\n${summary}\n${source}\n\n${fullChat(run.id)}`;
       run.report = handoff.text; this.save(run);
     }
     await this.report(handoff.text, { once: true });
@@ -607,6 +615,8 @@ export class Children {
   async remove(id: string) {
     if (!this.history.records.has(id)) throw new Error(`No subagent ${id}.`);
     if (this.deleting.has(id)) throw new Error(`${id} is already being deleted.`);
+    // A run that is live while being deleted reports its own deletion, even one a tell was resuming; a finished one has nothing left to say, so memory is told here.
+    let reports = false;
     const runs = () => [id, ...this.history.descendants(id).map(run => run.id)], marked = new Set<string>();
     // An overlapping delete of a descendant keeps its own marks, so neither delete clears the other's.
     const mark = () => { for (const run of runs()) if (!this.deleting.has(run)) { marked.add(run); this.deleting.add(run); } };
@@ -617,6 +627,7 @@ export class Children {
         await Promise.allSettled(this.launches);
         const live = runs().flatMap(run => this.running.get(run) ?? []);
         if (!live.length) break;
+        if (live.some(run => run.info.id === id)) reports = true;
         mark();
         await Promise.allSettled(live.map(run => this.stop(run.info.id)));
         await Promise.allSettled(live.map(run => run.completion));
@@ -625,6 +636,7 @@ export class Children {
       const records = runs().flatMap(run => this.history.records.get(run) ?? []);
       if (records.some(run => run.connected && !run.handoff?.delivered)) throw new Error(`${id} has a connected conversation whose handoff has not reached the main agent yet, so it was kept.`);
       for (const run of records.reverse()) this.history.remove(run.id); // Children first, so a failure never leaves one without its parent.
+      if (!reports) this.memory.append('work', `[${id}] deleted by the user`);
     } finally { for (const run of marked) this.deleting.delete(run); this.changed(); }
   }
   async close() {

package/src/browser.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { atomicWrite } from './memory.ts';
+import { atomicWrite } from './store.ts';
 import { type Memory } from './memory.ts';
 
 // One self-contained, read-only HTML snapshot of a profile's memory.

package/src/cache.ts

@@ -1,4 +1,5 @@
 import { isView } from './memory.ts';
+import { AT_WORK } from './prompts.ts';
 
 export function record(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -20,6 +21,15 @@ export function splitView(text: string) {
  * 60 blocks (240 lines). With the end of the request, that is Anthropic's limit of 4 marks. */
 const MARKS = [0, 20, 40];
 
+/** The status line's own message, in Pi's context and in Anthropic's payload alike. */
+export const isAtWork = (message: unknown) => record(message) && message.role === 'user' && Array.isArray(message.content) && message.content.length === 1
+  && record(message.content[0]) && typeof message.content[0].text === 'string' && message.content[0].text.startsWith(AT_WORK);
+function lastBlock(message: Record<string, unknown>) {
+  if (typeof message.content === 'string') message.content = [{ type: 'text', text: message.content }];
+  const block: unknown = Array.isArray(message.content) ? message.content.at(-1) : undefined;
+  return record(block) ? block : undefined;
+}
+
 /** Anthropic: marks on the view (see MARKS) plus automatic end-of-request caching, so the next call finds the last one's entry
  * and pays only for the lines after it. */
 export function cachePayload(payload: unknown): unknown {
@@ -46,6 +56,11 @@ export function cachePayload(payload: unknown): unknown {
     delete message.cache_control;
     if (Array.isArray(message.content)) for (const item of message.content) if (record(item) && !view.has(item)) delete item.cache_control;
   }
-  payload.cache_control = { type: 'ephemeral' };
+  // The status line changes between calls, so the turn's mark goes on the block before it rather than at the end of the request.
+  // Pi may end the request with an empty system message carrying settings (effort); it holds nothing to cache.
+  const [before, last] = messages.filter(message => !record(message) || message.role !== 'system').slice(-2);
+  const turn = isAtWork(last) && record(before) && before.role === 'user' ? lastBlock(before) : undefined;
+  if (turn) turn.cache_control = { type: 'ephemeral' };
+  else payload.cache_control = { type: 'ephemeral' };
   return payload;
 }

package/src/checkpoint.ts

@@ -2,7 +2,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { atomicWrite } from './memory.ts';
+import { atomicWrite } from './store.ts';
 const exec = promisify(execFile);
 
 export async function checkpoint(directory: string) {

package/src/images.ts

@@ -1,16 +1,10 @@
 import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
 import type { ImageContent } from '@earendil-works/pi-ai';
 import { resizeImage } from '@earendil-works/pi-coding-agent';
-import { atomicWrite } from './memory.ts';
+import { isMime, type Store } from './store.ts';
 
 /** Kept images fit 2048 px on the long side and ~1.5 MB (2 MB as base64), re-encoded as JPEG 85 only when they don't already. */
 export const IMAGE_LIMITS = { maxWidth: 2048, maxHeight: 2048, maxBytes: 2 * 1024 * 1024, jpegQuality: 85 };
-const EXTENSIONS = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp' } as const;
-type Mime = keyof typeof EXTENSIONS;
-const isMime = (mime: string): mime is Mime => Object.hasOwn(EXTENSIONS, mime);
-const MIMES = new Map<string, Mime>((Object.keys(EXTENSIONS) as Mime[]).map(mime => [EXTENSIONS[mime], mime]));
 
 const hash = (image: ImageContent) => createHash('sha256').update(image.data).digest('hex').slice(0, 16);
 /** How a message's image reads in memory: named by the image as the message holds it, before any shrinking, so it always gets the same name. */
@@ -19,26 +13,22 @@ const REF = /\[image ([0-9a-f]{16})\]/g;
 
 export const isImage = (part: unknown): part is ImageContent => typeof part === 'object' && part !== null
   && 'type' in part && part.type === 'image' && 'data' in part && typeof part.data === 'string' && 'mimeType' in part && typeof part.mimeType === 'string';
-const stored = (directory: string, name: string) => {
-  try { return readdirSync(join(directory, 'images')).find(file => file.startsWith(`${name}.`) && MIMES.has(file.slice(name.length + 1))); } catch { return undefined; }
-};
 
-/** Keeps each image of a message's content under `images/`, once per distinct image, shrunk to IMAGE_LIMITS. */
-export async function saveImages(directory: string, content: unknown) {
+/** Keeps each image of a message's content in the store, once per distinct image, shrunk to IMAGE_LIMITS. */
+export async function saveImages(store: Store, content: unknown) {
   if (!Array.isArray(content)) return;
   for (const image of content.filter(isImage)) {
     const name = hash(image);
-    if (stored(directory, name)) continue;
+    if (await store.image(name)) continue;
     // Pi's own resizer (Photon, WASM), as its read tool uses: it returns small images untouched, and null if it can't decode.
     const kept = await resizeImage(Buffer.from(image.data, 'base64'), image.mimeType, IMAGE_LIMITS) ?? image;
-    if (isMime(kept.mimeType)) atomicWrite(join(directory, 'images', `${name}.${EXTENSIONS[kept.mimeType]}`), Buffer.from(kept.data, 'base64'));
+    if (isMime(kept.mimeType)) await store.putImage(name, kept.mimeType, Buffer.from(kept.data, 'base64'));
   }
 }
 
 /** The kept images a text refers to, in order, each once; ones never kept are skipped. */
-export function loadImages(directory: string, text: string): ImageContent[] {
-  return [...new Set(Array.from(text.matchAll(REF), match => match[1]))].flatMap(name => {
-    const file = stored(directory, name), mimeType = file && MIMES.get(file.slice(name.length + 1));
-    return file && mimeType ? [{ type: 'image' as const, data: readFileSync(join(directory, 'images', file)).toString('base64'), mimeType }] : [];
-  });
+export async function loadImages(store: Store, text: string): Promise<ImageContent[]> {
+  const names = [...new Set(Array.from(text.matchAll(REF), match => match[1]))];
+  return (await Promise.all(names.map(name => store.image(name))))
+    .flatMap(kept => kept ? [{ type: 'image' as const, data: Buffer.from(kept.data).toString('base64'), mimeType: kept.mimeType }] : []);
 }

package/src/import/job.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, rmSync, cpSync, mkdirSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { Memory, bytes, isEntry, type Entry, type Compressor } from '../memory.ts';
-import { atomicWrite } from '../memory.ts';
+import { atomicWrite } from '../store.ts';
 import { record } from '../cache.ts';
 import { copyKey, type ImportedEntry } from './sources.ts';
 import { DEFAULT_SETTINGS } from '../settings.ts';
@@ -106,7 +106,7 @@ export async function runImport(dir: string, compress: Compressor, signal: Abort
   const plan: unknown[] = readFileSync(join(path, STAGED), 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line));
   // Every line must parse, and the plan must be whole and in order, so a damaged plan can't drop messages silently.
   if (!plan.every(isEntry) || plan.length !== job.total || plan.some((e, i) => e.i !== i)) throw new Error('Import staging data is invalid; original memory remains intact.');
-  const memory = new Memory(path, compress, () => {}, undefined, jobs);
+  const memory = await Memory.open(path, compress, () => {}, undefined, jobs);
   const report = () => progress({ messages: memory.root.length - memory.pending, total: plan.length, summaries: memory.tree.size, error: memory.lastError });
   const timer = setInterval(report, 500);
   try {

package/src/inbox.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { record } from './cache.ts';
-import { atomicWrite } from './memory.ts';
+import { atomicWrite } from './store.ts';
 import type { Memory } from './memory.ts';
 
 interface Arrival { id: string; text: string; date: string }

package/src/index.ts

@@ -6,13 +6,14 @@ import { getSupportedThinkingLevels } from '@earendil-works/pi-ai';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import { parseSkillBlock, type ExtensionAPI, type ExtensionContext, type ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
-import { atomicWrite, Memory } from './memory.ts';
+import { Memory } from './memory.ts';
+import { atomicWrite, storeFor } from './store.ts';
 import { createCompressor } from './compactor.ts';
-import { createProfile, instructions, isWindows, lastProfile, listProfiles, loadConfig, lockProfile, profilePath, rememberProfile, saveConfig, ProfileBusyError, type ProfileConfig } from './profiles.ts';
+import { createProfile, holdProfile, instructions, isWindows, lastProfile, listProfiles, loadConfig, profilePath, rememberProfile, saveConfig, ProfileBusyError, type ProfileConfig } from './profiles.ts';
 import { allowSearch, CONTINUITY, IMPORT_GUIDANCE, MASTER, SEARCH_DOC, VIEW_DOC } from './prompts.ts';
 import { cachePayload, record } from './cache.ts';
 import { saveImages } from './images.ts';
-import { asUser, boundedMessage, buildContext, logMessage, previousExchange, reportReceipt, REPORT_RECEIPT, REPORT_TYPE, RUN_BOUNDARY, textContent, typedText } from './transcript.ts';
+import { asUser, boundedMessage, atWork, buildContext, logMessage, previousExchange, reportReceipt, REPORT_RECEIPT, REPORT_TYPE, RUN_BOUNDARY, textContent, typedText } from './transcript.ts';
 import { registerReportRenderer, type ReportDetails } from './report-message.ts';
 import { memoryTools, result, searchTool } from './tools.ts';
 import { Children, CWD_DOC, loadedBuiltins } from './agents.ts';
@@ -176,7 +177,7 @@ export default function optchat(pi: ExtensionAPI) {
   const openProfile = async (name: string, ctx: ExtensionContext) => {
     const dir = profilePath(name);
     if (!existsSync(dir)) throw new Error(`Profile ${name} does not exist. Use /optchat profile to create it.`);
-    const unlock = await lockProfile(dir, `${name} · PID ${process.pid} · ${hostname()} · ${ctx.cwd}`);
+    const unlock = await holdProfile(storeFor(dir), dir, name, `${name} · PID ${process.pid} · ${hostname()} · ${ctx.cwd}`, warning => ctx.ui.notify(warning, 'warning'));
     let openingMemory: Memory | undefined;
     try {
       const config = loadConfig(dir);
@@ -186,7 +187,7 @@ export default function optchat(pi: ExtensionAPI) {
       const pending = join(dir, 'pending-reports.json');
       const saved: unknown = existsSync(pending) ? JSON.parse(readFileSync(pending, 'utf8')) : [];
       if (!Array.isArray(saved) || !saved.every(isPendingReport)) throw new Error('Invalid pending report journal.');
-      const memory = new Memory(memoryDirectory(dir), createCompressor(ctx.modelRegistry, () => config.compactor, message => {
+      const memory = await Memory.open(memoryDirectory(dir), createCompressor(ctx.modelRegistry, () => config.compactor, message => {
         usage.compression(message, 'compactor', sessionId);
         status(ctx);
       }, () => config.summaryAcceptBytes), warning => ctx.ui.notify(warning, 'error'));
@@ -328,7 +329,7 @@ export default function optchat(pi: ExtensionAPI) {
     const message = asUser(bounded);
     // Before the message is logged, so the image its text names is already there for zoom; zoom's own images are kept already.
     if (message.role === 'user' || message.role === 'toolResult' && message.toolName !== 'zoom') {
-      try { await saveImages(active.memory.directory, message.content); }
+      try { await saveImages(active.memory.store, message.content); }
       catch (error) { ctx.ui.notify(`OptChat could not keep an image: ${errorText(error)}`, 'warning'); }
     }
     if (!active) return;
@@ -379,7 +380,8 @@ export default function optchat(pi: ExtensionAPI) {
         view = a.memory.render(); // Capture old history before logging the new input.
         flush();
       }
-      return { messages: buildContext(event.messages, run, view, promptFor(prompt, a.config), previous) };
+      // Built on every call, unlike the view, so it is never out of date; it goes last, after everything cached.
+      return { messages: buildContext(event.messages, run, view, promptFor(prompt, a.config), previous, atWork(a.children.working)) };
     } catch (error) {
       // Pi catches extension errors. Explicitly abort so it cannot fall back to old context.
       ctx.abort();
@@ -415,7 +417,8 @@ export default function optchat(pi: ExtensionAPI) {
   });
   registerConnectedRenderer(pi);
   registerReportRenderer(pi);
-  for (const tool of memoryTools(() => required().memory)) pi.registerTool(tool);
+  const [zoom, date] = memoryTools(() => required().memory, id => required().children.transcript(id));
+  pi.registerTool(zoom); pi.registerTool(date);
   pi.registerTool({ ...searchTool(() => required().memory), defaultActive: false });
   // The tool and its prompt line change together, once per toggle, so the cached prefix is otherwise stable.
   // Synced on save too: a report turn started while idle reuses the tool set without before_agent_start.

package/src/memory.ts

@@ -1,6 +1,5 @@
-import { closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, writeSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
 import { EventEmitter } from 'node:events';
+import { FileStore, storeFor, type Saved, type Store } from './store.ts';
 
 export const NODE = 512;
 export const VIEW = 128_000;
@@ -34,20 +33,6 @@ export function cap(text: string, limit = CAP) {
   const tail = text.slice(/[\udc00-\udfff]/.test(text[text.length - half]) ? text.length - half + 1 : text.length - half);
   return head + notice(text.length - head.length - tail.length) + tail;
 }
-export function localDay(date = new Date()) {
-  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
-}
-export function atomicWrite(file: string, text: string | Uint8Array) {
-  mkdirSync(resolve(file, '..'), { recursive: true, mode: 0o700 });
-  const temporary = `${file}.${process.pid}.tmp`;
-  // One read-write handle: Windows refuses fsync on a read-only one, and it cannot open a directory at all, so there the file flush is the whole guarantee.
-  const fd = openSync(temporary, 'w+', 0o600);
-  try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
-  renameSync(temporary, file);
-  if (process.platform === 'win32') return;
-  const parent = openSync(resolve(file, '..'), 'r');
-  try { fsyncSync(parent); } finally { closeSync(parent); }
-}
 /** The index of the view's most due pair of sibling lines whose parent is built, or -1 (recipe §3.2). A pair is as due as
  * long ago it ended, in its own line size; equal pairs go oldest first. This is the order of Taelin's rollback push. */
 export function mostDue(view: readonly Part[], total: number, built: (part: Part) => boolean) {
@@ -94,33 +79,6 @@ class Sawtooth {
     return this.parts.length < lines;
   }
 }
-const otherWriter = (file: string) => new Error(`Another process wrote ${file}. Close every other Pi on this profile and restart Pi; nothing was written.`);
-/** With `size`, refuses to append unless the file still has that size. A last line left without its newline is ended first. Returns the new size. */
-export function appendJson(file: string, value: unknown, size?: number) {
-  const fd = openSync(file, 'a+', 0o600);
-  try {
-    const length = fstatSync(fd).size, last = Buffer.alloc(1);
-    if (size !== undefined && length !== size) throw otherWriter(file);
-    const torn = length > 0 && readSync(fd, last, 0, 1, length - 1) === 1 && last[0] !== 0x0a;
-    const data = Buffer.from((torn ? '\n' : '') + JSON.stringify(value) + '\n');
-    if (writeSync(fd, data) !== data.length) throw new Error(`Incomplete write: ${file}`);
-    fsyncSync(fd);
-    return fstatSync(fd).size;
-  } finally { closeSync(fd); }
-}
-function records(dir: string, warn: (s: string) => void): unknown[] {
-  if (!existsSync(dir)) return [];
-  const result: unknown[] = [];
-  for (const name of readdirSync(dir).filter(n => n.endsWith('.jsonl')).sort()) {
-    const file = join(dir, name);
-    for (const [index, line] of readFileSync(file, 'utf8').split('\n').entries()) {
-      if (!line.trim()) continue;
-      try { result.push(JSON.parse(line)); }
-      catch { warn(`Skipped damaged JSON at ${file}:${index + 1}`); }
-    }
-  }
-  return result;
-}
 function object(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
@@ -146,7 +104,6 @@ export class Memory {
   private readonly busy = new Map<number, Promise<void>>();
   private readonly retryAt = new Map<number, number>();
   private readonly reported = new Set<number>();
-  private readonly lastSeenBytes = new Map<string, number>();
   /** Messages without their node, and merges whose halves are built, oldest first, so the scheduler never scans the tree for work (recipe §4). */
   private readonly unbuilt = new Set<number>();
   private readonly merges = new Map<number, Part>();
@@ -157,21 +114,34 @@ export class Memory {
   private stopped = false;
   private readonly chat: Sawtooth;
   private readonly compaction: Sawtooth;
+  /** The last store write still running, if any. Once an append fails, later writes are skipped and appends throw, as after a failed file write. */
+  private writing?: Promise<void>;
+  private failed?: string;
+  /** Where this memory's local files live: all of it for a FileStore, and the browser page, runs and imports for any store. */
+  readonly directory: string;
+  readonly store: Store;
   lastError?: string;
 
-  /** `jobs`: summaries built at once, and how many unbuilt lines a new message's node waits behind. Chat keeps 8; imports pass the "Import: summaries at once" setting. */
-  constructor(readonly directory: string, private readonly compress: Compressor,
+  /** Opens the memory in `directory` through the store `storeFor` picks, after its load. */
+  static async open(directory: string, compress: Compressor, warn: (s: string) => void = console.error, budget = VIEW, jobs = 8) {
+    const store = storeFor(directory, warn);
+    return new Memory({ directory, store, saved: await store.load() }, compress, warn, budget, jobs);
+  }
+  /** A directory alone opens a FileStore there. `jobs`: summaries built at once, and how many unbuilt lines a new message's node
+   * waits behind. Chat keeps 8; imports pass the "Import: summaries at once" setting. */
+  constructor(source: string | { directory: string; store: Store; saved: Saved }, private readonly compress: Compressor,
     private readonly warn: (s: string) => void = console.error,
     readonly budget = VIEW, private readonly jobs = 8, private readonly retryMs = 10_000) {
     this.chat = new Sawtooth(budget, budget / 2, part => this.node(part));
     this.compaction = new Sawtooth(budget / 4, budget / 8, part => this.node(part));
-    for (const sub of ['main', 'tree']) mkdirSync(join(directory, sub), { recursive: true, mode: 0o700 });
-    const main = join(directory, 'main'), log = records(main, warn);
-    for (const name of readdirSync(main).filter(n => n.endsWith('.jsonl'))) this.lastSeenBytes.set(join(main, name), statSync(join(main, name)).size);
+    let saved: Saved;
+    if (typeof source === 'string') { const store = new FileStore(source, warn); this.directory = source; this.store = store; saved = store.load(); }
+    else ({ directory: this.directory, store: this.store, saved } = source);
+    const log = saved.entries;
     const entries = log.every(isEntry) ? log.sort((a, b) => a.i - b.i) : undefined;
     if (!entries || entries.some((entry, i) => entry.i !== i)) throw new Error('Invalid/noncontiguous OptChat log; refusing to change it.');
     for (const value of entries) this.root.push({ ...value, size: bytes(`${value.kind}: ${value.text}`) });
-    for (const value of records(join(directory, 'tree'), warn)) {
+    for (const value of saved.tree) {
       if (!isSummary(value) || value.l < 0 || value.i < 0 || end(value) > this.root.length)
         throw new Error('Invalid OptChat summary record.');
       this.tree.set(key(value), { ...value, size: lineBytes(value.text) });
@@ -179,34 +149,43 @@ export class Memory {
     for (const node of this.tree.values()) this.queueParent(node);
     for (let i = 0; i < this.root.length; i++) if (!this.node({ l: 0, i })) this.unbuilt.add(i);
     // Refolding the log gives a different view than the live one, and every cache entry would miss, so the view is saved.
-    const loaded = this.load();
+    const loaded = this.load(saved.view);
     for (const part of this.view) this.compaction.push(part);
     this.compaction.fit(loaded, true);
     for (let i = loaded; i < this.root.length; i++) { this.push(i); this.fit(i + 1); }
     this.fit(); this.save(); this.schedule();
   }
-  private checkLog(next: string) {
-    const main = dirname(next), names = readdirSync(main).filter(n => n.endsWith('.jsonl'));
-    if (names.length !== this.lastSeenBytes.size || names.some(n => statSync(join(main, n)).size !== this.lastSeenBytes.get(join(main, n)))) throw otherWriter(next);
-  }
   append(kind: Kind, text: string, date = new Date().toISOString(), receipt?: string, origin?: Origin) {
     if (this.stopped) throw new Error('Memory is closed.');
+    if (this.failed) throw new Error(`Memory could not be saved: ${this.failed}`);
     const entry: Entry = { i: this.root.length, kind, text, date, size: bytes(`${kind}: ${text}`), ...(receipt ? { receipt } : {}), ...(origin ? { origin } : {}) };
-    const file = join(this.directory, 'main', `${localDay()}.jsonl`);
-    if (!this.lastSeenBytes.has(file)) this.checkLog(file);
-    this.lastSeenBytes.set(file, appendJson(file, entry, this.lastSeenBytes.get(file) ?? 0));
+    void this.enqueue(() => this.store.append(entry), error => {
+      this.failed ??= error instanceof Error ? error.message : String(error);
+      this.warn(`Memory could not be saved: ${this.failed}`);
+    });
     this.root.push(entry); this.push(entry.i); if (this.fit()) this.save(); this.schedule();
     return entry;
   }
   node(part: Part) { return this.tree.get(key(part)); }
   private text(part: Part) { return this.node(part)?.text ?? UNBUILT; }
+  /** Runs a store write at once when none is running, so a store that finishes its writes as it returns (FileStore) throws here
+   * as before; otherwise after the running ones, so writes land in the order Memory makes them. Returns the queued write, settled
+   * through `failed`, unless it finished at once. */
+  private enqueue(write: () => Promise<void> | undefined, failed: (error: unknown) => void) {
+    const run = () => this.failed ? undefined : write();
+    const started = this.writing ? this.writing.then(run) : run();
+    if (!started) return;
+    const settled = started.catch(failed);
+    const tail: Promise<void> = settled.catch(() => {}).then(() => { if (this.writing === tail) this.writing = undefined; });
+    this.writing = tail;
+    return settled;
+  }
   /** Takes the saved view if it still tiles the log from the start, and returns how many messages it covers. */
-  private load() {
-    const file = join(this.directory, 'view.json');
-    if (!existsSync(file)) return 0;
-    const rebuild = () => { this.warn(`Rebuilt the memory view: ${file} does not match the log.`); return 0; };
+  private load(view: string | undefined) {
+    if (view === undefined) return 0;
+    const rebuild = () => { this.warn('Rebuilt the memory view: the saved one does not match the log.'); return 0; };
     let saved: unknown;
-    try { saved = JSON.parse(readFileSync(file, 'utf8')); } catch { return rebuild(); }
+    try { saved = JSON.parse(view); } catch { return rebuild(); }
     if (!Array.isArray(saved)) return rebuild();
     const parts: Part[] = [];
     let covered = 0;
@@ -223,8 +202,9 @@ export class Memory {
   /** Saved when it merges: a view that only grew is the saved one plus a line per later message, as `load` replays it.
    * The log stays authoritative, so a failed save only warns. */
   private save() {
-    try { atomicWrite(join(this.directory, 'view.json'), JSON.stringify(this.view.map(p => [p.l, p.i]))); }
-    catch (error) { this.warn(`Could not save the memory view: ${error instanceof Error ? error.message : String(error)}`); }
+    const failed = (error: unknown) => { this.warn(`Could not save the memory view: ${error instanceof Error ? error.message : String(error)}`); };
+    try { void this.enqueue(() => this.store.saveView(JSON.stringify(this.view.map(p => [p.l, p.i]))), failed); }
+    catch (error) { failed(error); }
   }
   private push(i: number) {
     const part = { l: 0, i };
@@ -304,7 +284,9 @@ export class Memory {
     if (this.stopped) return;
     if (!text) throw new Error('Compactor returned an empty summary.');
     const node = { ...part, text, size: lineBytes(text) };
-    appendJson(join(this.directory, 'tree', `${localDay()}.jsonl`), node);
+    // A failed node write fails the build, which is retried.
+    const written = this.enqueue(() => this.store.appendNode(node), error => { throw error; });
+    if (written) await written;
     this.tree.set(key(part), node); this.retryAt.delete(key(part)); this.merges.delete(key(part)); this.queueParent(part);
     if (!part.l) { this.unbuilt.delete(part.i); this.chat.built(part.i); this.compaction.built(part.i); }
     if (!this.retryAt.size) this.lastError = undefined;
@@ -388,6 +370,6 @@ export class Memory {
   }
   async close() {
     this.stopped = true; this.controller.abort(); clearTimeout(this.retryTimer);
-    this.events.emit('change'); await Promise.allSettled(this.busy.values());
+    this.events.emit('change'); await Promise.allSettled(this.busy.values()); await this.writing;
   }
 }

package/src/profiles.ts

@@ -5,7 +5,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import type { ModelChoice } from './compactor.ts';
 import { record } from './cache.ts';
-import { atomicWrite } from './memory.ts';
+import { atomicWrite, type Store } from './store.ts';
 import { DEFAULT_SETTINGS, readSettings, type Settings } from './settings.ts';
 
 export const isWindows = process.platform === 'win32';
@@ -127,3 +127,18 @@ export async function lockProfile(dir: string, description: string) {
   if (!isWindows) { try { chmodSync(socketPath, 0o600); } catch (error) { await unlock(); throw error; } }
   return unlock;
 }
+
+/** How often a held lease is renewed; a store lets one lapse after about 30 seconds without renewal. */
+export const HEARTBEAT_MS = 10_000;
+/** Holds the profile until the returned function is called: through the store's lease if it has one, else the machine-local lock. */
+export async function holdProfile(store: Pick<Store, 'lock'>, dir: string, profile: string, description: string, warn: (text: string) => void) {
+  const { lock } = store;
+  if (!lock) return lockProfile(dir, description);
+  const owner = await lock.lease(profile, description);
+  if (owner !== undefined) throw new ProfileBusyError(owner);
+  const beat = setInterval(() => {
+    lock.heartbeat().catch((error: unknown) => { warn(`Could not renew the profile lease: ${error instanceof Error ? error.message : String(error)}`); });
+  }, HEARTBEAT_MS);
+  beat.unref();
+  return async () => { clearInterval(beat); await lock.release(); };
+}

package/src/prompts.ts

@@ -70,6 +70,8 @@ further along than it was, and never narrate the process of summarizing
 ("output unseen", "read-only", "unconfirmed") unless that uncertainty is itself
 a fact OptChat must know. If told the line is too long, shorten it. Non-ASCII
 characters cost 2-4 bytes.`;
+/** Labels the line naming running agents, last in every main-agent request while any run (src/transcript.ts); never stored. */
+export const AT_WORK = '[OptChat status] Agents at work now: ';
 export const MASTER = `You are OptChat, an AI agent that works for one user in a single chat that
 never ends. Each turn starts with the view below, followed by the user's new
 message.
@@ -84,7 +86,8 @@ message starting "[id] ", between your tool calls or as a new turn. Never wait
 for one (no sleep, no polling): go on, or end your turn and tell the user what
 is running. The same goes for anything slow, such as CI or a deploy: don't sit
 polling it yourself at the end of a task, start a subagent to watch it, and
-move on.`;
+move on. A message starting "[OptChat status]" is OptChat's own note on which
+subagents are running, not the user.`;
 export const VIEW_DOC = `The view: the whole chat between OptChat and the user, oldest first, inside
 <chat> tags, as one-line summaries. Each line is
 

package/src/report-message.ts

@@ -1,6 +1,6 @@
 import { getMarkdownTheme, type ExtensionAPI, type Theme } from '@earendil-works/pi-coding-agent';
 import { Box, Markdown, Text } from '@earendil-works/pi-tui';
-import { REPORT_TYPE, textContent } from './transcript.ts';
+import { REPORT_TYPE, textContent, withoutFullChat } from './transcript.ts';
 
 const HEAD = /^\[([0-9a-f]{8})\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
 
@@ -9,6 +9,7 @@ export interface ReportDetails { count?: number }
 
 /** Split "[id] Message from subagent (still running): body" into a short label and the body. */
 export function reportParts(text: string, count = 1) {
+  text = withoutFullChat(text); // For the agent: the user has the Agents page.
   if (count > 1) return { label: `${count} subagent reports`, body: text };
   const match = HEAD.exec(text);
   if (!match) return { label: 'subagent', body: text };

package/src/runs.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { SessionManager } from '@earendil-works/pi-coding-agent';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
-import { atomicWrite } from './memory.ts';
+import { atomicWrite } from './store.ts';
 import { record } from './cache.ts';
 import { textContent } from './transcript.ts';
 

package/src/store.ts

@@ -0,0 +1,125 @@
+import { closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import type { Entry, Summary } from './memory.ts';
+
+/** The image types memory keeps, and the file extension each is saved under. */
+export const EXTENSIONS = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp' } as const;
+export type Mime = keyof typeof EXTENSIONS;
+export const isMime = (mime: string): mime is Mime => Object.hasOwn(EXTENSIONS, mime);
+const MIMES = new Map<string, Mime>((Object.keys(EXTENSIONS) as Mime[]).map(mime => [EXTENSIONS[mime], mime]));
+
+/** What a store gives back when a memory opens. Memory validates every record itself; `view` is the JSON `saveView` was last given. */
+export interface Saved { entries: unknown[]; tree: unknown[]; view?: string }
+/** A write is done when it returns: a store that writes behind returns a promise instead, which Memory awaits in order. */
+type Write = Promise<void> | undefined;
+type Maybe<T> = T | Promise<T>;
+
+/** Cross-machine exclusivity. Implement it only if you want it: without it OptChat keeps its machine-local lock (a socket in the
+ * profile, or a named pipe on Windows), so two Pis on one machine still can't share a profile. */
+export interface Lease {
+  /** Takes the profile for `holder` (who and where, shown to anyone refused), or returns the current holder.
+   * A lease not renewed for about 30 seconds may be taken by someone else. */
+  lease(profile: string, holder: string): Promise<string | undefined>;
+  /** Renews the lease. OptChat calls it every 10 seconds while it holds the profile and only warns when it fails, so fencing is
+   * the store's job: once its lease may have lapsed, it must refuse writes (for example with a fencing token checked on each one),
+   * since a paused process cannot be trusted to stop itself in time. */
+  heartbeat(): Promise<void>;
+  release(): Promise<void>;
+}
+
+/** Where one memory keeps what travels between machines: its message log, summary nodes, saved view and images. Everything else
+ * in a profile (runs, recovery journals, the active-memory pointer and imports, usage, settings, AGENTS.md) stays on the machine.
+ * Memory loads once when it opens, then works in RAM and issues every write in order. */
+export interface Store {
+  load(): Maybe<Saved>;
+  /** Appends a message. Throws, writing nothing, if someone else appended since this store loaded. */
+  append(entry: Entry): Write;
+  /** Appends a summary node. */
+  appendNode(node: Summary): Write;
+  /** Replaces the saved view. */
+  saveView(view: string): Write;
+  putImage(name: string, mimeType: Mime, data: Uint8Array): Write;
+  image(name: string): Maybe<{ mimeType: Mime; data: Uint8Array } | undefined>;
+  lock?: Lease;
+}
+
+/** The one place a profile's store is chosen. A `store` setting will plug in here; until then every profile keeps its memory in files. */
+export const storeFor = (directory: string, warn: (s: string) => void = console.error): Store => new FileStore(directory, warn);
+
+export function localDay(date = new Date()) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+export function atomicWrite(file: string, text: string | Uint8Array) {
+  mkdirSync(resolve(file, '..'), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  // One read-write handle: Windows refuses fsync on a read-only one, and it cannot open a directory at all, so there the file flush is the whole guarantee.
+  const fd = openSync(temporary, 'w+', 0o600);
+  try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temporary, file);
+  if (process.platform === 'win32') return;
+  const parent = openSync(resolve(file, '..'), 'r');
+  try { fsyncSync(parent); } finally { closeSync(parent); }
+}
+const otherWriter = (file: string) => new Error(`Another process wrote ${file}. Close every other Pi on this profile and restart Pi; nothing was written.`);
+/** With `size`, refuses to append unless the file still has that size. A last line left without its newline is ended first. Returns the new size. */
+export function appendJson(file: string, value: unknown, size?: number) {
+  const fd = openSync(file, 'a+', 0o600);
+  try {
+    const length = fstatSync(fd).size, last = Buffer.alloc(1);
+    if (size !== undefined && length !== size) throw otherWriter(file);
+    const torn = length > 0 && readSync(fd, last, 0, 1, length - 1) === 1 && last[0] !== 0x0a;
+    const data = Buffer.from((torn ? '\n' : '') + JSON.stringify(value) + '\n');
+    if (writeSync(fd, data) !== data.length) throw new Error(`Incomplete write: ${file}`);
+    fsyncSync(fd);
+    return fstatSync(fd).size;
+  } finally { closeSync(fd); }
+}
+function records(dir: string, warn: (s: string) => void): unknown[] {
+  if (!existsSync(dir)) return [];
+  const result: unknown[] = [];
+  for (const name of readdirSync(dir).filter(n => n.endsWith('.jsonl')).sort()) {
+    const file = join(dir, name);
+    for (const [index, line] of readFileSync(file, 'utf8').split('\n').entries()) {
+      if (!line.trim()) continue;
+      try { result.push(JSON.parse(line)); }
+      catch { warn(`Skipped damaged JSON at ${file}:${index + 1}`); }
+    }
+  }
+  return result;
+}
+
+/** Memory as files in one directory: `main/` and `tree/` hold dated JSONL, each line fsynced as it is appended; `view.json` and
+ * `images/<hash>.<ext>` are replaced atomically. Every write is done when it returns. */
+export class FileStore implements Store {
+  /** Each log file's size as this store last left it, so a write by another process is refused instead of interleaved. */
+  private readonly lastSeenBytes = new Map<string, number>();
+  constructor(readonly directory: string, private readonly warn: (s: string) => void = console.error) {}
+  load(): Saved {
+    for (const sub of ['main', 'tree']) mkdirSync(join(this.directory, sub), { recursive: true, mode: 0o700 });
+    const main = join(this.directory, 'main'), entries = records(main, this.warn);
+    for (const name of readdirSync(main).filter(n => n.endsWith('.jsonl'))) this.lastSeenBytes.set(join(main, name), statSync(join(main, name)).size);
+    const view = join(this.directory, 'view.json');
+    // An unreadable view is rebuilt, as a damaged one is.
+    let saved: string | undefined;
+    if (existsSync(view)) try { saved = readFileSync(view, 'utf8'); } catch { saved = ''; }
+    return { entries, tree: records(join(this.directory, 'tree'), this.warn), view: saved };
+  }
+  append(entry: Entry): undefined {
+    const file = join(this.directory, 'main', `${localDay()}.jsonl`);
+    if (!this.lastSeenBytes.has(file)) this.checkLog(file);
+    this.lastSeenBytes.set(file, appendJson(file, entry, this.lastSeenBytes.get(file) ?? 0));
+  }
+  private checkLog(next: string) {
+    const main = dirname(next), names = readdirSync(main).filter(n => n.endsWith('.jsonl'));
+    if (names.length !== this.lastSeenBytes.size || names.some(n => statSync(join(main, n)).size !== this.lastSeenBytes.get(join(main, n)))) throw otherWriter(next);
+  }
+  appendNode(node: Summary): undefined { appendJson(join(this.directory, 'tree', `${localDay()}.jsonl`), node); }
+  saveView(view: string): undefined { atomicWrite(join(this.directory, 'view.json'), view); }
+  putImage(name: string, mimeType: Mime, data: Uint8Array): undefined { atomicWrite(join(this.directory, 'images', `${name}.${EXTENSIONS[mimeType]}`), data); }
+  image(name: string) {
+    let file: string | undefined;
+    try { file = readdirSync(join(this.directory, 'images')).find(f => f.startsWith(`${name}.`) && MIMES.has(f.slice(name.length + 1))); } catch { return undefined; }
+    const mimeType = file && MIMES.get(file.slice(name.length + 1));
+    return file && mimeType ? { mimeType, data: readFileSync(join(this.directory, 'images', file)) } : undefined;
+  }
+}

package/src/tools.ts

@@ -1,6 +1,8 @@
-import { Type } from 'typebox';
+import { Type, type Static } from 'typebox';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import { flat, PAGE, start, type Memory } from './memory.ts';
 import { loadImages } from './images.ts';
+import { runTranscript } from './transcript.ts';
 export const result = (text: string) => ({ content: [{ type: 'text' as const, text }], details: {} });
 export const SEARCH_PAGE = 20;
 const SNIPPET = 200;
@@ -22,20 +24,39 @@ export function searchPage(memory: Memory, text: string, before?: number) {
   return `${hits.length} ${older}${hits.length === 1 ? 'message contains' : 'messages contain'} "${text}", newest first:\n${lines.join('\n')}${more}`;
 }
 
-export function memoryTools(memory: () => Memory) {
+const zoomParameters = Type.Object({ id: Type.Union([Type.Integer({ minimum: 0 }), Type.String({ minLength: 1 })]), n: Type.Optional(Type.Integer({ minimum: 1 })),
+  offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: PAGE })) });
+
+/** A page of a run's transcript, saying where the next one starts. */
+export function runPage(text: string, offset = 0, limit = PAGE) {
+  if (offset > text.length) throw new Error(`This transcript has ${text.length} characters; offset must be 0 to ${text.length}.`);
+  // Never split a surrogate pair: a page starts on its first half and ends after its second.
+  const from = /[\udc00-\udfff]/.test(text[offset] ?? '') ? offset - 1 : offset;
+  let to = Math.min(text.length, from + limit);
+  if (to < text.length && /[\ud800-\udbff]/.test(text[to - 1])) to += to - 1 === from ? 1 : -1;
+  return `${text.slice(from, to)}\n[characters ${from}-${to} of ${text.length}${to < text.length ? `; go on with offset ${to}` : ''}]`;
+}
+
+/** `runs` gives a subagent's messages by run id, live or finished; undefined for no such run. */
+export function memoryTools(memory: () => Memory, runs?: (id: string) => readonly AgentMessage[] | undefined) {
   return [
-    { name: 'zoom', label: 'Zoom memory', description: `Open the line id+n of the view into the two lines of n/2 under it; n = 1 gives the message whole. A message over ${PAGE.toLocaleString('en-US')} characters comes in pages; offset and limit (characters) read any part of it, and are not needed for a shorter one. A message's images come back with it.`,
-      parameters: Type.Object({ id: Type.Integer({ minimum: 0 }), n: Type.Integer({ minimum: 1 }),
-        offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: PAGE })) }),
-      async execute(_id: string, args: { id: number; n: number; offset?: number; limit?: number }) {
-        const m = memory(), text = m.zoom(args.id, args.n, args.offset, args.limit), page = result(text);
+    { name: 'zoom', label: 'Zoom memory', description: `Open the line id+n of the view into the two lines of n/2 under it; n = 1 (the default) gives the message whole. A message over ${PAGE.toLocaleString('en-US')} characters comes in pages; offset and limit (characters) read any part of it, and are not needed for a shorter one. A message's images come back with it. zoom("<run id>") gives a subagent's whole chat so far, in the same pages.`,
+      parameters: zoomParameters,
+      async execute(_id: string, { id, n = 1, offset, limit }: Static<typeof zoomParameters>) {
+        if (typeof id === 'string') {
+          const messages = runs?.(id);
+          if (messages) return result(runPage(runTranscript(messages), offset, limit));
+          // A model may quote a message id; eight digits can be a run id (src/agents.ts), so those never open a message.
+          if (!/^\d+$/.test(id) || id.length === 8) throw new Error(`No run ${id}.`);
+        }
+        const m = memory(), text = m.zoom(Number(id), n, offset, limit), page = result(text);
         // A message's images come back with its text, as read returns a PNG; summaries stay text.
-        return args.n === 1 ? { ...page, content: [...page.content, ...loadImages(m.directory, text)] } : page;
+        return n === 1 ? { ...page, content: [...page.content, ...await loadImages(m.store, text)] } : page;
       } },
     { name: 'date', label: 'Memory date', description: 'The date and time of message id.',
       parameters: Type.Object({ id: Type.Integer({ minimum: 0 }) }),
       async execute(_id: string, args: { id: number }) { return result(memory().date(args.id)); } },
-  ];
+  ] as const;
 }
 
 export const searchTool = (memory: () => Memory) => ({ name: 'search', label: 'Search memory',

package/src/transcript.ts

@@ -2,7 +2,8 @@ import { createHash } from 'node:crypto';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
 import { getCurrentSystemMessage, type SystemMessage, type UserMessage } from '@earendil-works/pi-ai';
-import { CAP, cap, type Memory } from './memory.ts';
+import { CAP, cap, flat, isView, type Memory } from './memory.ts';
+import { AT_WORK } from './prompts.ts';
 import { record } from './cache.ts';
 import { DEFAULT_SETTINGS } from './settings.ts';
 import { imageRef, isImage } from './images.ts';
@@ -124,9 +125,45 @@ function latestExchange(branch: readonly SessionEntry[]) {
   return latest;
 }
 
-/** Keep one completed exchange plus the current run; all other history comes from the view. */
+/** Ends every subagent report, so the parent knows it can check the report against what the child did. */
+export const fullChat = (id: string) => `Full chat: zoom("${id}")`;
+export const withoutFullChat = (text: string) => text.replace(/\n\nFull chat: zoom\("[\w-]+"\)$/gm, '');
+const TASK = '\n</chat>\n\nYour task:\n';
+/** Tool calls and results in a run transcript keep their head and tail, so a page holds many steps. */
+const STEP = 1_000;
+/** A subagent's chat for zoom, as `kind|text` lines: its task without the memory view, replies, tool calls and results, and what it was told. */
+export function runTranscript(messages: readonly AgentMessage[]) {
+  const task = messages.find(message => message.role === 'user');
+  return messages.flatMap(message => {
+    if (message.role === 'user') {
+      // Only the task prompt holds the memory view (src/agents.ts): `${view}\n\nYour task:\n${task}`.
+      const text = textContent(message.content, false), at = text.indexOf(TASK);
+      return [`user|${message === task && isView(text) && at >= 0 ? text.slice(at + '\n</chat>\n\n'.length) : text}`];
+    }
+    if (message.role === 'toolResult') return [`echo|${cap(`${message.toolName}: ${textContent(message.content, false)}`, STEP)}`];
+    if (message.role !== 'assistant') return [];
+    return [...message.content.flatMap(block => block.type === 'text' && block.text.trim() ? [`talk|${block.text}`]
+      : block.type === 'toolCall' ? [`tool|${cap(`${block.name} ${JSON.stringify(block.arguments)}`, STEP)}`] : []),
+    ...message.stopReason === 'error' || message.stopReason === 'aborted' ? [`echo|Agent ${message.stopReason}: ${message.errorMessage ?? 'No further details'}`] : []];
+  }).join('\n');
+}
+
+/** The status line naming running agents by id and the first words of their task; none while nothing runs. */
+export function atWork(runs: readonly { id: string; task: string }[]) {
+  if (!runs.length) return undefined;
+  return AT_WORK + runs.map(({ id, task }) => {
+    const words = flat(task).replaceAll('"', "'").split(/\s+/).filter(Boolean), start = words.slice(0, 6).join(' ');
+    // Six words, but never more than 60 characters: a task can be one long word.
+    const preview = [...start].slice(0, 60).join('');
+    return `${id} "${preview}${words.length > 6 || preview.length < start.length ? '…' : ''}"`;
+  }).join(', ') + '.';
+}
+
+/** Keep one completed exchange plus the current run; all other history comes from the view.
+ * `status` goes last, after everything cached, so it never moves the cached prefix (see cachePayload). It comes with new input only
+ * (the user, a report, a restart note): a call that follows a tool result is the same turn, which already had it. */
 export function buildContext(canonical: AgentMessage[], run: AgentMessage[], view: string, prompt: string,
-  previous: readonly AgentMessage[] = []): AgentMessage[] {
+  previous: readonly AgentMessage[] = [], status?: string): AgentMessage[] {
   const system = getCurrentSystemMessage(canonical);
   const head: SystemMessage = { role: 'system', content: prompt, toolsAdded: system?.toolsAdded, timestamp: 0 };
   if (!run.some(m => m.role === 'user')) throw new Error('OptChat has no current user message; refusing to send historical context.');
@@ -136,5 +173,5 @@ export function buildContext(canonical: AgentMessage[], run: AgentMessage[], vie
     injected = true;
     return { ...message, content: [{ type: 'text' as const, text: view }, ...(typeof message.content === 'string' ? [{ type: 'text' as const, text: message.content }] : message.content)] };
   });
-  return [head, ...messages];
+  return [head, ...messages, ...status && messages.at(-1)?.role !== 'toolResult' ? [{ role: 'user' as const, content: [{ type: 'text' as const, text: status }], timestamp: 0 }] : []];
 }

package/src/usage.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import type { AssistantMessage, Usage } from '@earendil-works/pi-ai';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
 import { record } from './cache.ts';
-import { appendJson } from './memory.ts';
+import { appendJson } from './store.ts';
 
 export type UsageRole = 'main' | 'subagent' | 'compactor' | 'import';
 export const ranges = ['This session', 'Last hour', 'Today', 'Last 7 days', 'All time'] as const;