billion-context-pi 0.1.55 → 0.1.56-pr.266.96

package/README.md

@@ -22,7 +22,7 @@ The model decides <em>when</em> and <em>what</em> to compress — not a hard lim
 
 ---
 
-> **Host support:** this plugin is for **Pi**. It does **not** support **OMP (oh-my-pi)** — on an OMP host it refuses to run. OMP users: use [billion-context](https://github.com/ranxianglei/billion-context) instead (`bili omp`). Details: [docs/omp.md](./docs/omp.md).
+> **Host support:** this plugin is for **Pi**. It does **not** support **OMP (oh-my-pi)** — on an OMP host it refuses to run. OMP users: use [billion-context](https://github.com/ranxianglei/billion-context) instead (`bili omp`, built-in plugin). Full client → package table: see [Which do I need?](#which-do-i-need); OMP details: [docs/omp.md](./docs/omp.md).
 
 ## Why?
 
@@ -39,6 +39,19 @@ This means:
 1. **A single session handles enormous workloads.** Per simulation tests of the three-tier architecture (see [opencode-acp](https://github.com/ranxianglei/opencode-acp)), one session can process on the order of 10–60 billion cumulative tokens — while retaining long-term memory of distant key information (paths, decisions, signatures). You can work in the **same session for months** without outgrowing the context.
 2. **Context stays lean over the long run.** In practice context typically holds under ~150K tokens (opencode-acp keeps it under ~200K), so compared to traditional compaction that lets context balloon toward 1M, **a single session costs roughly 5× less in tokens**.
 
+## Which do I need?
+
+Pick by your client:
+
+| Client | Use |
+|---|---|
+| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) (in-process extension) |
+| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) (in-process extension) |
+| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) |
+| **everything else** | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili <client>` (launcher, preferred) or `/bili/` prefix |
+
+> Why OMP can't use this in-process extension, and what happens if you try anyway: see [Host support](#host-support) and [docs/omp.md](./docs/omp.md).
+
 ## Install
 
 ```bash
@@ -76,7 +89,7 @@ This has two practical implications:
 
 ## Host support
 
-billion-context-pi is built for the **Pi** coding agent (`@earendil-works/pi-coding-agent`) and detects the host at session start:
+billion-context-pi is built for the **Pi** coding agent (`@earendil-works/pi-coding-agent`) and detects the host at session start — the full client → package table lives in [Which do I need?](#which-do-i-need):
 
 - **Pi** — fully supported.
 - **OMP (`can1357/oh-my-pi`)** — **not supported.** OMP's in-process session API diverges from Pi's, so the compression refs the extension injects can drift out of sync with the session's real refs and `compress` calls fail with `does not exist in this session` (issue [#234](https://github.com/ranxianglei/billion-context-pi/issues/234)). On OMP the extension now **refuses service**: it prints a warning, disables the ACP tools, and leaves the host's own context handling untouched.
@@ -120,7 +133,7 @@ Worker runs on Pi's full default toolset - no `--tools` allowlist is applied, so
 
 The full delegate result is saved to a file (`/tmp/acp-delegate/<runId>.out`); the tool result and injected notification carry only the **task title + file path** (no preview) - use `read` for the details. This keeps the parent context lean.
 
-- **Interactive (TUI) & RPC modes**: `async:true` (default) runs the child in the background; a short completion notification is injected into the chat when it finishes.
+- **Interactive (TUI) & RPC modes**: `async:true` (default) runs the child in the background; a short completion notification is injected into the chat when it finishes — **unless the model already read the result file after the run finished** (detected via the `read` tool or a bash command referencing the file), in which case the notification is skipped: the model already has the result, so re-injecting it would only waste context. Set `delegate: { notifyIfRead: "always" }` in `acp.json` to restore the always-inject behavior.
 - **Print / JSON modes** (`pi -p`, SDK): `async:true` auto-downgrades to **synchronous** — the result returns as the tool result in the same turn (the parent exits after one turn, so background injection would be lost).
 - **Failures are loud, never silent.** A run that fails (nonzero exit, spawn error, watchdog timeout) injects a `FAILED ⚠️` notification carrying a short error excerpt, so a failed delegate cannot hide among sibling completions. If a notification cannot be delivered at all, a recovery notice is attached to the next delegate notification or the next `acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel` tool result — a dispatched run's failure always reaches the model before it wraps up.
 
@@ -196,6 +209,37 @@ billion-context protects three categories of content from compression:
 2. **Soft recent-zone** — the last N messages (default 5) and last ~5K tokens are soft-protected so the model keeps its working set. Tool results from `decompress`, `search_context`, `read`, and `bash` are **excluded** from this zone: they're large and meant to be compressible once consumed, so they don't eat the protected budget.
 3. **Last user message** — always protected (user intent must survive).
 
+## Session storage & migration
+
+billion-context-pi persists each session's compression state in a **sidecar file** next to the session transcript. Every session lives as two files in Pi's sessions directory (`~/.pi/agent/sessions/`):
+
+| File | Contents |
+|------|----------|
+| `<id>.jsonl` | The conversation transcript (messages, tool calls) |
+| `<id>.jsonl.acp.json` | The ACP compression state (compressed blocks, message refs, nudge + stats) |
+
+The `.acp.json` sidecar is what holds your compressed blocks. Without it, the session runs on its full raw history until ACP compresses again.
+
+### Migrating a session (cross-machine copy / backup-restore)
+
+Pi's built-in export/import moves only the **transcript**, not the ACP state. Two things are lost:
+
+1. **The `.acp.json` sidecar is not carried.** An imported session therefore has *no* compressed blocks: every LLM call resends the entire raw history until the nudge re-compresses it — a one-time full re-cache cost plus context bloat back to original size. Very long sessions can approach or exceed the model window before re-compression kicks in (Pi's native compaction is disabled while this plugin is active, so ACP is the only context manager).
+2. **Export drops the `parentSession` header.** Clone/fork child sessions rely on that header field to inherit their parent's compression state; once exported, the link is gone even if the parent's files still exist on the target machine.
+
+**To migrate a session with its compression state intact, copy both files together** (they share the same base name):
+
+```bash
+# copy the pair
+cp <id>.jsonl <id>.jsonl.acp.json  <dest>/
+# ... or back up / restore the whole directory
+cp -r ~/.pi/agent/sessions  <backup>/pi-sessions
+```
+
+Restore them next to each other on the target machine. For clone/fork children, also bring the parent's pair so `parentSession` resolves.
+
+> A permanent fix — the host carrying the sidecar through import/export and preserving `parentSession` — belongs upstream in pi-coding-agent and is tracked in issue [#299](https://github.com/ranxianglei/billion-context-pi/issues/299). Until it lands, copy the pair manually.
+
 ## Built on acp-kernel
 
 The compression engine is [`acp-kernel`](https://github.com/ranxianglei/acp-kernel) — a platform-agnostic, MIT-licensed library with 208 tests. It's bundled inline into `dist/index.js`, so there are zero runtime dependencies.

package/README.zh-CN.md

@@ -20,7 +20,7 @@
 
 ---
 
-> **宿主支持:** 本插件面向 **Pi**。它**不支持 OMP(oh-my-pi)** —— 在 OMP 宿主上会拒绝运行。OMP 用户请改用 [billion-context](https://github.com/ranxianglei/billion-context)(`bili omp`)。详细说明:[docs/omp.zh-CN.md](./docs/omp.zh-CN.md)。
+> **宿主支持:** 本插件面向 **Pi**。它**不支持 OMP(oh-my-pi)** —— 在 OMP 宿主上会拒绝运行。OMP 用户请直接改用 [billion-context](https://github.com/ranxianglei/billion-context)(启动命令 bili omp);其他客户端的完整对照见[该选哪个?](#该选哪个)。OMP 详细说明:[docs/omp.zh-CN.md](./docs/omp.zh-CN.md)。
 
 ## 为什么选择 billion-context
 
@@ -38,6 +38,19 @@
 1. **一个会话即可支撑海量工作。** 根据三级压缩架构的模拟测试(见 [opencode-acp](https://github.com/ranxianglei/opencode-acp)),单会话累计可处理约 100 亿至 600 亿 token —— 同时对遥远的关键信息(路径、决策、签名)保持长久记忆。用户可以在**同一个会话里连续工作几个月**,而无需因为上下文膨胀而开新会话丢上下文。
 2. **上下文长期保持精简。** 实际运行中上下文通常稳定在 15 万 token 以下(opencode-acp 实测维持在 20 万以下),相比传统压缩方案动辄撑到 100 万上下文,**单会话累计可节省近 5 倍的 token 费用**。
 
+## 该选哪个?
+
+按客户端选:
+
+| 客户端 | 用这个 |
+|---|---|
+| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) |
+| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp)(进程内扩展) |
+| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件) |
+| **其余所有** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili <client>`(启动器,优先)或 `/bili/` 前缀 |
+
+> 为什么 OMP 不能用本进程内扩展、以及强行使用的后果:见下文[宿主支持](#宿主支持)与 [docs/omp.zh-CN.md](./docs/omp.zh-CN.md)。
+
 ## 安装
 
 ```bash
@@ -75,7 +88,7 @@ billion-context 通过拦截 Pi 的 `context` 事件接管上下文管理。**Pi
 
 ## 宿主支持
 
-billion-context-pi 面向 **Pi** 编码代理(`@earendil-works/pi-coding-agent`)构建,并在会话开始时检测宿主:
+billion-context-pi 面向 **Pi** 编码代理(`@earendil-works/pi-coding-agent`)构建,并在会话开始时检测宿主——完整的「客户端 → 包」对照表见[该选哪个?](#该选哪个):
 
 - **Pi** — 完全支持。
 - **OMP(`can1357/oh-my-pi`)** — **不支持。** OMP 的进程内会话 API 与 Pi 不同,扩展注入的压缩引用可能与会话的真实引用漂移失步,导致 `compress` 调用失败,报错 `does not exist in this session`(issue [#234](https://github.com/ranxianglei/billion-context-pi/issues/234))。在 OMP 上,扩展现在会**拒绝服务**:打印警告、禁用 ACP 工具,并保持宿主自身的上下文处理不受影响。
@@ -196,6 +209,37 @@ billion-context 保护三类内容不被压缩:
 2. **软近期区** — 最后 N 条消息(默认 5)和最后约 5K token 被软保护,让模型保留工作集。来自 `decompress`、`search_context`、`read`、`bash` 的工具结果被**排除**出此区:它们体量大、消费后就该能压缩,所以不该占用保护预算。
 3. **最后一条用户消息** — 始终保护(用户意图必须存活)。
 
+## 会话存储与迁移
+
+billion-context-pi 把每个会话的压缩状态持久化在会话转录文件旁边的一个**旁挂(sidecar)文件**里。每个会话在 Pi 的会话目录(`~/.pi/agent/sessions/`)下都有两个文件:
+
+| 文件 | 内容 |
+|------|------|
+| `<id>.jsonl` | 会话转录(消息、工具调用) |
+| `<id>.jsonl.acp.json` | ACP 压缩状态(压缩块、消息引用、nudge 与统计) |
+
+`.acp.json` 旁挂文件承载了你的压缩块。没有它,会话就会以完整原始历史运行,直到 ACP 再次压缩。
+
+### 迁移会话(跨机器拷贝 / 备份恢复)
+
+Pi 内置的导出/导入只搬运**转录**,不搬 ACP 状态。会丢失两样东西:
+
+1. **`.acp.json` 旁挂文件不会被携带。** 因此导入后的会话*没有任何*压缩块:每次 LLM 调用都会重发完整原始历史,直到 nudge 重新压缩 —— 一次性全量重缓存成本 + 上下文膨胀回原始大小。超长会话可能在重新压缩生效前逼近甚至超出模型窗口(本插件激活时 Pi 的原生 compaction 被禁用,ACP 是唯一的上下文管理者)。
+2. **导出会丢弃 `parentSession` 头。** clone/fork 子会话依赖这个头字段来继承父会话的压缩状态;一旦导出,这条链接就断了 —— 即使目标机器上父会话的文件仍然存在。
+
+**要带着完整压缩状态迁移会话,请把两个文件一起拷贝**(它们共享同一基础名):
+
+```bash
+# 成对拷贝
+cp <id>.jsonl <id>.jsonl.acp.json  <目标目录>/
+# ... 或整体备份 / 恢复整个目录
+cp -r ~/.pi/agent/sessions  <备份>/pi-sessions
+```
+
+在目标机器上把它们放回彼此相邻的位置。对 clone/fork 子会话,还要带上父会话的那一对,以便 `parentSession` 能解析。
+
+> 根治方案 —— 让宿主在 import/export 时一并携带旁挂文件并保留 `parentSession` —— 属于上游 pi-coding-agent,已在 issue [#299](https://github.com/ranxianglei/billion-context-pi/issues/299) 跟踪。落地前请手动成对拷贝。
+
 ## 基于 acp-kernel
 
 压缩引擎是 [`acp-kernel`](https://github.com/ranxianglei/acp-kernel) — 平台无关、MIT 许可的库,有 208 个测试。它被内联打包进 `dist/index.js`,因此零运行时依赖。

package/dist/config.d.ts

@@ -1,5 +1,21 @@
 import { type Config, type Prompts } from "acp-kernel";
 import type { ThrottleRetryConfig } from "./throttle-retry.js";
+/** Per-role delegate defaults. Lets long-lived automation pin a cheaper or
+ *  more capable model and a thinking level per delegate role, so the main
+ *  agent doesn't have to fill them in on every `acp_delegate()` call. */
+export interface DelegateRoleConfig {
+    /** Default model for this role, as `"provider/id"`. Resolution priority:
+     *  per-call `model` > this role default > parent agent's current model. A
+     *  value that isn't a valid `"provider/id"` is ignored (treated as unset).
+     *  If the configured model doesn't exist in the live registry, the child
+     *  falls back to the parent model and a warning is logged — it never fails. */
+    model?: string;
+    /** Default thinking level for this role: one of off|minimal|low|medium|
+     *  high|xhigh|max. Resolution priority: per-call `thinkingLevel` > this role
+     *  default > global `delegate.thinkingLevel` > Pi's own default. An invalid
+     *  value is ignored with a warning (never fails). */
+    thinkingLevel?: string;
+}
 /** Delegate sub-agent configuration. */
 export interface DelegateConfig {
     /** Enable acp_delegate tools (delegate/wait/cancel) and their system-prompt
@@ -12,7 +28,68 @@ export interface DelegateConfig {
      *  "merged" — delegate token usage folded into the tool-result usage field,
      *  counted as part of the main session totals. */
     displayUsage?: "merged" | "separate";
+    /** Maximum acp_delegate nesting depth. Default: 2 (main → child → grandchild;
+     *  the grandchild cannot delegate further). Set 1 to forbid nested delegation
+     *  (orchestrator → leaf workers only). The resolved value is propagated to
+     *  child processes via PI_ACP_DELEGATE_MAX_DEPTH so the cap follows the whole
+     *  delegation tree, even when a child loads a different project acp.json. */
+    maxDepth?: number;
+    /** Hard timeout for synchronous delegates (async=false, or async auto-downgraded
+     *  on one-shot hosts), in minutes. Default: 5. 0 or null disables the timeout
+     *  (the run blocks until the child exits or the tool call is cancelled). */
+    syncTimeoutMinutes?: number | null;
+    /** Idle watchdog for async delegates: kill when no output arrives for this many
+     *  minutes. Default: 5. This is the main defense against a stuck child holding
+     *  its stdout fd open, so disabling it (0/null) logs a warning — use
+     *  acp_delegate_cancel as the manual escape hatch. */
+    idleTimeoutMinutes?: number | null;
+    /** Hard time limit for async delegates, in minutes. Default: 30. 0 or null
+     *  disables the limit. */
+    asyncTimeoutMinutes?: number | null;
+    /** Cap on how many background (async) delegate processes run at once.
+     *  `1` forces strict serial execution; `N` allows up to N in parallel;
+     *  omitted means unlimited (existing behavior). Extra launches are queued and
+     *  start automatically as slots free. Invalid values (non-integer, <1) fall
+     *  back to unlimited with a warning. Env `PI_ACP_DELEGATE_MAX_CONCURRENT`
+     *  overrides this. See #294. */
+    maxConcurrent?: number;
+    /** Global default thinking level applied to every delegate when neither the
+     *  per-call `thinkingLevel` nor the role's own `thinkingLevel` is set. One of
+     *  off|minimal|low|medium|high|xhigh|max. When unset at all levels, no
+     *  `--thinking` flag is passed and each child uses Pi's own default. */
+    thinkingLevel?: string;
+    /** Per-role defaults keyed by role name (reviewer/researcher/worker/planner/
+     *  oracle, or any custom role). See DelegateRoleConfig. Only affects roles
+     *  that are named here; other roles inherit the parent model + Pi defaults. */
+    agents?: Record<string, DelegateRoleConfig>;
+    /** What happens to the completion notification when the model has already
+     *  read the delegate's result file after the run finished.
+     *  "skip" (default) — the notification is not injected; the model already
+     *  saw the result, so re-injecting it would only waste context.
+     *  "always" — always inject the notification (previous behavior). */
+    notifyIfRead?: "skip" | "always";
+}
+/** Resolved delegate policy: what actually takes effect after merging acp.json,
+ *  env overrides and defaults. Timeout fields are milliseconds; null means the
+ *  corresponding timeout/watchdog is disabled. */
+export interface DelegatePolicy {
+    enabled: boolean;
+    displayUsage: "merged" | "separate";
+    maxDepth: number;
+    syncTimeoutMs: number | null;
+    idleMs: number | null;
+    asyncTimeoutMs: number | null;
+    /** Resolved cap on concurrent background delegates; Infinity = unlimited. */
+    maxConcurrent: number;
+    /** Global default thinking level (undefined when unset). */
+    thinkingLevel?: string;
+    /** Per-role defaults keyed by role name (undefined when unset). */
+    agents?: Record<string, DelegateRoleConfig>;
+    /** Whether to suppress the completion notification when the model already
+     *  read the result file after the run finished. Always resolved ("skip" default). */
+    notifyIfRead: "skip" | "always";
 }
+export declare const DEFAULT_DELEGATE_POLICY: DelegatePolicy;
 /** Compression tuning fields, shared by all three levels (global, provider,
  *  model). Percentage fields accept a ratio (0.75) or percent string ("75%").
  *  Resolution is per-field, deepest-wins (model > provider > global); an
@@ -117,11 +194,10 @@ export interface AdapterConfig {
 export declare const DEFAULT_TOOL_BASH_TIMEOUT = 60;
 export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 200000;
 /** Resolve delegate config from the adapter, handling the boolean shorthand
- *  and the legacy flat `displayUsage` alias. */
-export declare function resolveDelegate(adapter: AdapterConfig): {
-    enabled: boolean;
-    displayUsage: "merged" | "separate";
-};
+ *  and the legacy flat `displayUsage` alias. Precedence: env > acp.json >
+ *  default (same convention as ACP_MODEL_CONTEXT_LIMIT). Invalid values fall
+ *  back to the default with a logged warning — they never fail the session. */
+export declare function resolveDelegate(adapter: AdapterConfig): DelegatePolicy;
 /** Per-field deepest-wins merge of the three compression levels (global →
  *  provider → model). An undefined field at a deeper level does NOT clear a
  *  value set at a shallower level — only a defined value overrides. */

package/dist/delegate-tool.d.ts

@@ -1,15 +1,21 @@
 import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import { Type, type Static } from "typebox";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type DelegatePolicy, type DelegateRoleConfig } from "./config.js";
 import { type Usage } from "./delegate-events.js";
+export declare const OUT_DIR: string;
 export declare function delegateStdinText(resumeFrom: boolean, task: string | undefined): string;
 export declare function delegateSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions;
+/** Child process env for a nested delegate: depth increments by one, and the
+ *  resolved maxDepth rides along so the cap binds the whole delegation tree
+ *  even when the child loads a different project acp.json. */
+export declare function delegateChildEnv(parentDepth: number, maxDepth: number): NodeJS.ProcessEnv;
 /** Resolve the pi CLI entry for delegate child processes.
  *  argv[1] is only the pi CLI under a CLI host; embedded hosts (e.g. pi-web)
  *  run the SDK inside another node process, so probe instead. Non-pi hosts
  *  (omp) keep argv[1] untouched. */
 export declare function resolvePiCliEntry(argv1: string, env?: NodeJS.ProcessEnv, piHost?: boolean): string;
-export type RunStatus = "running" | "completed" | "failed" | "cancelled";
+export type RunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
 interface DelegateRun {
     runId: string;
     agent: string;
@@ -49,11 +55,55 @@ interface DelegateRun {
     /** True while the run sits in the coalescing notification queue (scheduled
      *  for the next batched flush, not yet delivered). */
     notifyQueued?: boolean;
+    /** When the model successfully read this run's result file (read tool, or a
+     *  bash command referencing it). A read at/after finishedAt means the model
+     *  already saw the final result — the completion notification is then
+     *  suppressed (notifyIfRead: "skip"). */
+    readAt?: number;
+    /** True when the completion notification was suppressed because the model
+     *  had already read the result file. Treated as delivered (injected=true)
+     *  so wait/recovery never re-surface the result. */
+    readSuppressed?: boolean;
 }
 export declare function addDelegateUsage(u: Usage): void;
 export declare function getDelegateUsage(): Usage | undefined;
 export declare function resetDelegateUsage(): void;
 export declare function setDelegateDisplayUsage(mode: "merged" | "separate"): void;
+export declare function setDelegatePolicy(policy: DelegatePolicy): void;
+export declare class ConcurrencyGate {
+    private active;
+    private queue;
+    private readonly capacityOf;
+    constructor(capacityOf: () => number);
+    private get capacity();
+    get unlimited(): boolean;
+    get activeCount(): number;
+    get queuedCount(): number;
+    /** Start `launch` immediately when a slot is free and nothing waits ahead;
+     *  otherwise hold it in the FIFO queue. True when it started right away. */
+    launchOrQueue(runId: string, launch: () => void): boolean;
+    cancelQueued(runId: string): boolean;
+    /** A live child hit a terminal state: free its slot, then start waiting
+     *  launches FIFO (skipping any cancelled while queued). */
+    release(): void;
+}
+export declare function setDelegateDefaults(d: {
+    thinkingLevel?: string;
+    agents?: Record<string, DelegateRoleConfig>;
+} | undefined): void;
+export declare function resetDelegateDefaults(): void;
+declare const VALID_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export declare function isValidThinkingLevel(v: unknown): v is (typeof VALID_THINKING_LEVELS)[number];
+export declare function setDelegateNotifyIfRead(mode: "skip" | "always"): void;
+/** Mark the run whose result file the model just read (via the `read` tool).
+ *  Returns true when a run matched. A read of the final result file after the
+ *  run finished means the model already saw the result — the completion
+ *  notification is then suppressed (notifyIfRead: "skip"). */
+export declare function markDelegateResultRead(filePath: string): boolean;
+/** Mark runs referenced by a bash command (e.g. `cat <result file>`).
+ *  Matches runIds appearing anywhere in the command string; only existing
+ *  runs are affected, so task text that merely contains "del_..." is inert. */
+export declare function markDelegateRunReadByCommand(command: string): boolean;
 /** Snapshot of currently-running delegate runs, for the TUI status widget. */
 export declare function runningRunsSnapshot(): {
     runId: string;
@@ -61,6 +111,31 @@ export declare function runningRunsSnapshot(): {
     task: string;
     startedAt: number;
 }[];
+export interface FleetRunView {
+    runId: string;
+    agent: string;
+    task: string;
+    cwd: string;
+    startedAt: number;
+    finishedAt?: number;
+    status: RunStatus;
+    exitLabel: string;
+    timedOut?: string;
+    resumedFrom?: string;
+    /** Streamed reply text (always retained, even for cancelled runs). */
+    replyFile: string;
+    /** Live tool-activity log (async json-stream runs only). */
+    activityFile?: string;
+    sessionFile?: string;
+    usage?: Usage;
+}
+/** Running first (oldest spawn on top), then recently finished (newest first,
+ *  capped) — the order the fleet inspector list shows. */
+export declare function orderRunsForFleet(all: DelegateRun[]): DelegateRun[];
+/** Display-safe snapshot of every delegate run known this session, for the
+ *  fleet inspector (/acp-fleet). In-memory only: runs from previous pi
+ *  processes are not listed (their files remain under OUT_DIR). */
+export declare function fleetRunsSnapshot(): FleetRunView[];
 /** Minimal writable surface accepted by makeEventApplier — real WriteStreams
  *  in production, in-memory collectors in tests. */
 export interface EventApplierWriters {
@@ -102,6 +177,7 @@ declare const DelegateParams: Type.TObject<{
     resumeFrom: Type.TOptional<Type.TString>;
     cwd: Type.TOptional<Type.TString>;
     model: Type.TOptional<Type.TString>;
+    thinkingLevel: Type.TOptional<Type.TString>;
     async: Type.TOptional<Type.TBoolean>;
     showThinking: Type.TOptional<Type.TBoolean>;
 }>;
@@ -164,6 +240,7 @@ export declare function formatBatchRunSection(run: DelegateRun): string;
  *  in which case the caller delivers the full payload via formatRunResult(). */
 export declare function injectedWaitMessage(run: {
     injected?: boolean;
+    readSuppressed?: boolean;
     result?: {
         file: string;
     };
@@ -196,10 +273,30 @@ export declare function buildChildArgs(args: DelegateArgs, rolePrompt: string, c
     useJsonStream: boolean;
     sessionFile: string | null;
 }>;
+/** Model-facing summary of the ACTIVE async watchdog limits — built from the
+ *  resolved policy so it stays truthful when timeouts are customized or
+ *  disabled via acp.json/env. */
+export declare function asyncWatchdogDescription(): string;
 /** Watchdog/EOF finalize arrives with code === null (the child was killed or
  *  never exited). If a result was delivered (non-empty reply or stderr), the
  *  run counts as completed (0); otherwise it stays null = genuine failure. */
 export declare function effectiveExitCode(code: number | null, output: string, stderr: string): number | null;
+/** Pure read-after-finish predicate: should the completion notification be
+ *  suppressed because the model already read the final result file? Only a
+ *  read at/after finishedAt counts — a read while the run was still in flight
+ *  (readAt < finishedAt) saw partial output, so the notification still goes
+ *  out. Callers additionally gate on run.status === "completed": a FAILED
+ *  run's file holds only partial output with no failure marker, so the model
+ *  cannot tell it failed from the file — failure notifications are never
+ *  suppressed (failures are loud). */
+export declare function shouldSuppressRead(run: {
+    readAt?: number;
+    finishedAt?: number;
+}, mode: "skip" | "always"): boolean;
+/** Suppress the completion notification for a run the model already read:
+ *  mark it delivered (so wait/recovery/flush never re-surface the result),
+ *  account its usage in separate mode, and log the skip. Idempotent. */
+export declare function applyReadSuppression(run: DelegateRun, runId: string): void;
 /** status (set by finalize from the effective exit code) is the authority for
  *  the FAILED/completed decision; the raw code is diagnostic display only
  *  ("exit ?"), so the notification can never disagree with run.status. */

package/dist/delegate-watchdog.d.ts

@@ -1,8 +1,10 @@
 import type { Readable } from "node:stream";
 export interface WatchdogOptions {
     eofGraceMs: number;
-    idleMs: number;
-    timeoutMs: number;
+    /** Kill when no output for this long. 0/null disables the idle timer. */
+    idleMs?: number | null;
+    /** Hard time limit. 0/null disables the limit timer. */
+    timeoutMs?: number | null;
     killGraceMs: number;
 }
 export interface WatchdogHooks {

package/dist/fleet-inspector.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type FleetRunView } from "./delegate-tool.js";
+export interface InspectorTheme {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+}
+export declare function formatDuration(ms: number): string;
+export declare function statusIcon(status: FleetRunView["status"]): string;
+export declare function usageSummary(usage: FleetRunView["usage"]): string | undefined;
+export interface ListRow {
+    run: FleetRunView;
+    label: string;
+    detail: string;
+}
+export declare function buildListRows(runs: FleetRunView[], now: number): ListRow[];
+/** Last maxBytes of a file as utf8; a partial leading line is dropped so the
+ *  tail always starts on a line boundary. Missing/unreadable → "". */
+export declare function readTailSync(file: string | undefined, maxBytes: number): string;
+export declare function renderListView(rows: ListRow[], selIdx: number, theme: InspectorTheme, width: number): string[];
+export declare function renderTranscriptView(run: FleetRunView, tail: string, now: number, theme: InspectorTheme, width: number): string[];
+/** Plain-text snapshot for non-TUI hosts (rpc/print/json). */
+export declare function buildSnapshotText(runs: FleetRunView[], now: number): string;
+/** Open the live fleet inspector: TUI overlay in interactive mode, plain-text
+ *  snapshot notification elsewhere. Resolves when the user closes it. */
+export declare function openFleetInspector(ctx: ExtensionContext): Promise<void>;