pi-optchat 0.6.7 → 0.6.8

package/README.md

@@ -1,3 +1,5 @@
+![Pi-OptChat: persistent memory for Pi](https://raw.githubusercontent.com/jonaslsaa/pi-optchat/main/docs/banner.jpg)
+
 # pi-optchat
 
 A Pi extension that implements [Victor Taelin's OptChat recipe](https://gist.github.com/VictorTaelin/91837951a5ce5b38f341ec1ba1df6449): one endless chat per profile, remembered through a summary tree instead of compaction.
@@ -41,6 +43,7 @@ For headless use, pass `--optchat-profile work`.
 | --- | --- |
 | `/optchat` | Status and actions menu. |
 | `/optchat profile` | Select or create a profile. Switching starts a fresh Pi session. |
+| `/optchat settings` | This profile's settings: models, subagent levels and limits, previous exchange, summary size tolerance. |
 | `/optchat model` | Compactor model and effort for this profile. |
 | `/optchat agents` | Live agent tree and saved run history. |
 | `/optchat agents model` | Subagent model and effort for this profile. |
@@ -63,6 +66,26 @@ Subagent and compactor settings are saved per profile and do not follow the main
 
 Compression and subagents make extra model requests with your provider credentials.
 
+## Settings
+
+`/optchat settings` opens this profile's settings. Each row shows its value and default, the selected row says what it does and when a change applies, and a change is saved right away to the profile's `config.json`. Defaults follow Victor's recipe, except Previous exchange and Summary size tolerance, which keep OptChat's earlier behaviour.
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| Compactor model | Sonnet 5.5, medium | Same as `/optchat model`. Applies to the next summary. |
+| Subagent model | Opus 5.5, high | Same as `/optchat agents model`. Applies to new subagents. |
+| Subagent levels | 1 | 1: only the main agent starts subagents (the recipe). 2 or more: subagents may start their own, that many levels deep. Applies to subagents started or resumed after the change. |
+| Max active agents | 8 | Subagents running at once in the profile, all levels together, so it also caps how deep a chain can go. |
+| Previous exchange | on | Replays your last request and answer in full with the next turn (see below). Off is the recipe. |
+| Previous exchange limit | 16 KB | A larger last exchange is left out. |
+| Summary size tolerance | 640 bytes | The compactor is always asked for 512-byte lines; a longer line up to this size is kept instead of retried. 512 is the recipe's strict rule. |
+
+Numbers must be whole numbers of at least 1 (512 for the summary size tolerance). Missing keys in an older `config.json` take their defaults.
+
+**Upgrading from 0.6.x:** subagent levels used to be fixed at 3 and now default to 1, so subagents no longer start their own subagents until you set Subagent levels to 2 or 3.
+
+![Settings page](docs/screenshots/settings.png)
+
 ## Subagents
 
 Ask in plain words, for example: "Spawn an agent to investigate this repository and report back."
@@ -72,9 +95,9 @@ Ask in plain words, for example: "Spawn an agent to investigate this repository
 - Each child reports back on its own when it finishes. 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. (One exception: reports recovered at startup, before your first message in the session, still show as plain user messages.)
 - 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 of the 8 slots. Connected windows can't be resumed, and a child whose transcript is missing must be spawned fresh.
-- Delegation goes up to three levels below the main agent (child, grandchild, great-grandchild).
-- At most 8 agents can be active per profile, including parents waiting on descendants. Going over a limit returns an error; there is no queue.
+- `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).
+- **Max active agents** (8 by default) caps how many agents can be active per profile, including parents waiting on descendants. Going over a limit returns an error; there is no queue.
 - Stopping an agent stops its whole subtree. A failed parent stops its descendants.
 - Agents run inside the Pi process. Closing Pi stops them; there is no detached mode.
 
@@ -119,7 +142,7 @@ Guidance shows as queued until delivered, or undelivered if the child stops firs
 Pick the destination profile, then run `/optchat import`.
 
 1. **Source**: Claude Code (`~/.claude/projects`), Claude Code memories, Codex (`~/.codex/sessions`, `~/.codex/archived_sessions`), or a ChatGPT export (ZIP, folder, or `conversations.json`; ZIP needs `unzip`). Scanning is local and makes no model calls.
-2. **Select**: for Claude Code, its memories, and Codex, pick projects (busiest first), optionally filter by start date, then take all conversations or pick some. **Space** toggles, **Enter** continues, type to filter, **Ctrl+A**/**Ctrl+D** select/clear matches, **Esc** cancels. Nothing is classified as work or personal for you.
+2. **Select**: for Claude Code, its memories, and Codex, pick projects (busiest first), optionally filter by start date, then take all conversations or pick some. **Tab** toggles (and **Space** when the filter is empty), **Enter** continues, type to filter, **Ctrl+A**/**Ctrl+D** select/clear matches, **Esc** cancels. Nothing is classified as work or personal for you.
 3. **Mode** (only if the profile already has history):
    - **Append**: keep existing summaries and add the import. Faster and cheaper.
    - **Rebuild by conversation start date**: regenerate the whole tree, ordered by conversation start.
@@ -189,12 +212,12 @@ To delete a profile, delete its folder. Your original Pi sessions are kept in Pi
 
 ## How it differs from the recipe
 
-The recipe's four prompts are kept verbatim in `src/prompts.ts`, along with its numbers: 512-byte summary nodes (summaries up to 640 bytes are accepted without a retry), a 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Anthropic requests get stable cache breakpoints on the view, 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.
+The recipe's four prompts are kept verbatim in `src/prompts.ts`, along with its 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 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Anthropic requests get stable cache breakpoints on the view, 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:
+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)):
 
-1. **Previous exchange kept verbatim.** Your last request (with any steering) and the final answer are included in full, so "why is that?" refers to what you actually read. Tool calls and reasoning are not carried over. It comes on top of the 128,000-byte view and is not truncated. A new Pi session starts with the memory view only.
-2. **Subagents** are built in with Pi's SDK rather than a separate package. Children report individually instead of per batch, and can delegate two extra levels.
+1. **Previous exchange kept verbatim.** Your last request (with any steering) and the final answer are included in full, so "why is that?" refers to what you actually read. Tool calls and reasoning are not carried over. It comes on top of the 128,000-byte view. If it is over 16,000 bytes (about 4,000 tokens, usually a big paste; Previous exchange limit) it is left out entirely, and the model relies on the view and zoom as in Victor's recipe. A new Pi session starts with the memory view only.
+2. **Subagents** are built in with Pi's SDK rather than a separate package. Children report individually instead of per batch, and with Subagent levels above 1 they can delegate further.
 3. **Profiles**, the **inspector**, the **usage ledger**, **import**, and **connected windows** are additions. Import adds historical-record guidance to the prompts.
 4. **Not done**: computer use and hosting on an always-on machine.
 

package/docs/victor-recipe.md

@@ -13,8 +13,9 @@ The source remains upstream rather than duplicating the full article here. Its f
 - `src/memory.ts`: append-only log, binary summary tree, compression scheduling, bounded view, zoom/date.
 - `src/compactor.ts`: contextual compression and size retries.
 - `src/cache.ts`: stable Anthropic cache boundaries.
-- `src/transcript.ts`: fresh context per parent run, current-run tool loop retained. The previous completed exchange is also retained in full text, an intentional addition to the summary-only recipe for conversational continuity.
+- `src/transcript.ts`: fresh context per parent run, current-run tool loop retained. The previous completed exchange is also retained in full text (left out if over 16,000 bytes by default), an intentional addition to the summary-only recipe for conversational continuity.
 - `src/agents.ts`: asynchronous Pi SDK children and automatic completion reports.
+- `src/settings.ts`: per-profile settings for the departures from the recipe. Defaults are the recipe's (one subagent level), except the previous exchange (on) and the summary size tolerance (640 bytes, against the recipe's strict 512).
 - `src/import/`: profile-scoped historical imports retain user messages and final assistant replies, following the lighter history described in recipe section 10. Source adapters, final-reply detection, replay filtering, and ChatGPT branch labels are integration choices. Live-chat tool logging remains unchanged.
 
 Profiles, native Pi UI, conversation import, and local Git checkpoints are integration choices described in the README.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "pi-optchat",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "type": "module",
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/jonaslsaa/pi-optchat/main/docs/banner.jpg"
   },
   "scripts": {
     "check": "tsc --noEmit",

package/src/agents.ts

@@ -11,12 +11,13 @@ import { memoryTools } from './tools.ts';
 import { type Memory } from './memory.ts';
 import type { ModelChoice } from './compactor.ts';
 import { cachePayload } from './cache.ts';
-import { RunHistory, sessionMessages, type RunInfo, type FinishReason } from './runs.ts';
+import { RunHistory, transition, sessionMessages, type RunInfo, type RunState, type FinishReason } from './runs.ts';
 import { UsageLedger } from './usage.ts';
 import { textContent } from './transcript.ts';
 import { Type } from 'typebox';
 import { result } from './tools.ts';
 import type { HandoffEvidence } from './handoff.ts';
+import { DEFAULT_SETTINGS, type Settings } from './settings.ts';
 
 export interface LiveRun {
   session: AgentSession; info: RunInfo; updated: number; streaming?: AgentMessage;
@@ -26,6 +27,8 @@ export interface LiveRun {
 interface Options { parentSession?: string; usage?: UsageLedger; createSession?: typeof createAgentSession;
   /** Names of the built-in extensions the main session loaded (see `loadedBuiltins`). */
   builtins?: () => Iterable<string>;
+  /** Read on every spawn, so a changed profile setting applies to the next one. */
+  settings?: () => Pick<Settings, 'subagentLevels' | 'maxAgents'>;
   summarizeHandoff?: (run: RunInfo, messages: AgentMessage[], descendants?: HandoffEvidence[]) => Promise<string> }
 
 // Subagents load the user's installed extensions, except any copy of OptChat itself: they get memory tools directly and must not open a profile.
@@ -65,6 +68,7 @@ export class Children {
   private launching = 0;
   private readonly resuming = new Set<string>();
   private settling = 0;
+  private readonly launches = new Set<Promise<unknown>>();
   private readonly completions = new Set<Promise<void>>();
   constructor(private readonly memory: Memory, private readonly registry: ModelRegistry,
     private readonly choice: () => ModelChoice, private readonly instructions: () => string,
@@ -80,6 +84,8 @@ export class Children {
       } catch (error) { warn(`Could not backfill child usage for ${run.id}: ${String(error)}`); }
     }
   }
+  private get settings() { return this.options.settings?.() ?? DEFAULT_SETTINGS; }
+  private full(extra: number) { return this.running.size + this.launching + extra > this.settings.maxAgents; }
   get ids() { return [...this.running.keys()]; }
   get active() { return this.completions.size > 0 || this.launching > 0 || this.settling > 0; }
   live(id: string) { return this.running.get(id); }
@@ -125,13 +131,34 @@ export class Children {
     const cancelled = () => this.closing || (parentId !== undefined && this.running.get(parentId)?.info.state !== 'running');
     if (parentId && (!parent || parent.info.state !== 'running')) throw new Error('The parent is no longer running.');
     const depth = parent ? parent.info.depth + 1 : 1;
-    if (depth > 3) throw new Error('Delegation depth limit reached: great-grandchildren cannot spawn.');
+    const { subagentLevels, maxAgents } = this.settings;
+    if (depth > subagentLevels) throw new Error(`Delegation depth limit reached: this profile allows ${subagentLevels} level${subagentLevels === 1 ? '' : 's'} of subagents.`);
     if (this.closing) throw new Error('Profile is closing.');
-    if (this.running.size + this.launching + tasks.length > 8) throw new Error('Profile limit: at most 8 active agents, including parents and descendants. Reduce the batch or continue without delegating.');
+    if (this.full(tasks.length)) throw new Error(`Profile limit: at most ${maxAgents} active agents, including parents and descendants. Reduce the batch or continue without delegating.`);
     const view = this.memory.render();
     const selected = this.choice();
     const model = this.registry.find(selected.provider, selected.model);
     if (!model) throw new Error(`Subagent model unavailable: ${selected.provider}/${selected.model}`);
+    const launched = await this.track(this.launchBatch({ tasks, cwd, depth, parentId, connected, selected, model, signal, cancelled }));
+    // Each child reports independently. A slow sibling must not hold back a finished result.
+    for (const live of launched) {
+      const work = this.execute(live, `${view}\n\nYour task:\n${live.info.task}`).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
+        .finally(() => { this.completions.delete(work); this.changed(); });
+      this.completions.add(work);
+      live.completion = work;
+    }
+    this.changed();
+    return launched.map(c => c.info.id);
+  }
+  /** close() waits for launches, so shutdown never unlocks the profile under a child that is still opening. */
+  private track<T>(launch: Promise<T>) {
+    this.launches.add(launch);
+    const done = () => { this.launches.delete(launch); };
+    launch.then(done, done);
+    return launch;
+  }
+  private async launchBatch({ tasks, cwd, depth, parentId, connected, selected, model, signal, cancelled }: { tasks: { task: string; cwd?: string }[]; cwd: string; depth: number; parentId?: string; connected: boolean;
+    selected: ModelChoice; model: Model<Api>; signal?: AbortSignal; cancelled: () => boolean }) {
     const launched: LiveRun[] = [];
     let reserved = tasks.length;
     this.launching += reserved;
@@ -155,28 +182,21 @@ export class Children {
       for (const child of launched) {
         await this.shutdown(child.session); // Extensions such as MCP close their connections and stop their server processes.
         this.dispose(child.session); this.running.delete(child.info.id);
-        child.info.state = 'failed'; child.info.ended = Date.now(); child.info.report = `Launch failed: ${String(error)}`;
+        transition(child.info, 'failed'); child.info.ended = Date.now(); child.info.report = `Launch failed: ${String(error)}`;
         if (child.info.connected) child.info.handoff = { reason: signal?.aborted ? 'disconnected' : 'failed' };
         this.save(child.info);
         if (child.info.connected) await this.deliverHandoff(child.info).catch(error => this.warn(`Handoff saved for recovery: ${String(error)}`));
       }
       throw error;
     } finally { this.launching -= reserved; }
-    // Each child reports independently. A slow sibling must not hold back a finished result.
-    for (const live of launched) {
-      const work = this.execute(live, `${view}\n\nYour task:\n${live.info.task}`).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
-        .finally(() => { this.completions.delete(work); this.changed(); });
-      this.completions.add(work);
-      live.completion = work;
-    }
-    this.changed();
-    return launched.map(c => c.info.id);
+    return launched;
   }
   /** Builds a child session with the same prompt, tools and extensions whether it is new or resumed. */
   private async open(o: { id: string; directory: string; depth: number; parentId?: string; connected: boolean; provider: string; model: Model<Api>;
     thinking?: ModelChoice['thinking']; sessionManager: SessionManager }) {
     const { id, directory, depth, parentId, connected } = o;
-    const delegation = depth < 3 ? 'You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows 8 active agents total.' : 'You are at the maximum delegation depth. Complete your task with your own tools.';
+    const { subagentLevels, maxAgents } = this.settings, delegates = depth < subagentLevels;
+    const delegation = delegates ? `You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows ${maxAgents} active agents total.` : 'You are at the maximum delegation depth. Complete your task with your own tools.';
     const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
       : 'Use tell_parent only when your parent needs something now (a blocking question, an important early finding, or when asked to). Your final answer is delivered automatically; do not repeat it with tell_parent.'].filter(Boolean).join('\n\n');
     // The user's settings list their installed packages; a copy in memory keeps the child from writing them back.
@@ -198,17 +218,17 @@ 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), ...(depth < 3 ? this.delegationTools(id, directory) : []), this.parentTool(id, parentId, connected)],
-      excludeTools: depth < 3 ? [] : ['spawn', 'tell'],
+      customTools: [...memoryTools(() => 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.
     try { await session.bindExtensions({}); }
     catch (error) { await this.shutdown(session); this.dispose(session); throw error; }
     return session;
   }
-  private delegationTools(parentId: string, cwd: string) {
-    return [{ name: 'spawn', label: 'Delegate task', description: 'Delegate parts of your task. Results arrive automatically after this run; never poll or sleep waiting. Maximum depth 3 and 8 active agents per profile.',
-      parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })) }), { minItems: 1, maxItems: 8 }) }),
+  private delegationTools(parentId: string, cwd: string, levels: number, maxAgents: number) {
+    return [{ name: 'spawn', label: 'Delegate task', description: `Delegate parts of your task. Results arrive automatically after this run; never poll or sleep waiting. Maximum depth ${levels} and ${maxAgents} active agents per profile.`,
+      parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })) }), { minItems: 1 }) }),
       execute: async (_id: string, args: { tasks: { task: string; cwd?: string }[] }, signal?: AbortSignal) => result(`Started: ${(await this.spawn(args.tasks, cwd, signal, parentId)).join(', ')}. Results will arrive automatically.`),
     }, { name: 'tell', label: 'Guide child', description: 'Send guidance to one of your direct children. A finished child is resumed with its earlier conversation, and its new report arrives automatically.',
       parameters: Type.Object({ id: Type.String(), message: Type.String() }),
@@ -248,34 +268,36 @@ export class Children {
     const { session, info } = live;
     try {
       if (info.connected) await this.report(`[${info.id}] User started a connected conversation in ${info.cwd}. That agent is handling this request with the user directly; don't do it yourself. Initial message: ${info.task}\n\nUse tell with this agent ID only if you know something it needs. It stays open between replies and sends a final handoff on completion or disconnect.`);
-      if (this.closing || info.handoff) throw new Error('Conversation stopped before its first request.');
+      // A stop that lands before the first prompt has no turn to abort, so it is honoured here.
+      const state: RunState = info.state; // a local, so the loop below still sees later state changes
+      if (this.closing || info.handoff || state === 'stopping') throw new Error('Stopped before its first request.');
       await session.prompt(prompt);
       while (info.state !== 'stopping') {
         const last = session.messages.findLast(m => m.role === 'assistant');
         if (last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted')) break;
         if (live.pendingGuidance.length) {
-          info.state = 'running'; this.save(info);
+          transition(info, 'running'); this.save(info);
           await session.prompt(live.pendingGuidance.shift()!);
           continue;
         }
         if (live.pendingReports.length) {
-          info.state = 'running'; this.save(info);
+          transition(info, 'running'); this.save(info);
           await session.prompt(live.pendingReports.splice(0).join('\n\n'));
           continue;
         }
         const children = this.directChildren(info.id).flatMap(child => child.completion ? [child.completion] : []);
         if (!children.length && !info.connected) break;
         const wake = new Promise<void>(resolve => { live.wake = resolve; });
-        info.state = 'waiting'; this.save(info);
+        transition(info, 'waiting'); this.save(info);
         await Promise.race([...children, wake]); live.wake = undefined;
       }
       const last = session.messages.findLast(m => m.role === 'assistant');
-      info.state = info.state === 'stopping' || last?.role === 'assistant' && last.stopReason === 'aborted' ? 'stopped'
-        : last?.role === 'assistant' && last.stopReason === 'error' ? 'failed' : 'completed';
+      transition(info, info.state === 'stopping' || last?.role === 'assistant' && last.stopReason === 'aborted' ? 'stopped'
+        : last?.role === 'assistant' && last.stopReason === 'error' ? 'failed' : 'completed');
       info.report = last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted')
         ? `Task ${last.stopReason}: ${last.errorMessage ?? 'No details'}` : session.getLastAssistantText() || 'Finished without a text report.';
     } catch (error) {
-      info.state = info.state === 'stopping' ? 'stopped' : 'failed'; info.report = `${info.state}: ${String(error)}`;
+      transition(info, info.state === 'stopping' ? 'stopped' : 'failed'); info.report = `${info.state}: ${String(error)}`;
     } finally {
       const children = this.directChildren(info.id);
       await Promise.allSettled(children.map(child => this.stop(child.info.id)));
@@ -288,7 +310,7 @@ export class Children {
     }
     if (info.connected) {
       info.handoff ??= { reason: 'failed' };
-      info.state = info.handoff.reason === 'complete' ? 'completed' : 'interrupted';
+      transition(info, info.handoff.reason === 'complete' ? 'completed' : 'interrupted');
       this.save(info);
       await this.deliverHandoff(info);
       return;
@@ -311,7 +333,7 @@ export class Children {
   /** `caller` is the agent sending a manager message: undefined for the main agent, else the parent subagent's ID. */
   async tell(id: string, message: string, source: 'manager' | 'user' = 'manager', caller?: string) {
     const live = this.running.get(id);
-    if (!live && source === 'manager' && this.history.records.has(id)) return this.resume(id, message, caller);
+    if (!live && source === 'manager' && this.history.records.has(id)) return this.track(this.resume(id, message, caller));
     if (live && !['running', 'waiting'].includes(live.info.state)) throw new Error(`${id} is finishing. Its report will arrive on its own${live.info.connected || source === 'user' ? '' : '; tell it again after that to resume it'}.`);
     if (!live) throw new Error(`No running subagent ${id}.`);
     const text = live.info.connected && source === 'manager' ? `[Main agent guidance]\n${message.trim()}` : message.trim(); if (!message.trim()) throw new Error('Message is empty.');
@@ -323,6 +345,7 @@ export class Children {
       else await live.session.steer(text);
     }
     catch (error) { guidance.state = 'undelivered'; this.save(live.info); throw error; }
+    if (guidance.state === 'undelivered') throw new Error(`${id} finished before it read the message. Tell it again to resume it.`);
     return 'Message queued for the next tool boundary.';
   }
   /** Reopens a finished child from its saved transcript, same ID, parent and model, and gives it a new message. */
@@ -338,7 +361,7 @@ export class Children {
         : `Only ${id}'s parent ${run.parentId} can resume it, and that parent is no longer running. Resume ${run.parentId} instead, or spawn a new subagent.`);
     }
     if (this.closing) throw new Error('Profile is closing.');
-    if (this.running.size + this.launching + 1 > 8) throw new Error(`Profile limit: at most 8 active agents, including parents and descendants. ${id} can be resumed when one finishes.`);
+    if (this.full(1)) throw new Error(`Profile limit: at most ${this.settings.maxAgents} active agents, including parents and descendants. ${id} can be resumed when one finishes.`);
     let manager: SessionManager | undefined;
     try { if (run.sessionFile && existsSync(run.sessionFile)) manager = SessionManager.open(run.sessionFile); } catch { manager = undefined; }
     if (!manager?.getEntries().some(e => e.type === 'message')) throw new Error(`The saved transcript of ${id} is missing or unreadable, so it cannot be resumed. Spawn a fresh subagent and give it the context it needs.`);
@@ -387,7 +410,7 @@ export class Children {
     const recovery = (async () => {
       for (const run of eligible) {
         run.handoff ??= { reason: 'owner-stopped' };
-        run.state = run.handoff.reason === 'complete' ? 'completed' : 'interrupted'; this.save(run);
+        transition(run, run.handoff.reason === 'complete' ? 'completed' : 'interrupted'); this.save(run);
         await this.deliverHandoff(run);
       }
     })();
@@ -426,17 +449,18 @@ export class Children {
     const descendants: LiveRun[] = [];
     const collect = (run: LiveRun) => { descendants.push(run); for (const child of this.directChildren(run.info.id)) collect(child); };
     collect(live);
-    for (const run of descendants) {
+    const stopping = descendants.filter(run => transition(run.info, 'stopping'));
+    for (const run of stopping) {
       if (run.info.connected) run.info.handoff ??= { reason: 'owner-stopped' };
-      run.info.state = 'stopping';
       run.wake?.();
       try { this.save(run.info); } catch (error) { this.warn(`Could not save stop status: ${String(error)}`); }
     }
-    await Promise.allSettled(descendants.map(run => run.session.abort()));
+    await Promise.allSettled(stopping.map(run => run.session.abort()));
   }
   async close() {
     this.closing = true;
     await Promise.allSettled([...this.running.keys()].map(id => this.stop(id)));
+    await Promise.allSettled(this.launches);
     await Promise.allSettled(this.completions);
   }
 }

package/src/cache.ts

@@ -1,3 +1,5 @@
+import { isView } from './memory.ts';
+
 export function record(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -19,38 +21,26 @@ export function splitView(text: string) {
 export function cachePayload(payload: unknown): unknown {
   if (!record(payload) || !Array.isArray(payload.messages)) return payload;
   const messages = payload.messages;
-  let found = false;
+  const view = new Set<unknown>();
   for (const message of messages) {
     if (!record(message) || message.role !== 'user' || !Array.isArray(message.content)) continue;
-    for (let i = 0; i < message.content.length; i++) {
-      const block: unknown = message.content[i];
-      if (!record(block) || block.type !== 'text' || typeof block.text !== 'string' || !block.text.startsWith('<chat>\n')) continue;
-      found = true;
-      const pieces = splitView(block.text);
-      message.content.splice(i, 1, ...pieces.map((text, j) => ({ type: 'text', text,
-        ...(j < pieces.length - 1 ? { cache_control: { type: 'ephemeral' } } : {}) })));
-      break;
-    }
-    if (found) break;
+    const at = message.content.findIndex((block: unknown) => record(block) && block.type === 'text' && typeof block.text === 'string' && isView(block.text));
+    if (at < 0) continue;
+    const pieces = splitView(message.content[at].text);
+    const blocks = pieces.map((text, j) => ({ type: 'text', text, ...(j < pieces.length - 1 ? { cache_control: { type: 'ephemeral' } } : {}) }));
+    message.content.splice(at, 1, ...blocks);
+    for (const block of blocks) view.add(block);
+    break;
   }
-  if (!found) return payload;
+  if (!view.size) return payload;
   // Pi's default system/recent-message marks would exceed Anthropic's four-mark limit.
-  // Remove all adapter marks first, keeping only the newly split view's three marks.
   for (const section of [payload.system, payload.tools]) {
     if (Array.isArray(section)) for (const item of section) if (record(item)) delete item.cache_control;
   }
-  let seenView = false;
   for (const message of messages) {
     if (!record(message)) continue;
     delete message.cache_control;
-    if (!Array.isArray(message.content)) continue;
-    let inView = false;
-    for (const item of message.content) {
-      if (!record(item)) continue;
-      if (!seenView && item.type === 'text' && typeof item.text === 'string' && item.text.startsWith('<chat>\n')) { inView = true; seenView = true; }
-      if (!inView) delete item.cache_control;
-      if (inView && typeof item.text === 'string' && item.text.includes('</chat>')) { delete item.cache_control; inView = false; }
-    }
+    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' };
   return payload;

package/src/checkpoint.ts

@@ -7,10 +7,8 @@ const exec = promisify(execFile);
 
 export async function checkpoint(directory: string) {
   const git = (args: string[]) => exec('git', ['-C', directory, ...args], { maxBuffer: 1_000_000 });
-  if (!existsSync(join(directory, '.git'))) {
-    await git(['init', '-q', '-b', 'main']);
-    atomicWrite(join(directory, '.gitignore'), '/runs/\n/memory.html\n/usage.jsonl\n*.tmp\n');
-  }
+  if (!existsSync(join(directory, '.git'))) await git(['init', '-q', '-b', 'main']);
+  if (!existsSync(join(directory, '.gitignore'))) atomicWrite(join(directory, '.gitignore'), '/runs/\n/memory.html\n/usage.jsonl\n*.tmp\n');
   await git(['add', '-A', '--', '.']);
   const status = await git(['diff', '--cached', '--name-only']);
   if (!status.stdout.trim()) return;

package/src/compactor.ts

@@ -5,12 +5,11 @@ import { COMPACT } from './prompts.ts';
 import { bytes, NODE, type Compressor } from './memory.ts';
 import { cachePayload, splitView } from './cache.ts';
 import { IMPORT_GUIDANCE } from './import/guidance.ts';
+import { DEFAULT_SETTINGS } from './settings.ts';
 
 export interface ModelChoice { provider: string; model: string; thinking: ThinkingLevel }
-const scaleBase = 'user: Keep work and personal memory separate; use a binary summary tree and inspect original messages before acting. talk: Implemented the append-only log with durable writes and a stable view. echo: Checked caching, chronological summaries, cancellation, and profile locks. user: Main agent uses Opus; compactor uses Sonnet at medium effort. work: Worker completed the parser; tests cover invalid records and repeated imports. talk: The browser opens original messages, preserving dates and sources.';
-export const SCALE = scaleBase.padEnd(NODE, '.').slice(0, NODE);
-/** The model is asked for 512 bytes; a small overshoot costs less view space than a retry costs money. */
-export const ACCEPTED = NODE * 1.25;
+/** A realistic summary line of exactly NODE bytes, on a topic no real chat shares so its wording can't leak into summaries. */
+export const SCALE = 'user: Plan the Lisbon trip for 14-18 May: four adults, one in a wheelchair, 2400 EUR budget, no flights before 09:00. talk: Suggested Baixa; skip tram 28 (not step-free). tool: searched TAP, easyJet fares; echo: TAP TP1205 at 08:40 (too early), easyJet U27652 at 11:15 is 162 EUR each. user: "Book easyJet; step-free rooms matter more than a view." work: [4c1e9a20] Casa do Rio has two step-free rooms at 138 EUR/night, free cancellation to 10 May, held to 2 May. talk: Asked about a Sintra day trip, unanswered.';
 const WARM_MS = 4 * 60_000; // Anthropic's short cache lives 5 minutes from its last use.
 
 /** Parallel calls can't read a cache entry that isn't written yet, so one call primes a cold prefix and the rest wait until it answers. */
@@ -38,8 +37,9 @@ function primeFirst() {
     };
   };
 }
+/** The model is asked for 512 bytes; `accepted` is the longest line kept without a retry (the profile's summary size tolerance). */
 export function createCompressor(registry: ModelRegistry, choice: () => ModelChoice,
-  onUsage: (message: AssistantMessage) => void = () => {}): Compressor {
+  onUsage: (message: AssistantMessage) => void = () => {}, accepted = () => DEFAULT_SETTINGS.summaryAcceptBytes): Compressor {
   const gate = primeFirst();
   return async (input, signal) => {
     const selected = choice();
@@ -67,7 +67,8 @@ export function createCompressor(registry: ModelRegistry, choice: () => ModelCho
       const line = reply.content.filter(c => c.type === 'text').map(c => c.text).join('').trim();
       if (!line) throw new Error('Compactor returned no text.');
       tries.push(line);
-      if (bytes(line) <= ACCEPTED) break;
+      // A merge of two short lines can come back nearly as big as both, so a line must also shrink what it replaces.
+      if (bytes(line) <= accepted() && bytes(line) < bytes(input.source)) break;
       messages.push(reply);
       const cut = Buffer.from(line).subarray(0, NODE).toString('utf8').replace(/\uFFFD$/, '');
       messages.push({ role: 'user', content: `That line is ${bytes(line)} bytes; the limit is 512. It must end where it is cut here:\n${cut}| ← LIMIT`, timestamp: Date.now() });

package/src/import/multi-select.ts

@@ -44,8 +44,8 @@ export class MultiSelect implements Component, Focusable {
     if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) return this.finish(undefined);
     if (matchesKey(data, 'return')) {
       if (this.selected.size) return this.finish([...this.selected].sort((a, b) => a - b));
-      this.error = 'Select at least one item with Space.';
-    } else if (matchesKey(data, 'space')) {
+      this.error = 'Select at least one item with Tab.';
+    } else if (matchesKey(data, 'tab') || (matchesKey(data, 'space') && !this.filter.getValue())) {
       const index = this.visible[this.cursor];
       if (index !== undefined) { if (this.selected.has(index)) this.selected.delete(index); else this.selected.add(index); }
     } else if (matchesKey(data, 'ctrl+a')) this.visible.forEach(i => this.selected.add(i));
@@ -82,7 +82,7 @@ export class MultiSelect implements Component, Focusable {
     if (!this.visible.length) lines.push('No matches. Ctrl+U clears the filter.');
     lines.push(color('dim', `${this.visible.length ? this.cursor + 1 : 0}/${this.visible.length} matching · ${this.labels.length} total`));
     lines.push(color(this.error ? 'error' : 'dim', this.error || '↑↓ move · PgUp/PgDn page · Home/End jump'));
-    lines.push(color('dim', 'Space toggle · Enter continue · Esc cancel'));
+    lines.push(color('dim', 'Tab toggle · Space toggle (empty filter) · Enter continue · Esc cancel'));
     lines.push(color('dim', 'Ctrl+A select matches · Ctrl+D clear matches'));
     return lines.map(line => truncateToWidth(line, width));
   }

package/src/import/sources.ts

@@ -22,9 +22,12 @@ const codexSubagent = (metadata: Record<string, unknown>) => metadata.source ===
   || record(metadata.source) && 'subagent' in metadata.source;
 const missingSource = (error: unknown) => record(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
 const missingWarning = (file: string) => `${file}: source file is no longer available; conversation skipped. Rescan to retry if it returns.`;
+const zoneless = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)$/;
+// A time without a zone is UTC, not the machine's zone. A number above 1e11 is milliseconds (1e11 seconds is the year 5138).
 export function timestamp(value: unknown, fallback: string): string {
-  const time = typeof value === 'number' ? value * 1000 : typeof value === 'string' ? Date.parse(value) : NaN;
-  return Number.isFinite(time) ? new Date(time).toISOString() : fallback;
+  const time = typeof value === 'number' ? (value > 1e11 ? value : value * 1000) : typeof value === 'string' ? Date.parse(value.trim().replace(zoneless, '$1T$2Z')) : NaN;
+  const date = new Date(time);
+  return Number.isNaN(date.getTime()) ? fallback : date.toISOString();
 }
 function text(value: unknown): string {
   if (typeof value === 'string') return value;
@@ -188,10 +191,19 @@ async function claudeProject(folder: string, name: string, signal?: AbortSignal)
 function frontmatter(content: string) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(content);
   const fields = new Map<string, string>();
-  for (const line of match ? match[1].split(/\r?\n/) : []) {
+  const lines = match ? match[1].split(/\r?\n/) : [];
+  for (let i = 0; i < lines.length; i++) {
     // Newer files nest type/modified under `metadata:`; the first occurrence of each key wins.
-    const m = /^\s*([A-Za-z]+):\s*(.+?)\s*$/.exec(line);
-    if (m && !fields.has(m[1])) fields.set(m[1], unquote(m[2]));
+    const m = /^(\s*)([A-Za-z]+):\s*(.+?)\s*$/.exec(lines[i]);
+    if (!m) continue;
+    let value: string;
+    if (/^[>|][+-]?\d?$/.test(m[3])) { // A folded or literal block is the indented lines after the key.
+      let end = i + 1;
+      while (end < lines.length && (!lines[end].trim() || lines[end].search(/\S/) > m[1].length)) end++;
+      value = lines.slice(i + 1, end).map(line => line.trim()).join(m[3].startsWith('>') ? ' ' : '\n').trim();
+      i = end - 1;
+    } else value = unquote(m[3]);
+    if (value && !fields.has(m[2])) fields.set(m[2], value);
   }
   return { fields, body: match ? content.slice(match[0].length) : content };
 }
@@ -233,16 +245,19 @@ export async function readConversation(c: Conversation, signal?: AbortSignal): P
     const nodes = Object.entries(mapping).filter((pair): pair is [string, Record<string, unknown>] => record(pair[1]));
     nodes.sort((a, b) => timestamp(record(a[1].message) ? a[1].message.create_time : undefined, c.date)
       .localeCompare(timestamp(record(b[1].message) ? b[1].message.create_time : undefined, c.date)));
-    const ordered: typeof nodes = [], visited = new Set<string>(), visiting = new Set<string>();
-    const visit = (key: string, node: Record<string, unknown>) => {
-      if (visited.has(key)) return;
-      if (visiting.has(key)) throw new Error(`${c.title}: cycle in ChatGPT conversation mapping.`);
-      visiting.add(key);
-      const parent = typeof node.parent === 'string' ? mapping[node.parent] : undefined;
-      if (typeof node.parent === 'string' && record(parent)) visit(node.parent, parent);
-      visiting.delete(key); visited.add(key); ordered.push([key, node]);
-    };
-    for (const [key, node] of nodes) visit(key, node);
+    const ordered: typeof nodes = [], visited = new Set<string>();
+    for (const first of nodes) {
+      const chain: typeof nodes = [], inChain = new Set<string>();
+      let link: (typeof nodes)[number] | undefined = first;
+      while (link && !visited.has(link[0])) {
+        const [key, node]: (typeof nodes)[number] = link;
+        if (inChain.has(key)) throw new Error(`${c.title}: cycle in ChatGPT conversation mapping.`);
+        inChain.add(key); chain.push(link);
+        const parent = typeof node.parent === 'string' ? mapping[node.parent] : undefined;
+        link = typeof node.parent === 'string' && record(parent) ? [node.parent, parent] : undefined;
+      }
+      for (const done of chain.reverse()) { visited.add(done[0]); ordered.push(done); }
+    }
     const selected = new Set<string>();
     let cursor = string(c.exported?.current_node);
     const hasSelectedBranch = !!cursor;