@aragon-agent/cli 0.6.17 → 0.6.18

package/CHANGELOG.md

@@ -5,57 +5,89 @@ All notable changes to `@aragon-agent/cli` are documented here. Entries at
 — those releases really were published under that name, so they are left as they
 were written.
 
-## Unreleased
-
-### 启动与缩窗不再误报 Frame diff lost sync
-
-- 启动即现的 "Frame diffing lost sync with the terminal and fell back to a
-  full repaint … `--no-diff-render`" 警告已消除：Ink 挂载/卸载经渲染 stdout 写出的
-  光标隐藏/恢复序列（`ESC[?25l` / `ESC[?25h`）由帧写入器直接透传——不进差分、
-  不失效缓存、不计 fallback，也不再消耗会话的首写豁免。启动序列恢复
-  "种子帧透传 → 首帧全量 → 之后纯 diff"。
-- 终端高度缩小（拖小窗口、改字号、面板重排）不再触发同一条警告：Ink 的
-  `clearTerminal` 整帧写入被差分器识别为 Ink 自身写法，透传并失效缓存但不计
-  fallback；该控制写同样不消耗首写豁免，其后的首个 log-update 帧仍按种子帧豁免，
-  下一帧自然全量重绘。
-- `/perf` 的 `fallbacks` 重新从 0 起步，"健康会话 fallbacks === 0" 的诊断信号
-  （AC-11）恢复可判。
-
-### Consistent TUI styling
-
-- Interactive sessions always use Unicode and default to truecolor, including
-  PowerShell sessions without terminal or UTF locale markers. Ink's actual color
-  output follows the same policy, with renderer state restored on exit.
-- Explicit color opt-outs keep Unicode borders and icons; the opening logo now
-  depends only on available space. Headless terminal detection is unchanged.
-- Reloading model settings preserves session display preferences. Syntax
-  highlighting follows the same color policy, and status icons use consistent
-  single-column glyphs to prevent narrow-frame overflow.
-- Hiding the editor caret while scrolling preserves draft geometry, preventing
-  a layout update loop when entering text above the full startup logo.
-- Register exit cleanup before mounting the application, so immediate exits and
-  initial render failures restore terminal and color state reliably. Failed
-  mounts no longer mark an auto-installed build as healthy.
-
-### Model context window
-
-- Discover context limits at startup and after connection changes without blocking
-  input. The status bar and compaction use the discovered limit; `/context` names
-  API versus catalog metadata. Unknown windows show `?`, not a fabricated 128k
-  capacity or percentage. Manual `contextWindow` overrides retain precedence.
-- Window overrides now apply to tail relief and compaction progress as well as
-  the gauge. Workers on different models/endpoints do not inherit the lead's
-  override. API-key changes refresh metadata, and ending a session cancels its
-  pending model queries. `/context` also hides unknown capacities/percentages.
-
-### TUI 输入与排队可靠性
-
-- Shift+Enter 与粘贴按输入顺序处理；普通 Enter 保持弹层兼容，混合输入最多提交一次，
-  余稿及拒绝提交的正文保留。结束输入流时完整排空，不泄漏内部控制标记。
-- 超限粘贴拒绝同一外部输入块的正文和 Enter，避免误提交旧稿；未闭合粘贴继续按正文消费。
-- 拖选后仅 Ctrl+C 复制；文字变化与丢失鼠标释放时取消无效高亮，避免卡住视口。
-- 固定 Queue 状态行按消息 ID 回执更新，支持窄屏、暂停与多条消息计数。
-- 保存和退出保留所有未发送全文；恢复先验证存档，旧 queued 作为警告展示且不自动重放。
+## Unreleased
+
+### Team dispatch supervisor (team-overseer)
+
+- **A time ceiling on a subagent is now an inspection trigger, not a death
+  sentence.** With the supervisor on (new key `team.overseer`, default
+  `true`, needs the fast tier), two soft timers per child - event silence at
+  `idleTimeoutMs` and a wall clock at `subagentTimeoutMs` (or 5 minutes when
+  no ceiling is configured) - fire one bounded fast-tier inspection. The
+  supervisor decides wait / nudge / replace / abandon; the runtime applies,
+  funnelling every lifecycle change through the worker loop that awaits the
+  child, so a replacement is never built for nobody.
+- **A nudge is steering; a replace is a rebuild with an amended brief.**
+  Guidance is queued at core's safe top-of-loop checkpoint; a replacement
+  carries the supervisor's reason, the dead child's `filesTouched`, and the
+  original brief bounded to the same prompt budget. A post-mortem inspection
+  diagnoses a child that died silently (watchdog death, stream loss) and may
+  re-assign it once.
+- **Budgets are structural, not settings**: 4 inspections and 1 replacement
+  per child per dispatch; past them the child runs under its own (lengthened
+  while supervised) idle watchdog and the supervisor goes quiet. An
+  unparseable or failing supervision call always becomes `wait` -
+  supervision must never kill a healthy child.
+- Every applied decision is visible three ways: the report's Supervisor
+  section (`[silence 30s] a1: nudge - ...`), the team panel and the `-p`
+  stderr line, and a `debug` log event. `aragon exec` emits it as an
+  additive `team` subtype `overseer` (`EXEC_SCHEMA_VERSION` unchanged).
+- New command `/team overseer on|off` (refused mid-dispatch, like every
+  other `/team` setting) and new config key `team.overseer`, also settable
+  as `aragon config set team.overseer false`. With the supervisor off - or
+  no fast tier - every path is byte-for-byte the pre-feature regime:
+  `subagentTimeoutMs` is a hard abort and silence is the child's own
+  watchdog.
+
+### 启动与缩窗不再误报 Frame diff lost sync
+
+- 启动即现的 "Frame diffing lost sync with the terminal and fell back to a
+  full repaint … `--no-diff-render`" 警告已消除：Ink 挂载/卸载经渲染 stdout 写出的
+  光标隐藏/恢复序列（`ESC[?25l` / `ESC[?25h`）由帧写入器直接透传——不进差分、
+  不失效缓存、不计 fallback，也不再消耗会话的首写豁免。启动序列恢复
+  "种子帧透传 → 首帧全量 → 之后纯 diff"。
+- 终端高度缩小（拖小窗口、改字号、面板重排）不再触发同一条警告：Ink 的
+  `clearTerminal` 整帧写入被差分器识别为 Ink 自身写法，透传并失效缓存但不计
+  fallback；该控制写同样不消耗首写豁免，其后的首个 log-update 帧仍按种子帧豁免，
+  下一帧自然全量重绘。
+- `/perf` 的 `fallbacks` 重新从 0 起步，"健康会话 fallbacks === 0" 的诊断信号
+  （AC-11）恢复可判。
+
+### Consistent TUI styling
+
+- Interactive sessions always use Unicode and default to truecolor, including
+  PowerShell sessions without terminal or UTF locale markers. Ink's actual color
+  output follows the same policy, with renderer state restored on exit.
+- Explicit color opt-outs keep Unicode borders and icons; the opening logo now
+  depends only on available space. Headless terminal detection is unchanged.
+- Reloading model settings preserves session display preferences. Syntax
+  highlighting follows the same color policy, and status icons use consistent
+  single-column glyphs to prevent narrow-frame overflow.
+- Hiding the editor caret while scrolling preserves draft geometry, preventing
+  a layout update loop when entering text above the full startup logo.
+- Register exit cleanup before mounting the application, so immediate exits and
+  initial render failures restore terminal and color state reliably. Failed
+  mounts no longer mark an auto-installed build as healthy.
+
+### Model context window
+
+- Discover context limits at startup and after connection changes without blocking
+  input. The status bar and compaction use the discovered limit; `/context` names
+  API versus catalog metadata. Unknown windows show `?`, not a fabricated 128k
+  capacity or percentage. Manual `contextWindow` overrides retain precedence.
+- Window overrides now apply to tail relief and compaction progress as well as
+  the gauge. Workers on different models/endpoints do not inherit the lead's
+  override. API-key changes refresh metadata, and ending a session cancels its
+  pending model queries. `/context` also hides unknown capacities/percentages.
+
+### TUI 输入与排队可靠性
+
+- Shift+Enter 与粘贴按输入顺序处理；普通 Enter 保持弹层兼容，混合输入最多提交一次，
+  余稿及拒绝提交的正文保留。结束输入流时完整排空，不泄漏内部控制标记。
+- 超限粘贴拒绝同一外部输入块的正文和 Enter，避免误提交旧稿；未闭合粘贴继续按正文消费。
+- 拖选后仅 Ctrl+C 复制；文字变化与丢失鼠标释放时取消无效高亮，避免卡住视口。
+- 固定 Queue 状态行按消息 ID 回执更新，支持窄屏、暂停与多条消息计数。
+- 保存和退出保留所有未发送全文；恢复先验证存档，旧 queued 作为警告展示且不自动重放。
 
 ### Removed
 
