pi-ultracode 0.3.0 → 0.3.2

package/README.md

@@ -1,433 +1,147 @@
-# Ultracode
+# pi-ultracode
 
-**Ultracode** 是 [Pi](https://github.com/badlogic/pi-mono) 的“全力执行”模式。它把 Pi 的 Agentic Loop 从单线程编码助手升级为能够运行子代理团队的编排器。
+Deterministic multi-agent workflows for [Pi](https://github.com/earendil-works/pi).
 
-启用 Ultracode 后，主代理会获得一条 `workflow` 工具，以及一段要求它主动使用该工具处理复杂任务的系统提示词。扩展加载时会先注册该工具，并在模型请求前的 input 与 `before_agent_start` 边界按模式校准 active tools；未启用或已暂停时，残留调用会被拒绝。每个子代理都运行在独立的内存 Pi 会话中，拥有标准编码工具、独立上下文，并可选择结构化输出、模型覆盖、Agent Type 和隔离的 git worktree。
+**English** · [简体中文](https://github.com/ekil1100/pi-ultracode/blob/main/README.zh-CN.md)
 
-Ultracode 保留 Pi 自身的核心循环、内存模型、工具系统、扩展 API 与会话格式。它是在 Pi 之上增加编排能力，而不是替换 Pi。
+`pi-ultracode` adds an opt-in high-effort mode to Pi. When a task benefits from delegation, the main agent can run a bounded JavaScript workflow with parallel subagents, isolated worktrees, structured output, durable resume, and live progress.
 
-## 功能
+The project combines the terminal-first agentic experience of [Claude Code](https://github.com/anthropics/claude-code) with the explicit workflow and structural-control ideas found in [Grok Build](https://github.com/xai-org/grok-build), while keeping Pi as the runtime.
 
-| 能力 | 说明 |
-| --- | --- |
-| `workflow` 工具 | 模型请求前按 Ultracode 状态校准；运行确定性的 JavaScript 编排脚本，并调用 `agent()`、`parallel()`、`pipeline()` 和 `workflow()`。 |
-| 独立子代理 | 每次 `agent()` 调用都会创建一条带标准编码工具的新 Pi 会话。 |
-| 并行执行 | `parallel()` 并发运行任务、保留输入顺序，并在启动前整批预留 agent slots。 |
-| 流水线 | `pipeline()` 让任务独立流经多个阶段，无需全局屏障。 |
-| 结构化输出 | 传入 JSON Schema，即可通过终止型 `structured_output` 工具获得经校验的对象。 |
-| Agent Type | 通过 `.pi/ultracode/agents/*.md` 定义角色提示词、工具白名单、模型和思考强度。 |
-| 模型覆盖 | 每次 `agent()` 调用都可指定模型模式，例如 `anthropic/claude-sonnet-4`。 |
-| Worktree 隔离 | 让写入型并行代理在临时 git worktree 中运行，并把改动安全合并回共享工作树。 |
-| 进度与详情 | 实时状态、实际模型/effort、turn/工具/token 统计，以及可流式展开的 TUI 任务详情浮层。 |
-| Ultracode 模式 | `/ultracode on` 启用主动编排提示词，并请求当前模型支持的最高思考强度。 |
-| 执行限制 | `maxAgents`（默认 128/上限 1024）、每进程且每 session/runsDir 最多 4 个活动 workflow、并发限制与嵌套深度限制。 |
-
-## 为什么使用工作流
-
-普通的多代理提示通常依赖模型临场决定如何分解与组合任务。Ultracode 采用另一种方式：**模型编写确定性的编排脚本，运行时执行该脚本**。
-
-这样可以清晰表达：
-
-- 哪些任务可以并行；
-- 哪些阶段依赖前一阶段的结果；
-- 哪些代理应返回结构化数据；
-- 何时需要共享上下文，何时需要隔离；
-- 何时停止额外探索；
-- 失败分支应如何降级。
-
-## 安装
+## Install
 
 ```bash
-pi install npm:pi-ultracode      # or: pi install /path/to/pi-ultracode
+pi install npm:pi-ultracode
 ```
 
-> **工具冲突：** pi-ultracode 注册名为 `workflow` 的工具，与 `pi-dynamic-workflows` 相同。pi-ultracode 是后者的严格超集，请先执行 `pi remove npm:pi-dynamic-workflows` 移除原型扩展。
-
-安装后在 Pi 中运行 `/reload`。
-
-开发仓库也可直接加载：
-
-```bash
-pi -e ./extensions/ultracode.ts
-```
-
-仓库中提供两个兼容入口：
-
-- `extensions/ultracode.ts`：推荐的 Pi 扩展入口；
-- `src/index.ts`：兼容入口，重新导出同一个扩展。
-
-## 快速开始
-
-在 Pi 中启用模式：
+Then reload Pi and toggle Ultracode on:
 
 ```text
-/ultracode on
+/reload
+/ultracode
 ```
 
-随后给出复杂任务，例如：
-
-```text
-Review the current branch, identify correctness and compatibility risks,
-fix the justified issues, and verify the result.
-```
-
-启用后，主代理会被要求在并行检视、迁移、审计或大范围修改明显有益时编写并运行工作流，而不是把所有工作塞进一个上下文。
-
-也可以在启动时启用：
+You can also enable it at startup:
 
 ```bash
 pi --ultracode
 ```
 
-工作流运行时会内联显示实时进度，例如：
-
-```text
-◆ ▶ audit_repo (4/7 done, 2 running) · 3 cached · 203k token (141k new, 62k replayed)
-  ✓ Survey 1/1
-    #1 ✓ repo inventory
-       gpt-5.6-sol • max · 15 turns · 42 tool uses · 141k token
-  ▶ Review 3/4 · 1 running
-    #2 ✓ auth module
-    #3 ✓ db layer
-    #4 ● payments module
-       claude-sonnet-4 • high · 6 turns · 18 tool uses · 52.3k+ token · partial
-  ▶ Verify 0/2 · 2 running
-```
-
-紧凑 token 数始终是 input + output；cache read/write 与成本只出现在任务详情中。主对话会折叠较早任务并明确显示省略数量，按 `Ctrl+O` 可展开全部，或用 `F6` 打开详情。按 `Esc` 可取消；运行中的子代理会被终止并显示为 cancelled，同时保留已有输出和部分用量。
-
-## 命令
+> `pi-ultracode` registers a tool named `workflow`. If `pi-dynamic-workflows` is installed, remove it first with `pi remove npm:pi-dynamic-workflows`.
 
-```text
-/ultracode             # toggle on/off
-/ultracode on          # enable orchestration mode
-/ultracode off         # disable the tool and restore the previous thinking level
-/ultracode status      # show current status
-/workflows             # open the interactive workflow detail overlay
-/workflows <runId>     # open one run directly (prefix accepted)
-/workflows abort       # abort active runs
-F6                     # open the workflow detail overlay
-```
+Current releases are tested with Pi 0.84.
 
-`/workflows` 与 `F6` 打开实时浮层。只有一个活动运行时会直接进入；多个活动运行会先显示选择器；没有活动运行时会打开最近完成的运行。宽终端使用任务/详情双栏，窄终端在列表与详情间切换。键盘操作：
+## Core features
 
-- `↑` / `↓` 选择运行或任务；`Enter` 打开；`Tab` 切换双栏焦点；`Esc` 返回或关闭；
-- `PageUp` / `PageDown` 滚动；`End` 恢复尾随；
-- `/` 搜索任务，`r` 只看运行中的任务，`a` 恢复全部，`p` 展开或收起任务 prompt。
+- **Opt-in high-effort mode** — requests the highest thinking level supported by the current model and restores the previous level when disabled.
+- **Explicit workflows** — compose work with `agent()`, `parallel()`, `pipeline()`, and nested `workflow()` calls.
+- **Independent subagents** — each agent gets its own Pi session, context, tools, model selection, and optional role.
+- **Parallel worktree isolation** — writing agents can work in temporary git worktrees before their patches are integrated.
+- **Structured output** — validate agent results with a bounded JSON Schema subset.
+- **Durable resume** — replay completed calls by stable structural identity without rerunning successful work.
+- **Live observability** — inspect status, model, thinking level, turns, tool use, token usage, retries, and transcripts in the TUI.
+- **Bounded execution** — lifetime agent admission, concurrency limits, strict JSON limits, worker watchdogs, and bounded cleanup.
 
-每次 `agent()` 调用都是一个可独立展开的任务。详情按时间交错显示 turn、assistant 正文、工具调用、重试、上下文压缩、错误与 thinking 持续时间；thinking 正文不会被捕获。正文 delta 只保存在有界内存中并以不超过每 100ms 一次的频率刷新，消息完成后改用 Markdown 渲染。
+## Quick start
 
-所有可视化和落盘内容都会移除终端控制序列并脱敏凭据。内存上限为每任务 1MiB / 5000 行、每工作流 32MiB；最终 transcript 上限为每任务 10MB（约 1MB 头部 + 9MB 尾部）、每工作流 128MB。最终清理后的 timeline 与 manifest 保存在 session 的 `ultracode-runs/` 目录，因而 `/reload` 后仍可浏览；不会复制系统 prompt、注入 skill、AGENTS 内容或父会话上下文。
-
-状态行会显示实际生效的思考强度，例如：
+Toggle Ultracode on and describe a substantial task:
 
 ```text
-ultracode: on · max
-ultracode: on · xhigh
-ultracode: on · high
-ultracode: on · off
-```
-
-Ultracode 请求的是**当前模型支持的最高强度**，不是固定标签。对支持 `max` 的模型（包括 GPT-5.6 Sol）使用 `max`；能力较低的模型由 Pi 正常钳制。对不认识 `max` 的旧版 Pi，Ultracode 会自动回退到 `xhigh`。
-
-显式覆盖始终优先：
-
-- 每次调用的模型后缀，例如 `model: "openai/gpt-5.6-sol:high"`；
-- Agent Type frontmatter 中的 `thinking:`；
-- 显式 `:off`、`:high`、`:xhigh` 或 `:max`。
-
-模型切换或手动降低强度时，只要 Ultracode 仍启用，它就会重新请求该模型的最高可用强度。关闭或退出时，会恢复启用前的会话强度与原始默认偏好。若当前模型暂时无法表示原始强度，恢复意图会保留到后续兼容模型；中间模型的钳制结果不会覆盖原始意图。
+/ultracode
 
-## 工作原理
-
-扩展注册单个 `workflow` 工具，并在 input preflight 与 `before_agent_start` 边界按 Ultracode 状态校准 active tools，同时保留其他 active tools。关闭或暂停时，`tool_call` 与实际执行入口会双重 fail-closed 拒绝残留调用。工具输入是 JavaScript 源码，其中必须包含纯字面量 `meta` 导出：
-
-```js
-export const meta = {
-  name: "review_and_fix",
-  description: "Review independent areas, then verify the combined result",
-};
+Review the current branch in parallel, verify every finding,
+fix the justified issues, and run the relevant tests.
 ```
 
-脚本可使用下列全局变量：
+Pi decides whether a workflow is useful. Small tasks can still use the normal single-agent loop.
 
-- `agent(prompt, options)`
-- `parallel(thunks, options?)`
-- `pipeline(items, ...stages)`
-- `phase(title)`
-- `log(message)`
-- `workflow(nameOrRef, args)`
-- `args`
-- `cwd`
+Useful commands:
 
-workflow 工具本身支持 `maxAgents?: integer`：默认 128，范围 1–1024。它限制同一 run 在首次执行及所有 resume 中累计获准启动的 live agent；cache replay 不重复占用额度。它不是 token budget，token/cost 仍只用于观测展示。
-
-`agent()` 的主要选项：
-
-| 选项 | 作用 |
+| Command | Action |
 | --- | --- |
-| `label` | 进度中显示的 2–5 个词短名称。 |
-| `phase` | 显式指定进度阶段。 |
-| `schema` | 内联的有界 JSON Schema 子集（≤256 KiB、深度≤64）；成功时返回经 `structured_output` 校验且≤2 MiB 的对象。 |
-| `model` | 按模式覆盖模型，也可带 `:off`、`:high`、`:xhigh` 或 `:max`。 |
-| `agentType` | 使用内置或自定义角色。 |
-| `isolation: "worktree"` | 在临时 git worktree 中运行写入型代理。 |
-
-为保证可恢复和确定性，脚本不提供 Node.js 模块加载能力，也不允许直接使用 `fs`、网络、`Date.now()`、`new Date()` 或 `Math.random()`。Worker 使用 context-realm bridge，禁用字符串/Wasm code generation，并设置 128 MiB V8 old-generation heap 上限；Intl/Temporal、ArrayBuffer、SharedArrayBuffer、typed arrays 与 WebAssembly 不向脚本开放。控制流另受循环/函数 checkpoint、host-call fuel、AST 结构限制、同步 stall watchdog 和无 host RPC 时的 idle-progress watchdog 约束。这些是确定性与 liveness guard，不是安全沙箱，也不宣称与 Grok Build 的 Rhai operation fuel 完全等价。所有 `agent()`、`parallel()`、`pipeline()` 和 `workflow()` 返回值都必须直接被 await 或 return；原生 `.then/.catch/.finally` 链、动态 method call（`value[key](...)`）和 `Promise.all/allSettled/race/any` 会在执行前被拒绝（本地异步仅保留 `new Promise(...)` 与 `Promise.resolve(...)`）。并发编排必须使用 `parallel()`/`pipeline()`，以保持 call path 可恢复且不受完成顺序影响；同 scope 的 sibling async orchestration 及未观察或仍 pending 的编排 promise 也会使 workflow 失败。
-
-含编排调用的 helper 也属于可恢复身份的一部分，因此只支持直接声明的函数/函数变量，或声明对象/已赋给标识符的 class instance 上的静态 method call。helper alias、事后赋值 method、`this.otherMethod()` 转发、临时/awaited factory receiver 与高阶 callable 会在执行前 fail closed；请先改写为一个直接声明的 helper，再从明确的源码调用点调用它。编译器会把源码调用点、词法 loop iteration、helper caller scope、请求指纹和同请求 occurrence 组合成 durable identity，避免条件分支、循环、并行完成顺序或 resume 重试改变 cache 对应关系。
+| `/ultracode` | Toggle Ultracode on or off |
+| `/ultracode on` | Explicitly enable it (optional alias) |
+| `/ultracode off` | Disable it and restore the previous thinking level |
+| `/ultracode status` | Show the current mode and effective thinking level |
+| `/workflows` or `F6` | Open the workflow browser |
+| `/workflows <runId>` | Open a specific run |
+| `/workflows abort` | Abort active runs |
 
-资源输入输出同样有硬上限：`args` 1 MiB、schema 256 KiB/64 层、每个 agent/workflow output 2 MiB、journal 64 MiB。args/schema/output 必须是严格 JSON tree（只允许可持久化的有限 number〔不含 `-0`〕、string、boolean、null、array 与 plain object；拒绝 binary objects、accessor、稀疏数组以及循环/重复对象引用）。schema 只接受明确支持的子集：类型、object/array 结构、`enum`/`const`、`anyOf`/`allOf`、长度和数值约束及注解；未知关键字会直接拒绝。`$ref` 家族、`oneOf`、`format` 与所有 regex 关键字（包括 `pattern`/`patternProperties`）均不支持；JavaScript regex validation 无可靠执行上限。journal 在每次 append 前检查上限并校验记录语义；单进程恢复时只会修复 EOF 处的 torn JSONL 尾记录，文件中部损坏仍 fail closed。
+Press `Esc` to cancel a running workflow. In Pi's fullscreen TUI, use `Ctrl+PageUp`, `Ctrl+PageDown`, and `Ctrl+End` inside workflow details.
 
-### 取消与清理
+## Workflow example
 
-按 `Esc` 取消工作流时，取消信号会覆盖子代理初始化、异步 preflight 和流式执行窗口。运行器会等待进行中的 `abort()`，但 cleanup 最多等待 25 秒；即使 provider 忽略取消，workflow lease 也会在有界清理后释放。兼容旧版 Pi 时创建的临时 fallback 会话同样遵循该规则。
-
-### 直接调用
-
-```js
-export const meta = {
-  name: "single_review",
-  description: "Run one focused reviewer",
-};
-
-const result = await agent(
-  "Inspect src/mode.ts for lifecycle bugs. Return concise findings.",
-  { label: "mode review" },
-);
-
-return result;
-```
-
-### 并行检视
-
-`parallel()` 接收 thunk，而不是已经启动的 Promise。每个 panel 在任意 thunk 启动前原子预留 `options.reserveAgents ?? thunks.length` 个 agent slot；`reserveAgents` 不能小于 thunk 数。每个 thunk 保有一个独立基础 slot，其余显式预留量由 panel 共享；调用超过预留量会使整个 workflow 失败，不会临时挪用未预留的 `maxAgents` 容量。
+The main agent normally writes workflows for you. Reusable workflows can also be saved under `.pi/ultracode/workflows/*.workflow.js` or `~/.pi/ultracode/workflows/*.workflow.js`.
 
 ```js
 export const meta = {
   name: "parallel_review",
-  description: "Review independent concerns concurrently",
-};
-
-const tasks = [
-  ["correctness", "Review correctness and lifecycle behavior."],
-  ["tests", "Review test coverage and missing regressions."],
-  ["docs", "Review README and parity documentation."],
-];
-
-const results = await parallel(
-  tasks.map(([label, prompt]) => () => agent(prompt, { label })),
-  { reserveAgents: tasks.length },
-);
-
-return results.filter(Boolean);
-```
-
-### 流水线
-
-除非后续阶段确实需要所有前置结果，否则优先使用 `pipeline()`。不同条目可独立推进：
-
-```js
-export const meta = {
-  name: "review_pipeline",
-  description: "Inspect and verify several modules independently",
+  description: "Review correctness and tests in parallel",
 };
 
-const files = ["src/mode.ts", "src/workflow/agent-runner.ts"];
-
-const results = await pipeline(
-  files,
-  async (file) => agent(
-    `Inspect ${file} and report concrete risks.`,
-    { label: `inspect ${file}` },
+const findings = await parallel([
+  () => agent(
+    "Review the current branch for correctness and lifecycle bugs.",
+    { label: "correctness review" },
   ),
-  async (finding, file) => agent(
-    `Verify this finding against ${file}:\n\n${finding}`,
-    { label: `verify ${file}` },
+  () => agent(
+    "Review the current branch for missing or weak regression tests.",
+    { label: "test review" },
   ),
-);
+]);
 
-return results.filter(Boolean);
+return findings.filter(Boolean);
 ```
 
-### 结构化输出
-
-不传 `schema` 时，`agent()` 返回子代理最后一段非空 assistant 文本；传入支持的 JSON Schema 子集时，则返回经校验的对象。两种返回值都必须是≤2 MiB 的严格 JSON value：
+For editor IntelliSense, add:
 
 ```js
-export const meta = {
-  name: "structured_audit",
-  description: "Collect machine-readable findings",
-};
-
-const finding = await agent(
-  "Audit the mode lifecycle and return one finding.",
-  {
-    label: "lifecycle audit",
-    schema: {
-      type: "object",
-      properties: {
-        severity: { enum: ["low", "medium", "high"] },
-        summary: { type: "string" },
-      },
-      required: ["severity", "summary"],
-      additionalProperties: false,
-    },
-  },
-);
-
-return finding;
+/// <reference types="pi-ultracode/workflow" />
 ```
 
-使用 schema 的代理必须调用 `structured_output`。否则该 `agent()` 分支会失败并返回 `null`；工作流本身仍可继续，因此脚本应过滤或显式处理失败分支，而不会把自由文本伪装成结构化结果。
+The complete workflow contract is documented in [`types/workflow.d.ts`](types/workflow.d.ts). A larger example is available in [`examples/workflows`](examples/workflows).
 
-## Agent Type
+## Roles, models, and worktrees
 
-项目级角色定义放在：
+Custom agent roles live in:
 
 ```text
 .pi/ultracode/agents/*.md
-```
-
-用户级角色定义放在：
-
-```text
 ~/.pi/ultracode/agents/*.md
 ```
 
-同时兼容旧的用户级目录 `~/.pi/agent/agents/*.md`。
-
-示例：
-
-```md
----
-name: reviewer
-description: Read-only reviewer focused on correctness and regressions
-tools: read, bash
-model: anthropic/claude-sonnet-4
-thinking: high
----
-
-Inspect the requested area. Do not modify files. Report only evidence-backed findings.
-```
-
-工作流中的用法：
+A call can select a role, model, thinking level, or worktree isolation:
 
 ```js
-await agent("Review the current diff.", {
-  label: "diff review",
-  agentType: "reviewer",
-});
-```
-
-内置类型包括 `claude`、`general-purpose`、`Explore`、`Plan` 和 `code-reviewer`。
-
-Agent Type 可控制：
-
-- 角色提示词；
-- 工具白名单；
-- 默认模型；
-- 默认思考强度。
-
-每次调用的选项优先于 Agent Type 默认值。
-
-## 模型选择
-
-`model` 接受 provider/model 模式，并可带思考强度后缀：
-
-```js
-await agent("Analyze this failure.", {
-  label: "failure analysis",
-  model: "openai/gpt-5.6-sol:max",
-});
-```
-
-若未指定 model，则子代理继承工作流工具创建时的 Pi 当前模型。Ultracode 启用时，默认子代理强度同样请求 `max`，并按每个代理实际选择的模型独立钳制。Ultracode 不会自动启用 GPT-5.6 的 `pro` 模式。
-
-## Worktree 隔离
-
-并行写入同一工作树容易产生竞态。对会修改文件的代理使用：
-
-```js
-await agent("Implement the requested change and run focused tests.", {
-  label: "implementation",
+await agent("Implement and test the fix.", {
+  label: "implement fix",
+  agentType: "general-purpose",
+  model: "anthropic/claude-sonnet-4:high",
   isolation: "worktree",
 });
 ```
 
-运行器会：
+Worktree isolation requires a git repository with at least one commit. If setup fails, Ultracode logs the fallback and runs that agent in the shared working directory; avoid parallel writers in that case. A clean working tree is recommended for predictable patch integration.
 
-1. 创建临时 git worktree；
-2. 在隔离目录运行代理；
-3. 捕获 worktree diff；
-4. 检查共享工作树是否漂移；
-5. 通过 `git apply --3way` 应用补丁；
-6. 在失败时保存 rescue patch；
-7. 成功且安全时清理临时 worktree。
+## Guardrails
 
-如果 diff 捕获、rescue 保存或补丁集成异常，运行器会故障安全地保留 worktree，并在日志中给出路径，避免丢失代理改动。确认内容后可手动恢复或删除；超过保留阈值的 Ultracode worktree 会由后续运行回收。
+A workflow defaults to `maxAgents: 128`, supports at most 16 concurrent agent calls, and allows one level of nested workflows. The lifetime agent limit is preserved across resumes; cached replay does not consume it again.
 
-使用隔离前，共享仓库必须处于干净状态。
+Workflow agent sessions retain project context and ordinary skills, but do not initialize ambient Pi extensions or expose parent orchestration tools and skills (`workflow`, `subagent`, `subagent_wait`, or `pi-subagents`). This keeps orchestration at the parent boundary and allows `pi-ultracode` and `pi-subagents` to coexist in the main session.
 
-## 已保存的工作流与可恢复运行
+Resume is intentionally immutable: the script, arguments, agent definitions, effective models, and call structure must still match. Changed work starts a new run.
 
-可复用工作流可放在：
-
-```text
-.pi/ultracode/workflows/<name>.workflow.js
-~/.pi/ultracode/workflows/<name>.workflow.js
-```
+Token and cost data are reported for observability, not enforced as a budget. Worker and VM restrictions are determinism and liveness guards, not a security sandbox.
 
-可通过工具的 `name`、`scriptPath`，或脚本内调用来运行：
+## Design inspiration
 
-```js
-await workflow("saved_workflow_name", { target: "src" });
-```
+- **Claude Code** — natural-language, terminal-first agentic coding and focused delegation.
+- **Grok Build** — explicit workflows, durable journals, bounded admission, and structural execution controls.
+- **Pi** — the model runtime, sessions, tools, extension API, and TUI remain native Pi behavior.
 
-嵌套限制为一层，且共享父运行的并发上限、`maxAgents`、当前 parallel reservations 与代理计数。由 workflow 启动的 child Pi session 会显式排除 `workflow` 工具，不能再创建一条拥有独立额度的新 workflow 链。
+`pi-ultracode` is an independent Pi extension and is not affiliated with Anthropic or xAI.
 
-每次运行都会把脚本和 JSONL journal 保存到：
-
-```text
-<sessionDir>/ultracode-runs/<runId>.workflow.js
-<sessionDir>/ultracode-runs/<runId>.jsonl
-```
-
-没有 sessionDir 的独立调用使用用户目录下按 cwd 哈希隔离的 `~/.pi/ultracode-runs/<cwd-hash>/`，不会写入仓库可控制的 `.pi` symlink。run script、journal、details 和 transcript 会拒绝 symlink/non-regular artifacts，并使用 no-follow/独占或原子写入。与 Pi 和 Grok Build 一样，session 采用单进程 owner 模型；同一 Pi 进程内由 process-local lease 阻止重复运行同一 runId，但不支持两个 Pi 进程并发写同一个 session。
-
-已有 run 可再次调用 `workflow` 并传入 `resumeFromRunId`。resume 是 immutable：顶层 script/args、实际解析到的 Agent Type 定义、effective model/thinking，以及每个 nested workflow call path 的源码/args 都必须和原 run 完全一致；args 的可观察对象键序也属于 identity。需要修改工作时必须启动新 run。成功的 agent 结果按 Worker 生成的稳定结构 call path replay，因此不受 parallel/pipeline 完成顺序影响。live admission 会在 runner side effect 前持久化，并在整个 run 生命周期累计；恢复时省略 `maxAgents` 会继承当前上限，显式值只能提高、不能降低。不存在或格式不受支持的 runId 会明确失败。
-
-## 限制
-
-运行时限制：
-
-- run-lifetime `maxAgents` live admission（默认 128，绝对上限 1024；cache replay 免费）；
-- 同一进程、同一 session/runsDir 最多 4 个活动顶层 workflow；
-- 每个 run 最大并发 16；
-- 最多一层嵌套 workflow；
-- 10,000 次 host-call fuel、AST/checkpoint、stall 与 idle-progress 限制；
-- Worker V8 old-generation heap 128 MiB，并禁用 string/Wasm code generation 与二进制内存构造器；
-- args/schema/structured output/journal 字节与结构上限；
-- 取消后的 25 秒 cleanup deadline；
-- child session 显式排除 `workflow` 工具；
-- 结构化输出校验；
-- 静态及 context-realm 运行期确定性 guard。
-
-## 会话与兼容性
-
-Ultracode 模式状态通过自定义 session entry 持久化。恢复、reload、fork 和 `/tree` 导航都会按当前 branch 重新读取状态；被丢弃分支中的 entry 不会错误启用模式。旧版 Pi 或旧模型会把 `max` 兼容回退为 `xhigh`，而不会把未知值静默变成 `off`。
-
-### 0.3 迁移说明
-
-0.3 引入 Grok Build 式结构控制：`maxAgents` 默认为 128（范围 1–1024），并在同一 run 的所有 resume 中累计 live admissions；cache replay 不重复占用。`parallel()` 会在启动前按 panel 原子预留 slots，`reserveAgents < thunks.length`、调用超过预留量或超过 `maxAgents` 都是 fatal policy failure。一个 thunk 会调用多个 agent 时，必须用 `reserveAgents` 显式覆盖全部潜在调用。resume 改为 immutable script/args，并按稳定结构 call path replay；旧的“修改脚本后最长前缀恢复”不再支持。同一进程、同一 session/runsDir 同时最多 4 个顶层 workflow，取消清理有 25 秒上限，run artifacts 拒绝 symlink。
-
-### 0.2 迁移说明
-
-0.2 移除了 token budget 功能：`/ultracode budget` 命令、workflow tool 的 `budget` 参数，以及 workflow 脚本中的全局 `budget` 对象都不再存在。旧的 saved workflow 如果引用 `budget.total`、`budget.remaining()` 或 `budget.spent()`，需要删除这些引用，改为显式的 agent 数量、循环条件或输入列表边界。
-
-扩展清理只管理自己的详情浮层、status 与运行状态，不会调用 Pi 的全局 `ui.clear()`，因此不会清除其他扩展的 UI。
-
-## 开发
+## Development
 
 ```bash
 npm ci
@@ -436,48 +150,6 @@ npm test
 npm pack --dry-run
 ```
 
-项目源码位于：
-
-- `extensions/ultracode.ts`：扩展入口和 Pi 生命周期接线；
-- `src/mode.ts`：Ultracode 模式状态、恢复与强度管理；
-- `src/thinking.ts`：共享思考强度词汇与兼容性检测；
-- `src/workflow/`：脚本验证、运行时、子代理执行、worktree 和进度显示；
-- `test/`：单元、扩展和回归测试；
-- `docs/parity.md`：与原生 Pi 能力边界的说明。
-
-开发依赖会安装 TypeScript 和用于测试的 Pi peer 包；通过 `pi install` 加载正式包时，Pi 仍会提供这些 peer 依赖。
-
-## 发布
-
-npm 发布由 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) 完成，使用 npm Trusted Publishing（OIDC），无需保存长期 `NPM_TOKEN`。
-
-首次使用前，在 npm 的 `pi-ultracode` 包设置中添加 GitHub Actions Trusted Publisher：
-
-- Organization or user：`ekil1100`
-- Repository：`pi-ultracode`
-- Workflow filename：`publish-npm.yml`
-- Environment name：`npm`
-- Allowed action：`npm publish`
-
-同时在 GitHub 仓库中创建名为 `npm` 的 Environment；可以按需增加审批人。正常发布无需打开 Actions 页面：
-
-```bash
-npm version patch # or: minor / major / x.y.z-beta.1
-git push origin main --follow-tags
-```
-
-`npm version` 会同步更新 `package.json` 和 `package-lock.json`，创建版本提交与 `v<version>` Tag；推送 Tag 后 CI 自动发布。稳定版本发布到 `latest`，预发布版本发布到 `next`。
-
-需要重试或指定其他 npm dist-tag 时，也可以在 Actions 中手动运行工作流；填写完全匹配 `package.json` 的版本，且只允许从 `main` 运行。
-
-工作流会校验 Tag 与包版本完全一致、确认版本尚未发布，并在正式发布前执行干净安装、测试和类型检查。
-
-## 设计原则
-
-Ultracode 的目标不是“尽可能多地启动代理”，而是：
-
-> 在任务确实适合拆分、并行、独立验证或跨上下文扩展时，使用确定性编排获得更高置信度；否则继续使用 Pi 简洁直接的单代理循环。
-
-## 许可证
+## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,155 @@
+# pi-ultracode
+
+为 [Pi](https://github.com/earendil-works/pi) 提供确定性的多代理工作流。
+
+[English](README.md) · **简体中文**
+
+`pi-ultracode` 为 Pi 增加一个可选的高强度执行模式。当任务适合拆分时，主代理可以运行有边界的 JavaScript 工作流，使用并行子代理、隔离 worktree、结构化输出、持久恢复和实时进度。
+
+项目结合了 [Claude Code](https://github.com/anthropics/claude-code) 的终端 Agentic 体验，以及 [Grok Build](https://github.com/xai-org/grok-build) 的显式工作流和结构控制思路，同时继续使用 Pi 作为运行时。
+
+## 安装
+
+```bash
+pi install npm:pi-ultracode
+```
+
+然后重新加载 Pi，并用主命令切换到 Ultracode：
+
+```text
+/reload
+/ultracode
+```
+
+也可以在启动时直接启用：
+
+```bash
+pi --ultracode
+```
+
+> `pi-ultracode` 会注册名为 `workflow` 的工具。如果已安装 `pi-dynamic-workflows`，请先运行 `pi remove npm:pi-dynamic-workflows`。
+
+当前版本已在 Pi 0.84 上验证。
+
+## 核心特性
+
+- **可选高强度模式**：请求当前模型支持的最高思考强度，关闭时恢复之前的强度。
+- **显式工作流**：通过 `agent()`、`parallel()`、`pipeline()` 和嵌套 `workflow()` 组合任务。
+- **独立子代理**：每个代理拥有独立的 Pi 会话、上下文、工具、模型选择和可选角色。
+- **并行 worktree 隔离**：写入型代理可在临时 git worktree 中工作，再集成补丁。
+- **结构化输出**：使用有边界的 JSON Schema 子集校验代理结果。
+- **持久恢复**：按照稳定的结构身份复用已完成调用，不重复执行成功任务。
+- **实时可观测性**：在 TUI 中查看状态、模型、思考强度、turn、工具、token、重试和 transcript。
+- **有界执行**：限制累计代理数、并发、JSON 大小、Worker 运行和取消清理时间。
+
+## 快速开始
+
+用主命令开启 Ultracode，然后描述一个较复杂的任务：
+
+```text
+/ultracode
+
+Review the current branch in parallel, verify every finding,
+fix the justified issues, and run the relevant tests.
+```
+
+Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通的单代理循环。
+
+常用命令：
+
+| 命令 | 作用 |
+| --- | --- |
+| `/ultracode` | 切换 Ultracode 的开启或关闭状态 |
+| `/ultracode on` | 显式启用（可选别名） |
+| `/ultracode off` | 关闭并恢复之前的思考强度 |
+| `/ultracode status` | 查看当前模式和实际思考强度 |
+| `/workflows` 或 `F6` | 打开工作流浏览器 |
+| `/workflows <runId>` | 打开指定运行 |
+| `/workflows abort` | 中止活动运行 |
+
+按 `Esc` 可取消正在运行的工作流。在 Pi 的 fullscreen TUI 中，请在工作流详情内使用 `Ctrl+PageUp`、`Ctrl+PageDown` 和 `Ctrl+End`。
+
+## 工作流示例
+
+通常由主代理自动编写工作流。需要复用时，可以保存到 `.pi/ultracode/workflows/*.workflow.js` 或 `~/.pi/ultracode/workflows/*.workflow.js`。
+
+```js
+export const meta = {
+  name: "parallel_review",
+  description: "Review correctness and tests in parallel",
+};
+
+const findings = await parallel([
+  () => agent(
+    "Review the current branch for correctness and lifecycle bugs.",
+    { label: "correctness review" },
+  ),
+  () => agent(
+    "Review the current branch for missing or weak regression tests.",
+    { label: "test review" },
+  ),
+]);
+
+return findings.filter(Boolean);
+```
+
+如需编辑器类型提示，请添加：
+
+```js
+/// <reference types="pi-ultracode/workflow" />
+```
+
+完整工作流接口见 [`types/workflow.d.ts`](types/workflow.d.ts)，更多示例见 [`examples/workflows`](examples/workflows)。
+
+## 角色、模型与 worktree
+
+自定义代理角色放在：
+
+```text
+.pi/ultracode/agents/*.md
+~/.pi/ultracode/agents/*.md
+```
+
+每次调用都可以选择角色、模型、思考强度或 worktree 隔离：
+
+```js
+await agent("Implement and test the fix.", {
+  label: "implement fix",
+  agentType: "general-purpose",
+  model: "anthropic/claude-sonnet-4:high",
+  isolation: "worktree",
+});
+```
+
+Worktree 隔离只能在至少有一个 commit 的 Git 仓库中使用。如果创建失败，Ultracode 会记录回退信息，并让该代理在共享工作目录中运行；此时应避免并行写入。为保证补丁集成可预测，建议保持工作区干净。
+
+## 执行边界
+
+工作流默认使用 `maxAgents: 128`，最多并发运行 16 个代理，并只允许一层嵌套工作流。累计代理上限会跨 resume 保留，缓存回放不会再次占用额度。
+
+Workflow 子代理会保留项目上下文和普通 skills，但不会初始化环境中的 Pi 扩展，也不会暴露父级编排工具与 skill（`workflow`、`subagent`、`subagent_wait` 或 `pi-subagents`）。这样可把编排限制在父会话边界，同时允许 `pi-ultracode` 与 `pi-subagents` 在主会话中共存。
+
+Resume 刻意保持不可变：脚本、参数、代理定义、实际模型和调用结构都必须匹配。工作内容发生变化时，应启动新的 run。
+
+Token 和成本只用于可观测性，不作为执行预算。Worker 与 VM 限制用于确定性和存活性保护，不是安全沙箱。
+
+## 设计参考
+
+- **Claude Code**：自然语言驱动、终端优先的 Agentic 编码体验和任务委派。
+- **Grok Build**：显式工作流、持久 journal、有界 admission 和结构执行控制。
+- **Pi**：模型运行时、会话、工具、扩展 API 和 TUI 都继续使用 Pi 原生能力。
+
+`pi-ultracode` 是独立的 Pi 扩展，与 Anthropic 或 xAI 没有关联。
+
+## 开发
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ultracode",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Claude-Code-style \"ultracode\" for Pi: an effort mode that defaults to deterministic multi-agent workflow orchestration, with worktree isolation, per-agent model overrides, custom agent types, nested workflows, resumable runs, and a /workflows manager.",
   "type": "module",
   "keywords": [
@@ -53,10 +53,10 @@
     "acorn": "^8.11.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
-    "@earendil-works/pi-tui": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.0",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "@types/node": "^24.12.4",
     "typebox": "1.3.7",
     "typescript": "^5.9.3"

package/src/prompts.ts

@@ -64,7 +64,7 @@ export const WORKFLOW_GUIDELINES: string[] = [
   "For the workflow tool, if agent() needs machine-readable output pass an inline JSON Schema via opts.schema; agent() then returns the validated object. Use only the bounded subset: types, object/array structure, enum/const, anyOf/allOf, length/numeric constraints, and annotations. Unknown keywords, $ref variants, oneOf, format, pattern, and patternProperties are rejected. Keep schemas under 256 KiB / 64 levels and every agent/workflow output under 2 MiB. Use JSON Schema, not TypeScript or TypeBox constructors.",
   "For the workflow tool, when agent() is called WITHOUT a schema, its return value is the subagent's final assistant text (the last text the subagent produced). With a schema it returns the validated structured_output object. Prefer a schema for machine-readable results; use the text form only for prose summaries.",
   "For the workflow tool, agent opts also accept: model (override the subagent model by pattern), agentType (use a custom subagent role/system-prompt), isolation:'worktree' (run the agent in an isolated git worktree — use ONLY when agents mutate files in parallel and would conflict), and phase (assign the agent to a progress group explicitly inside parallel()/pipeline()).",
-  "For the workflow tool, workflow(nameOrRef, args) runs a saved workflow (by name) or a scriptPath inline as a sub-step, sharing this run's concurrency, maxAgents, active reservations, and agent counter. Nesting is one level only. Child subagent sessions explicitly exclude the workflow tool and cannot start an independent recursive workflow chain.",
+  "For the workflow tool, workflow(nameOrRef, args) runs a saved workflow (by name) or a scriptPath inline as a sub-step, sharing this run's concurrency, maxAgents, active reservations, and agent counter. Nesting is one level only. Child subagent sessions do not load ambient extensions or expose workflow/subagent orchestration tools, so they cannot start an independent recursive workflow chain.",
   "For workflow resumeFromRunId, reuse the exact same script and args. Resume is immutable, successful calls replay by stable structural call path, and maxAgents may only stay the same or increase; changed work must start a new run.",
   "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted or a policy limit is hit). Check for nulls before synthesizing conclusions, and prefer a final synthesis/assertion agent that returns a compact JSON-serializable verdict.",
   "For the workflow tool, directly await or return every orchestration promise (agent/parallel/pipeline/workflow). Native .then/.catch/.finally chains and Promise.all/allSettled/race/any are rejected; use parallel() or pipeline() so call identity stays deterministic. Unobserved, pending, or native same-scope concurrent orchestration is fatal.",

package/src/workflow/agent-runner.ts

@@ -14,6 +14,7 @@ import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import {
   createAgentSession,
   createCodingTools,
+  DefaultResourceLoader,
   getAgentDir,
   SessionManager,
   SettingsManager,
@@ -45,6 +46,42 @@ import type { AgentTypeDef } from "./agent-types.ts";
 
 export type { ThinkingLevel } from "../thinking.ts";
 
+const CHILD_ORCHESTRATION_TOOLS = ["workflow", "subagent", "subagent_wait"];
+const PARENT_ONLY_CHILD_SKILLS = new Set(["pi-subagents"]);
+
+export interface WorkflowChildResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  settingsManager?: SettingsManager;
+}
+
+/**
+ * Build the sealed resource view used by workflow agent sessions.
+ *
+ * Ambient extension factories execute during discovery, so filtering an already
+ * loaded extension result is too late: another in-process orchestrator may have
+ * already replaced process-global lifecycle state. Disable ambient extensions at
+ * the loader boundary while retaining project context and ordinary skills.
+ */
+export async function createWorkflowChildResourceLoader(
+  options: WorkflowChildResourceLoaderOptions,
+): Promise<DefaultResourceLoader> {
+  const settingsManager = options.settingsManager
+    ?? SettingsManager.create(options.cwd, options.agentDir);
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir: options.agentDir,
+    settingsManager,
+    noExtensions: true,
+    skillsOverride: ({ skills, diagnostics }) => ({
+      skills: skills.filter((skill) => !PARENT_ONLY_CHILD_SKILLS.has(skill.name)),
+      diagnostics,
+    }),
+  });
+  await loader.reload();
+  return loader;
+}
+
 /** A minimal structural view of a Pi model (avoids importing the heavy generic type). */
 export interface ModelLike {
   provider: string;
@@ -192,7 +229,10 @@ export interface WorkflowAgentRunnerOptions {
   model?: ModelLike;
   /** Default thinking level for subagents. */
   thinkingLevel?: ThinkingLevel;
-  /** Test seam for session construction and initialization races. */
+  /**
+   * Test seam for session construction and initialization races. Custom
+   * factories own resource isolation; production uses the sealed Pi loader.
+   */
   createSession?: AgentSessionFactory;
   /** Test/compatibility seam for async ModelRuntime initialization. */
   createModelRuntime?: ModelRuntimeFactory;
@@ -243,6 +283,7 @@ export class WorkflowAgentRunner {
   private readonly defaultModel?: ModelLike;
   private readonly defaultThinking?: ThinkingLevel;
   private readonly createSession: AgentSessionFactory;
+  private readonly usesPiSessionFactory: boolean;
   private readonly createModelRuntime?: ModelRuntimeFactory;
   private modelRuntimePromise?: Promise<ModelRuntimeLike | undefined>;
   private readonly runtimeSupportsMaxThinking: boolean;
@@ -253,10 +294,10 @@ export class WorkflowAgentRunner {
     this.providedModelRuntime = options.modelRuntime;
     this.defaultModel = options.model;
     this.defaultThinking = options.thinkingLevel;
-    const usesPiSessionFactory = options.createSession === undefined;
+    this.usesPiSessionFactory = options.createSession === undefined;
     this.createSession = options.createSession ?? (createAgentSession as unknown as AgentSessionFactory);
     this.createModelRuntime = options.createModelRuntime
-      ?? (options.modelRuntime !== undefined || !usesPiSessionFactory ? undefined : createPiModelRuntime);
+      ?? (options.modelRuntime !== undefined || !this.usesPiSessionFactory ? undefined : createPiModelRuntime);
     this.runtimeSupportsMaxThinking = options.supportsMaxThinking ?? piVersionSupportsMaxThinking(PI_VERSION);
   }
 
@@ -304,22 +345,29 @@ export class WorkflowAgentRunner {
       throw error;
     }
 
-    const createSession = (level: ThinkingLevel | undefined) => this.createSession({
-      cwd,
-      agentDir,
-      sessionManager: SessionManager.inMemory(cwd),
-      settingsManager: SettingsManager.create(cwd, agentDir),
-      customTools,
-      excludeTools: ["workflow"],
-      ...(model ? { model: model as any } : {}),
-      ...(level ? { thinkingLevel: level as any } : {}),
-      ...(toolAllowlist ? { tools: toolAllowlist } : {}),
-      ...(modelRuntime
-        ? { modelRuntime }
-        : this.modelRegistry
-          ? { modelRegistry: this.modelRegistry as any }
-          : {}),
-    });
+    const createSession = async (level: ThinkingLevel | undefined) => {
+      const settingsManager = SettingsManager.create(cwd, agentDir);
+      const resourceLoader = this.usesPiSessionFactory
+        ? await createWorkflowChildResourceLoader({ cwd, agentDir, settingsManager })
+        : undefined;
+      return this.createSession({
+        cwd,
+        agentDir,
+        sessionManager: SessionManager.inMemory(cwd),
+        settingsManager,
+        ...(resourceLoader ? { resourceLoader } : {}),
+        customTools,
+        excludeTools: [...CHILD_ORCHESTRATION_TOOLS],
+        ...(model ? { model: model as any } : {}),
+        ...(level ? { thinkingLevel: level as any } : {}),
+        ...(toolAllowlist ? { tools: toolAllowlist } : {}),
+        ...(modelRuntime
+          ? { modelRuntime }
+          : this.modelRegistry
+            ? { modelRegistry: this.modelRegistry as any }
+            : {}),
+      });
+    };
 
     const sessionThinking = resolveSessionThinkingLevel(thinkingLevel, model);
     safeEmitTelemetry(call.onTelemetry, {
@@ -619,9 +667,27 @@ export function resolveSessionThinkingLevel(
 
 function matchExactModelIn(models: ModelLike[] | undefined, pattern: string): ModelLike | undefined {
   if (!models || !pattern.trim()) return undefined;
-  const lower = pattern.trim().toLowerCase();
-  return models.find((m) => `${m.provider}/${m.id}`.toLowerCase() === lower)
-    ?? models.find((m) => m.id.toLowerCase() === lower);
+  const trimmed = pattern.trim();
+  const lower = trimmed.toLowerCase();
+  const canonicalMatches = models.filter((model) =>
+    `${model.provider}/${model.id}`.toLowerCase() === lower
+  );
+  if (canonicalMatches.length === 1) return canonicalMatches[0];
+  if (canonicalMatches.length > 1) throw ambiguousModelReferenceError(trimmed, canonicalMatches);
+
+  const idMatches = models.filter((model) => model.id.toLowerCase() === lower);
+  if (idMatches.length === 1) return idMatches[0];
+  if (idMatches.length > 1) throw ambiguousModelReferenceError(trimmed, idMatches);
+  return undefined;
+}
+
+function ambiguousModelReferenceError(pattern: string, matches: ModelLike[]): Error {
+  const references = [...new Set(matches.map((model) => `${model.provider}/${model.id}`))]
+    .sort((left, right) => left.localeCompare(right))
+    .join(", ");
+  return new Error(
+    `Model "${safeDisplayText(pattern, 80)}" is ambiguous across providers: ${safeDisplayText(references, 400)}. Use provider/model.`,
+  );
 }
 
 /** Match a model pattern against a registry list: exact provider/id, then exact id, then substring. */

package/src/workflow/workflow-overlay.ts

@@ -24,6 +24,12 @@ const MIN_SPLIT_WIDTH = 100;
 const MAX_RENDER_FPS_INTERVAL_MS = 100;
 let overlayOpen = false;
 
+type OverlayNavigationKey = "pageUp" | "pageDown" | "end";
+
+function matchesOverlayNavigationKey(data: string, key: OverlayNavigationKey): boolean {
+  return matchesKey(data, key) || matchesKey(data, `ctrl+${key}`);
+}
+
 interface TaskViewport {
   offset: number;
   follow: boolean;
@@ -318,8 +324,8 @@ export class WorkflowOverlayComponent implements Component {
     if (currentIndex >= 0) this.selectedTaskIndex = currentIndex;
     if (matchesKey(data, "up")) this.selectedTaskIndex = Math.max(0, this.selectedTaskIndex - 1);
     else if (matchesKey(data, "down")) this.selectedTaskIndex = Math.min(tasks.length - 1, this.selectedTaskIndex + 1);
-    else if (matchesKey(data, "pageUp")) this.selectedTaskIndex = Math.max(0, this.selectedTaskIndex - 10);
-    else if (matchesKey(data, "pageDown")) this.selectedTaskIndex = Math.min(tasks.length - 1, this.selectedTaskIndex + 10);
+    else if (matchesOverlayNavigationKey(data, "pageUp")) this.selectedTaskIndex = Math.max(0, this.selectedTaskIndex - 10);
+    else if (matchesOverlayNavigationKey(data, "pageDown")) this.selectedTaskIndex = Math.min(tasks.length - 1, this.selectedTaskIndex + 10);
     else if (matchesKey(data, "enter") || matchesKey(data, "return")) {
       if (split) this.focus = "detail";
       else {
@@ -341,13 +347,13 @@ export class WorkflowOverlayComponent implements Component {
     } else if (matchesKey(data, "down")) {
       viewport.offset++;
       viewport.follow = false;
-    } else if (matchesKey(data, "pageUp")) {
+    } else if (matchesOverlayNavigationKey(data, "pageUp")) {
       viewport.offset = Math.max(0, viewport.offset - page);
       viewport.follow = false;
-    } else if (matchesKey(data, "pageDown")) {
+    } else if (matchesOverlayNavigationKey(data, "pageDown")) {
       viewport.offset += page;
       viewport.follow = false;
-    } else if (matchesKey(data, "end")) {
+    } else if (matchesOverlayNavigationKey(data, "end")) {
       viewport.follow = true;
       viewport.newLines = 0;
     }
@@ -456,9 +462,13 @@ export class WorkflowOverlayComponent implements Component {
       viewport.offset = Math.max(0, Math.min(viewport.offset, maxOffset));
     }
     const visible = body.slice(viewport.offset, viewport.offset + bodyHeight);
+    // Fullscreen owns unmodified paging keys before focused overlays receive input.
+    // Ctrl variants remain routed to the overlay under Pi 0.84's default bindings.
+    const pageKeys = this.tui.mode === "fullscreen" ? "Ctrl+PgUp/Dn" : "PgUp/Dn";
+    const endKey = this.tui.mode === "fullscreen" ? "Ctrl+End" : "End";
     const footer = viewport.follow
-      ? "↑↓/PgUp scroll · End follow · p prompt · Tab tasks · Esc back"
-      : `↓ ${viewport.newLines} new lines · End to follow`;
+      ? `↑↓/${pageKeys} scroll · ${endKey} follow · p prompt · Tab tasks · Esc back`
+      : `↓ ${viewport.newLines} new lines · ${endKey} to follow`;
     return fitHeight([...fixed, "", ...visible, this.theme.fg("dim", footer)], height);
   }