@@ -451,6 +483,30 @@ were written.
 
 ## Unreleased
 
+### Project index on Ctrl+I (bundled `project-indexer` skill)
+
+- The `project-indexer` skill now ships **bundled** with the package
+  (`<pkg>/skills/project-indexer`, read-only, alongside `skill-creator`): it
+  generates the `.claude-index/` navigation map and injects the Google-style
+  Clean Code Guidelines section into `CLAUDE.md`, adapted from the standalone
+  Claude Code skill (ask_user instead of AskUserQuestion; body condensed under
+  the 30 KB invocation budget with the four templates bundled as files).
+- New keybinding `Ctrl+I`: opens a Yes/No confirm that names every write
+  target, then dispatches `/skill:project-indexer` through the ordinary
+  command path - the indexing run is a normal agent turn whose tool calls
+  stream into the transcript. While a run is in flight the key warns instead
+  of queueing; with skills disabled or the skill shadowed it explains instead
+  of failing silently.
+- `Ctrl+I` is legacy-encoded as the Tab byte, so the stdin filter's two
+  translators (win32-input-mode on Windows, kitty CSI-u / modifyOtherKeys
+  elsewhere) now emit a distinct NUL-delimited `INDEX_KEY_FRAME` for it -
+  the same framing technique `Shift+Enter` uses. On terminals with neither
+  protocol the key keeps its legacy Tab meaning (completion).
+- The header names the key next to the detail toggle: `^I Index` collapsed,
+  `^I build index` in the `Ctrl+G` expanded state; hidden below 72 columns and
+  while an overlay is open. `/skill:project-indexer` and `/project-indexer`
+  remain available as typed commands.
+
 ### Added
 
 - **Drag the mouse to select text, and release to copy it.** Full-screen mode

package/README.md

@@ -406,7 +406,7 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/save [file]` | Save the session to JSON |
 | `/resume [file]` | Load a saved session |
 | `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
-| `/team [on\|off\|max <n>]` | Team subagents: status and the live roster, the on/off switch, the fan-out width |
+| `/team [on\|off\|max <n>\|overseer on\|off]` | Team subagents: status and the live roster, the on/off switch, the fan-out width, the dispatch supervisor |
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
@@ -436,6 +436,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。应用默认请求终端区分修饰键（Windows 用 win32-input-mode，macOS/Linux 用 kitty/modifyOtherKeys），Shift+Enter 在支持的终端开箱即用；不支持的终端用 Ctrl+J。参见 [终端设置](#terminal-setup-for-shiftenter) |
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
+| `Ctrl+I` | **Build the project index** (bundled `project-indexer` skill). Asks for confirmation, then runs as a normal agent turn that writes `.claude-index/` and updates `CLAUDE.md`. On terminals without keyboard enhancement `Ctrl+I` is the Tab byte and completes input instead |
 | `Esc` | Close an overlay or popup; otherwise ask for interruption confirmation. While idle, cancel pending auto-continuation |
 | `Esc` ×2 | Interrupt the run when pressed within 1.5 seconds. Other keys or closing a menu cancel the first press |
 | `Esc` again after interruption | **Force-stop** a run that is still stopping, kill foreground shell commands and return to `idle`; background services remain running |
@@ -1146,6 +1147,17 @@ subagents wrote the same file the header says so, phrased as a warning rather
 than a fact: the file list is derived from `write_file` / `edit_file`, so a
 write made through `bash` is invisible to it.
 
+**The dispatch supervisor.** A time ceiling on a subagent is an inspection
+trigger, not a death sentence — as long as the fast tier is enabled. Two soft
+timers per child (event silence and a wall clock) hand a bounded snapshot to the
+fast model, which decides: keep waiting, steer a nudge in, rebuild the child
+with an amended brief, or abandon it with a recorded reason. The budgets are
+structural, not settings — 4 inspections and 1 replacement per child per
+dispatch, after which the child runs under its own hard ceilings and the
+supervisor goes quiet. Every applied decision is recorded in the report's
+Supervisor section; `/team overseer off` (or no fast tier) restores the
+pre-supervisor regime exactly.
+
 **Talking to each other.** Subagents get two extra tools, `team_send` and
 `team_wait`. Messages are delivered by attaching them to the recipient's next
 tool result, so nobody has to poll and nobody's work is interrupted. The limits
@@ -1627,6 +1639,39 @@ A skill is a reusable expert procedure stored on disk: a directory containing a
 `scripts/` and `assets/`. The format matches Claude Code's, so an existing
 community skill directory works as-is.
 
+### Project index - `Ctrl+I`
+
+Two skills ship **bundled** with the package (`<pkg>/skills`, read-only):
+`skill-creator`, and `project-indexer` - a codebase indexer that generates a
+`.claude-index/` navigation map (project overview, feature map, file index,
+exported symbols) and injects a Google-style **Clean Code Guidelines** section
+into `CLAUDE.md` so future sessions inherit the project's code-quality
+thresholds.
+
+`Ctrl+I` is its dedicated keybinding. The flow is deliberately boring:
+
+1. A **Yes/No confirm** opens (what will be written is spelled out - the
+   dialog names `.claude-index/` and `CLAUDE.md` before anything happens).
+2. Approving dispatches `/skill:project-indexer` through the ordinary command
+   path, so the run is a normal agent turn: every `glob` / `read_file` /
+   `write_file` streams into the transcript as a tool card, `Esc`
+   interrupts it, and the follow-up configuration questions (exclusions,
+   priority directories, clean-code preset) arrive through the same `ask_user`
+   overlay any other turn uses.
+3. The header names the key: `^I Index` collapsed, `^I build index` once
+   `Ctrl+G` expands the detail row.
+
+An existing `.claude-index/config.md` is reused on rebuild. While the agent is
+running, `Ctrl+I` warns instead of queueing. `/skill:project-indexer` and
+`/project-indexer` work as typed commands too.
+
+> **Terminal support:** `Ctrl+I` is the same byte as `Tab` in legacy terminal
+> encoding. AragonAgent already asks for modified-key reporting at startup
+> (win32-input-mode on Windows, kitty/modifyOtherKeys elsewhere - the same
+> machinery that makes `Shift+Enter` work), and under those protocols the key
+> is distinguishable and the binding works. On a terminal that implements
+> neither, `Ctrl+I` simply behaves as `Tab`.
+
 ### Progressive disclosure
 
 This is the part that makes skills cheap enough to install a lot of:
@@ -1956,9 +2001,10 @@ env / `.env` → CLI flags**.
 | `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
 | `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |
 | `team.maxConcurrent` | `3` | Subagents in flight at once, clamped to `[1, 10]` and capped at `maxSubagents`. A separate knob because provider rate limits are a different constraint from context economics. |
-| `team.subagentTimeoutMs` | `0` | One subagent's wall clock before it is aborted, clamped to `[0, 1800000]`. `0` (the default) = no ceiling — a wedged subagent still dies on its own idle watchdog, exactly like the lead. |
+| `team.subagentTimeoutMs` | `0` | One subagent's wall clock, clamped to `[0, 1800000]`. With the supervisor off it is a hard abort; with it on (the default) a positive value is the **first wall-clock inspection** — the supervisor looks and decides instead of killing. `0` (the default) = no ceiling — a wedged subagent still dies on its own idle watchdog, exactly like the lead. |
 | `team.dispatchTimeoutMs` | `0` | The whole dispatch's wall clock (and the `task` tool timeout), clamped to `[0, 3600000]`. `0` (the default) = no ceiling; only Esc ends a dispatch early. |
 | `team.maxTurnsPerSubagent` | `0` | Runaway-loop cap, clamped to `[0, 100]`. `0` (the default) = no cap, matching the lead. A subagent stopped at a positive cap is reported as `stopped: turn cap reached`, with whatever it had produced. |
+| `team.overseer` | `true` | The dispatch supervisor: time ceilings on subagents become inspection triggers for a fast-tier supervisor that decides wait / nudge / replace / abandon instead of aborting. Needs the fast tier (`fast.enabled`); with the tier off or this `false`, children run under the legacy hard ceilings exactly. `/team overseer on\|off` flips it live, and it is read per dispatch. |
 | `todo.enabled` | `true` | Master switch for todo planning. `false` means the `todo_write` tool is never registered — `/todo on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
 | `todo.panel` | `true` | Render the right-hand rail. Independent of `todo.enabled` on purpose: a screen-reader user wants the planning discipline without the column, and the system prompt varies one sentence accordingly. |
 | `todo.followThrough` | `"notify"` | What happens when a run ends with steps left. `notify` says so and stops; `auto` continues the plan after a 3-second grace window, bounded by two structural limits (one fruitless attempt, 25 continuations per plan) that are deliberately **not** settings; `off` is silent. An unrecognized value falls back to `notify`. |

package/dist/agent/controller.js

@@ -14,6 +14,7 @@ import { createToolOutputStore, } from '../tools/tool-output-store.js';
 import { TeamRuntime } from '../team/runtime.js';
 import { createChildReviewer } from '../team/child-reviewer.js';
 import { TeamHumanQueue } from '../team/human-queue.js';
+import { createFastOverseerProvider } from '../team/overseer.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
@@ -354,6 +355,18 @@ export class AgentController {
                         })
                         : undefined,
                 },
+                // THE DISPATCH SUPERVISOR (team-overseer): the fast tier that powers the
+                // per-child reviewers also powers the supervisor one-shot decision
+                // calls. Same live-predicate discipline as review above - every
+                // this.fast read lives in a closure that only runs from inside a
+                // dispatch, long after the wiring exists.
+                overseer: createFastOverseerProvider({
+                    getConfig: () => this.config,
+                    hasKey: (id, role) => this.hasApiKey(id, role),
+                    getApiKey: (id, role) => this.resolveKey(id, role),
+                    complete: (providerId, llmRequest) => this.fast.completeViaFastRegistry(providerId, llmRequest),
+                    available: () => this.fast?.available() === true,
+                }),
                 providerRegistry: this.providerRegistry,
                 getCwd: () => this.cwd,
                 getMode: () => this.effectiveMode,

package/dist/agent/headless.js

@@ -116,6 +116,13 @@ export async function runHeadless(controller, prompt, options = {}) {
             }
             return;
         }
+        if (event.type === 'overseer') {
+            // ONE LINE PER DECISION, on stderr with the rest of the team feed:
+            // a machine consumer reads the JSON events; a human watching a long
+            // dispatch reads who the supervisor touched and why.
+            err.write(`[team] supervisor ${event.label}: ${event.decision.action} (${event.trigger}) ${event.decision.reason}\n`);
+            return;
+        }
         if (event.type === 'dispatch_end') {
             const ok = event.outcome.runs.filter((r) => r.phase === 'done' && !r.error).length;
             err.write(`[team] done ${ok}/${event.outcome.runs.length} ok` +

package/dist/commands/builtins.js

@@ -254,7 +254,7 @@ const COMMANDS = [
     },
     {
         name: 'team',
-        description: 'Team subagents: status | on | off | max <n>',
+        description: 'Team subagents: status | on | off | max <n> | overseer on|off',
         /**
          * `/team on` CANNOT turn team mode on in a session that started without it,
          * and this command must not pretend otherwise (§4.5 / D-17 / P0-2).
@@ -294,7 +294,7 @@ const COMMANDS = [
                     ? `\nRunning: ${snapshot.runs.map((r) => `${r.label} (${r.phase})`).join(', ')}`
                     : '';
                 ctx.notify('info', `Team mode: ${state}. Max subagents: ${cfg.maxSubagents}, ` +
-                    `concurrent: ${cfg.maxConcurrent}.${roster}`);
+                    `concurrent: ${cfg.maxConcurrent}, supervisor: ${cfg.overseer ? 'on' : 'off'} (needs the fast tier).${roster}`);
                 return;
             }
             if (verb === 'on' || verb === 'off') {
@@ -331,7 +331,22 @@ const COMMANDS = [
                 ctx.toast('success', `Max subagents set to ${applied.maxSubagents}.`);
                 return;
             }
-            ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>].`);
+            if (verb === 'overseer') {
+                if (value !== 'on' && value !== 'off') {
+                    ctx.notify('warn', 'Usage: /team overseer on|off');
+                    return;
+                }
+                // Read LIVE per dispatch by the runtime, so no rebuild is needed - the
+                // same reason this command does not touch the tool array (its own header
+                // comment). Clamped by `setTeamConfig` and again on the persist path.
+                const applied = controller.setTeamConfig({ overseer: value === 'on' });
+                ctx.persistConfig({
+                    team: { overseer: applied.overseer },
+                });
+                ctx.toast('success', `Dispatch supervisor ${applied.overseer ? 'on' : 'off'}.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>|overseer on|off].`);
         },
     },
     {

package/dist/commands/index-build.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Ctrl+I project-index trigger (bundled `project-indexer` skill).
+ *
+ * WHY A MODULE AND NOT INLINE IN `App.tsx`. `App.tsx` is a documented
+ * historical oversize file (see `.claude-index/config.md`); the convention
+ * those entries record is that a feature only wires into it and keeps its
+ * logic in a small named module. Everything here is pure and unit-tested:
+ * the key handler in `App.tsx` guards, confirms, and dispatches; this file
+ * owns the words and the names.
+ *
+ * THE TRIGGER IS A SKILL COMMAND, NOT A REIMPLEMENTATION. Ctrl+I dispatches
+ * `/skill:project-indexer <args>` through the ordinary command path, so the
+ * load/activate/queue-frame/submit lifecycle is the SAME one a typed command
+ * gets, and the whole indexing run streams into the transcript like any
+ * agent turn. All strings here are ASCII-only: `commands/` is inside the
+ * `glyphs.test.ts` scan scope and every byte reaches a terminal.
+ */
+/** The bundled skill Ctrl+I runs. Bundled skills are read-only by scope. */
+export declare const INDEX_SKILL_NAME = "project-indexer";
+/** True when a previous run left a main index file behind (rebuild, not first build). */
+export declare function hasProjectIndex(cwd: string): boolean;
+/**
+ * Args handed to `/skill:project-indexer`. They land in the skill body's
+ * `$ARGUMENTS` placeholder, so the model sees WHY the turn started - a
+ * confirmed keypress, not a typed request - and skips asking "proceed?" a
+ * second time (the skill's own edge-case list says exactly that).
+ */
+export declare function indexBuildInvocationArgs(hasExistingIndex: boolean): string;
+export interface IndexConfirmInput {
+    cwd: string;
+    /** True when `.claude-index/index.md` already exists (rebuild, not first build). */
+    hasExistingIndex: boolean;
+}
+/**
+ * The Yes/No dialog body. It names WHAT WILL BE WRITTEN - an index run is a
+ * batch of file writes the user never typed, and the one question a confirm
+ * gate must answer is "what did I just agree to?".
+ */
+export declare function buildIndexConfirmSummary(input: IndexConfirmInput): string;

package/dist/commands/index-build.js

@@ -0,0 +1,61 @@
+/**
+ * Ctrl+I project-index trigger (bundled `project-indexer` skill).
+ *
+ * WHY A MODULE AND NOT INLINE IN `App.tsx`. `App.tsx` is a documented
+ * historical oversize file (see `.claude-index/config.md`); the convention
+ * those entries record is that a feature only wires into it and keeps its
+ * logic in a small named module. Everything here is pure and unit-tested:
+ * the key handler in `App.tsx` guards, confirms, and dispatches; this file
+ * owns the words and the names.
+ *
+ * THE TRIGGER IS A SKILL COMMAND, NOT A REIMPLEMENTATION. Ctrl+I dispatches
+ * `/skill:project-indexer <args>` through the ordinary command path, so the
+ * load/activate/queue-frame/submit lifecycle is the SAME one a typed command
+ * gets, and the whole indexing run streams into the transcript like any
+ * agent turn. All strings here are ASCII-only: `commands/` is inside the
+ * `glyphs.test.ts` scan scope and every byte reaches a terminal.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** The bundled skill Ctrl+I runs. Bundled skills are read-only by scope. */
+export const INDEX_SKILL_NAME = 'project-indexer';
+/** True when a previous run left a main index file behind (rebuild, not first build). */
+export function hasProjectIndex(cwd) {
+    try {
+        return existsSync(join(cwd, '.claude-index', 'index.md'));
+    }
+    catch {
+        // A cwd that cannot be probed simply has no index to reuse.
+        return false;
+    }
+}
+/**
+ * Args handed to `/skill:project-indexer`. They land in the skill body's
+ * `$ARGUMENTS` placeholder, so the model sees WHY the turn started - a
+ * confirmed keypress, not a typed request - and skips asking "proceed?" a
+ * second time (the skill's own edge-case list says exactly that).
+ */
+export function indexBuildInvocationArgs(hasExistingIndex) {
+    return hasExistingIndex
+        ? 'The user pressed Ctrl+I and confirmed. Rebuild the project index for this workspace now, reusing the existing .claude-index/config.md preferences.'
+        : 'The user pressed Ctrl+I and confirmed. Build the project index for this workspace now, asking the configuration questions first.';
+}
+/**
+ * The Yes/No dialog body. It names WHAT WILL BE WRITTEN - an index run is a
+ * batch of file writes the user never typed, and the one question a confirm
+ * gate must answer is "what did I just agree to?".
+ */
+export function buildIndexConfirmSummary(input) {
+    const action = input.hasExistingIndex ? 'Rebuild' : 'Build';
+    const existing = input.hasExistingIndex
+        ? '\nThe existing .claude-index/config.md preferences are reused.'
+        : '\nThe bundled skill asks a few configuration questions first.';
+    return (`${action} the project index for this workspace?\n` +
+        `\nRuns the bundled "${INDEX_SKILL_NAME}" skill as a normal agent turn:` +
+        `\n- scans the workspace (exclusions apply), extracts exported symbols` +
+        `\n- writes .claude-index/index.md and .claude-index/config.md` +
+        `\n- updates CLAUDE.md (index section + Clean Code Guidelines)` +
+        `${existing}` +
+        `\nWorkspace: ${input.cwd}` +
+        `\nEvery step is visible in the transcript; Esc interrupts.`);
+}

package/dist/config/cli-commands.d.ts

@@ -20,7 +20,7 @@ export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "
  * switch falls through every case, writes nothing, and still prints
  * `Set team.enabled = false`.
  */
-export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent"];
+export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent", "team.overseer"];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
  * (llm-api-retry-backoff §8.2).

package/dist/config/cli-commands.js

@@ -43,6 +43,7 @@ export const TEAM_CONFIG_SET_KEYS = [
     'team.subagentTimeoutMs',
     'team.dispatchTimeoutMs',
     'team.maxTurnsPerSubagent',
+    'team.overseer',
 ];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
@@ -199,6 +200,8 @@ export function applyTeamConfigSet(key, value) {
             return patch(clampOne('dispatchTimeoutMs'));
         case 'team.maxTurnsPerSubagent':
             return patch(clampOne('maxTurnsPerSubagent'));
+        case 'team.overseer':
+            return patch({ overseer: isTrue(value) });
         default:
             return null;
     }

package/dist/config/schema.d.ts

@@ -308,6 +308,11 @@ export interface TeamConfig {
      * ceiling: a subagent runs until it finishes or is aborted, exactly like
      * the lead, whose only in-run ceiling is the event-silence idle watchdog
      * a child already keeps. A wedged child still dies on its OWN watchdog.
+       *
+       * WITH `team.overseer` ON (the default) this is the FIRST wall-clock
+       * INSPECTION point, not a hard abort: the supervisor looks and decides
+       * (wait / nudge / replace / abandon), so a slow-but-healthy child is no
+       * longer killed at an arbitrary wall clock.
      */
     subagentTimeoutMs: number;
     /**
@@ -323,6 +328,18 @@ export interface TeamConfig {
      * the deliberate trade of "subagents as capable as the main agent".
      */
     maxTurnsPerSubagent: number;
+    /**
+     * The dispatch supervisor (team-overseer): time ceilings on children
+     * become inspection triggers for a fast-tier supervisor that decides
+     * wait / nudge / replace / abandon, instead of aborts. Default TRUE.
+     *
+     * READ PER DISPATCH. With the supervisor off (or no fast tier), children
+     * run exactly the pre-feature regime: `subagentTimeoutMs` is a hard abort
+     * and silence is the child's own watchdog. With it ON,
+     * `subagentTimeoutMs > 0` is the FIRST wall-clock inspection point, not
+     * a death sentence.
+     */
+    overseer: boolean;
 }
 /**
  * The requirement's ceiling on the fan-out (R-g).
@@ -596,10 +613,13 @@ export interface CompactionConfig {
      * (context-auto-compaction-hardening §3.4 / W3). Default TRUE.
      *
      * IT REVERSES D-15, WHOSE PREMISE IS MEASURABLY FALSE at the configured bounds:
-     * `team.maxTurnsPerSubagent` is 24 and `team.dispatchTimeoutMs` is 900 000, and
-     * 24 turns over fifteen minutes is the same profile as the lead run this
-     * feature exists for. When a child overflows today its history is discarded and
-     * the lead receives one partial sentence for the whole dispatch.
+     * D-15 measured `team.maxTurnsPerSubagent` 24 and `team.dispatchTimeoutMs`
+     * 900 000, where 24 turns over fifteen minutes is already the same profile
+     * as the lead run this feature exists for — and the parity defaults of
+     * 2ff15a9c3 later removed both ceilings (0 = no turn cap, no wall clock),
+     * which makes the premise falser still, not truer. When a child overflows
+     * today its history is discarded and the lead receives one partial sentence
+     * for the whole dispatch.
      *
      * `false` REPRODUCES ROUND 1 EXACTLY: `subagent.ts` spreads no `contextManager`
      * key at all, so the child's loop gate tests an absent field.

package/dist/config/schema.js

@@ -452,6 +452,9 @@ export const DEFAULT_TEAM_CONFIG = {
     subagentTimeoutMs: 0,
     dispatchTimeoutMs: 0,
     maxTurnsPerSubagent: 0,
+    // The dispatch supervisor, default ON (team-overseer): ceilings become
+    // inspections; the fast-tier supervisor decides what to do.
+    overseer: true,
 };
 const SUBAGENTS_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
 const CONCURRENT_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
@@ -482,6 +485,7 @@ export function clampTeamConfig(raw) {
         subagentTimeoutMs: clampIntAllowingZero(src.subagentTimeoutMs, DEFAULT_TEAM_CONFIG.subagentTimeoutMs, SUBAGENT_TIMEOUT_RANGE),
         dispatchTimeoutMs: clampIntAllowingZero(src.dispatchTimeoutMs, DEFAULT_TEAM_CONFIG.dispatchTimeoutMs, DISPATCH_TIMEOUT_RANGE),
         maxTurnsPerSubagent: clampIntAllowingZero(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
+        overseer: bool(src.overseer, DEFAULT_TEAM_CONFIG.overseer),
     };
 }
 export const DEFAULT_TODO_CONFIG = {

package/dist/exec/events.d.ts

@@ -193,7 +193,10 @@ export interface ExecTodoEvent {
 export interface ExecTeamEvent {
     type: 'team';
     sessionId: string;
-    subtype: 'dispatch_start' | 'agent_update' | 'dispatch_end';
+    subtype: 'dispatch_start' | 'agent_update' | 'dispatch_end' | 'overseer';
+    action?: string;
+    trigger?: string;
+    reason?: string;
     label?: string;
     phase?: string;
     description?: string;

package/dist/exec/runner.js

@@ -707,6 +707,19 @@ export class ExecRunner {
                 total: runs.length,
                 aborted: event.outcome.aborted,
             });
+            return;
+        }
+        if (event.type === 'overseer') {
+            this.emit({
+                type: 'team',
+                sessionId: this.sessionId,
+                subtype: 'overseer',
+                label: event.label,
+                action: event.decision.action,
+                trigger: event.trigger,
+                reason: event.decision.reason,
+            });
+            return;
         }
     }
 }

package/dist/input/csiu-keys.js

@@ -24,7 +24,7 @@
  * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
  * Pure: no node/React imports.
  */
-import { ENTER_NEWLINE_FRAME } from './limits.js';
+import { ENTER_NEWLINE_FRAME, INDEX_KEY_FRAME } from './limits.js';
 /** Enable / disable the two CSI-u report modes (posix side). */
 export const CSI_U_ENABLE = '\x1b[>1u\x1b[>4;2m';
 export const CSI_U_DISABLE = '\x1b[<u\x1b[>4m';
@@ -111,8 +111,19 @@ export function translateCsiUKey(key) {
         return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
     if (key.code === 27)
         return alt ? '\x1b\x1b' : '\x1b';
-    if (key.code === 9)
+    if (key.code === 9) {
+        // A modified Tab codepoint (modifyOtherKeys shape) mirrors the VK_TAB
+        // decision in win32-input-mode.ts: ctrl (without shift/alt) is the
+        // project-indexer trigger frame, shift stays Shift+Tab.
+        if (ctrl && !shift && !alt)
+            return INDEX_KEY_FRAME;
         return shift ? '\x1b[Z' : '\t';
+    }
+    // Ctrl+I under kitty disambiguate arrives as codepoint 105 with the ctrl
+    // modifier; the generic printable branch below would fold it back onto the
+    // legacy Tab byte, which is exactly the ambiguity the frame exists to break.
+    if (key.code === 105 && ctrl && !shift && !alt)
+        return INDEX_KEY_FRAME;
     if (key.code === 127) {
         // POST-normalisation bytes, same rationale as VK_BACK in win32-input-mode.
         if (alt)