@selesai/code 0.8.6 → 0.8.8

package/dist/extensions/pi-subagents/UPSTREAM-V0.50-MAPPING.md

@@ -0,0 +1,172 @@
+# Upstream v0.50.0 merge mapping
+
+Selesai fork of `nicobailon/pi-subagents` updated from v0.48.0 to upstream **v0.50.0**
+(v0.49.0 + v0.50.0). This file is the exact reconciliation map: for every changed file,
+what upstream did, what the fork had done, and what the merged tree contains. Regenerate
+on the next upstream merge (the merge base is always the previously vendored tag).
+
+Merge method: no shared git history exists (the fork vendors upstream as squashed
+commits), so the merge was a file-level 3-way: base = upstream v0.48.0, ours = fork at
+HEAD-before-merge, theirs = upstream v0.50.0. For each file, "theirs" was taken as the
+new base and the fork's v0.48.0-based hunks were re-applied; hunks that no longer
+matched were resolved by hand (listed below).
+
+Result: `tsc --noEmit` clean, `tsgo` clean for the whole host monorepo, 2060 unit tests
+pass (3 skipped), 777 integration tests pass.
+
+## Numbers
+
+| Set | Count | Handling |
+| --- | --- | --- |
+| Files changed by both fork and upstream (src) | 37 | 3-way merge, hunks re-applied |
+| Files changed only by upstream (src) | 33 | v0.50.0 adopted wholesale (+ branding on 3) |
+| Files changed only by the fork (src) | 38 | fork versions kept |
+| Fork "new" files | 6 | exist **verbatim** in upstream v0.50.0 (our features were upstreamed) |
+| Upstream-only test changes | 48 files | v0.50.0 adopted |
+| Fork-only test changes | 80 files patched, 7 new files | fork hunks re-applied; 12 files took fork versions, then fixed |
+
+## Fork features that upstream v0.50.0 already contains verbatim
+
+These six fork additions were merged into upstream before v0.50.0; the merged tree uses
+the upstream copies (identical content):
+
+- `src/slash/inline-subagents.ts` (#agent-name inline invocation + autocomplete)
+- `src/workflows/workflow-auto-relaunch.ts` (relaunch decision module — note: upstream
+  ships the module but **does not wire it**; the fork wires it, see below)
+- `src/agents/task-aware-routing.ts`
+- `src/extension/chain-validation.ts`
+- `src/shared/env.ts` (PI_SUBAGENT* → SELESAI_SUBAGENT* legacy shim)
+- `src/shared/session-lineage.ts`
+
+## Both-changed files (37) — resolutions
+
+Base for every file is v0.50.0; fork hunks were re-applied. Hand-resolved files:
+
+| File | Upstream (v0.48→v0.50) | Fork (vs v0.48) | Resolution |
+| --- | --- | --- | --- |
+| `src/extension/index.ts` | Orca tabs, external jobs, async-status snapshot, detach shortcut, resumable retained children, result-index reload work | branding; lineage goal continuation; resources_discover prompt paths; adoptedActive capacity; formatActiveWorkflowSummary; resetSessionState(previousSessionFile) | v0.50.0 + fork hunks; hand-added: lineage/adoption bits in `resetSessionState`, `formatActiveWorkflowSummary` definition (was referenced but missing), `resources_discover`, adopted-job capacity accounting |
+| `src/extension/public-execution.ts` | structured single-child (converts `{agent,task}` → `runs.run("main",…)`), rejects legacy top-level chain/tasks | restores chain/tasks/clarify as first-class | v0.50.0 + fork policy: `clarify` rejected only with workflowScript, top-level `chain`/`tasks` pass through, `schedule.create` accepts direct execution fields, single-child conversion kept (fork executor is v0.50's) |
+| `src/extension/schemas.ts` | task param, toolTimeoutMs, debug.run descriptions, agentContract integer bounds (#1095) | top-level `chain`/`tasks`/`clarify`, chatProgress 5-value enum, legacyChainControls trim comment | v0.50.0 + fork's top-level `chain`/`tasks`/`clarify` + 5-value chatProgress enum; v0.50's bounds fix and new descriptions kept |
+| `src/extension/tool-description.ts` | rewrote FULL/COMPACT text (single-child + retained resumability) | fork text describing all four modes | fork's FULL/COMPACT text kept (matches fork schema), v0.50's resumable-children wording folded in |
+| `src/agents/agents.ts` | `tools: "inherit"`, model validation | branding, extra builtins, home-dir guard, extra-agent-dirs env | v0.50.0 + fork branding/builtins (fork's splitToolList was already upstreamed) |
+| `src/runs/background/retained-children.ts` | resumable/not-resumable states | `listRetainedChildren` accepts multiple session ids | v0.50.0 + signature widened to `string \| string[]` (lineage callers) |
+| `src/runs/foreground/subagent-executor.ts` | result-files/async-status refactors, detached children as paused | auto-relaunch wiring (fan-out budget exhaustion) | v0.50.0 + re-wired fork auto-relaunch loop around `runWorkflowScript` (async path), with cap-exhaustion → failed run + `relaunchNote` summaries |
+| `src/runs/shared/llm-intent-arbiter.ts` | confidence levels, registry-method auth call, fail-closed >8k | simpler arbitration, head+tail truncation | v0.50.0 wholesale (strictly better) + `SELESAI_SUBAGENTS_LLM_INTENT_ARBITER` env rebrand |
+| `src/runs/shared/model-fallback.ts` | `resolveRequiredSubagentModelCandidate` (rejects unknown models, #1093) | same-model transient retry (503/429/no-body/econnreset), `MODEL_RETRY_DELAYS_MS`, `formatModelRetryNote` | both: v0.50.0's strict resolution + fork's retry schedule/exports (used by runner/execution) |
+| `src/shared/types.ts` | async-status snapshot types, artifact default "session" | `AsyncJobState.adopted`, artifact default "project" + `.pi-subagents` comment | v0.50.0 + `adopted` flag; fork's `DEFAULT_ARTIFACT_CONFIG.dir = "project"` kept (deliberate fork behavior) |
+| `src/shared/artifacts.ts` | packaging-warning work | `getArtifactsDir`/`getChainRunsDir` default "project" | v0.50.0 + fork default "project" restored |
+| `src/runs/background/result-watcher.ts` | indexed result inbox, session/observer/tool-call indexing | lineage adoption of old-session results | v0.50.0 + fork lineage logic, plus a fork-specific flat-file scan bounded to the adoption window (v0.50's scan only reads the index) |
+| `src/slash/slash-commands.ts` | detach command/shortcut, live-state work | export `launchSlashSubagent` (host workflow extension imports it), branding | v0.50.0 + `export` on `launchSlashSubagent` + import rebrand + inline invocation import |
+| `src/slash/slash-live-state.ts` | structured single-child initial results | `buildWorkflowInitialResult` + workflow update path | v0.50.0 + fork's workflow preview builder (+ `background` flag for async) |
+| `src/tui/fleet-status.ts` | nested-run tree (#1086), spacing config | nested rows (older own implementation) | v0.50.0 wholesale + import rebrand (upstream's tree supersedes fork's) |
+| `src/watchdog/review.ts`, `src/watchdog/permission-arbiter.ts`, `src/runs/foreground/prompt-audit.ts` | `agentStreamOptions()` host-API adapter | bare `streamFn` + auth | v0.50.0 wholesale + `@selesai/code` import rebrand (agentStreamOptions emits both `streamFn` and `streamFunction`, compatible with host pi-agent-core 0.84.1) |
+
+Remaining both-changed files (20) merged mechanically: fork hunks re-applied over v0.50.0
+with no conflicts — `extension/config.ts`, `extension/rpc.ts`, `intercom/native-supervisor-channel.ts`,
+`runs/background/{async-execution, async-job-tracker, async-status, run-id-resolver, run-status,
+scheduled-runs, subagent-runner, subagent-wait}.ts`, `runs/foreground/{chain-execution,
+execution}.ts`, `runs/shared/{nested-events, subagent-prompt-runtime}.ts`,
+`slash/slash-live-state.ts` (see above), `tui/{fleet, fleet-transcript, render}.ts`,
+`workflows/chat-progress.ts`.
+
+## Upstream-only files (33 src) — adopted wholesale
+
+v0.50.0 content taken as-is, then the fork branding transform applied where tokens
+appeared. Only three needed it:
+
+- `src/runs/shared/tool-timeout.ts` — `TOOL_TIMEOUT_ENV` → `SELESAI_SUBAGENT_TOOL_TIMEOUT_MS`, reads via `readSubagentEnv` (PI_ fallback)
+- `src/runs/shared/orca-progress-tabs.ts` — `PI_SUBAGENT_ORCA_BINARY` → `SELESAI_SUBAGENT_ORCA_BINARY` via `readSubagentEnv`
+- `src/runs/background/async-status-snapshot.ts` — widget prefix → `SELESAI_SUBAGENT_ASYNC_JSON:`
+
+The other 30 (agent-serializer, api/external-runs, api/preflight, herdr/*, intercom-bridge,
+missions/goal-driver, missions/store, result-files, active-*-capacity/index, async-resume,
+chain-root-attachment, completion-replay, fleet-view, resume-guidance, stale-run-reconciler,
+wait-completions, async-dismiss-action, completion-guard, external-cli-runner, parallel-utils,
+subagent-control, subagent-startup-retry, agent-stream-options, display-text, node-executable,
+scripted-workflow) are upstream's latest with no fork content to preserve.
+
+## Fork-only files (38 src) — kept
+
+Fork versions kept (upstream did not touch them): agent-management, agent-memory,
+agent-refinements, control-notices, doctor, fanout-child, steering-notices, profiles,
+notify, wait-config/wait-subscriptions/wait-tool, chain-clarify, foreground-history,
+capability-ceiling, permissions, pi-args, pi-spawn, run-fanout-budget,
+runtime-acknowledged-extensions, structured-output, tool-availability, tool-budget,
+worktree, fork-context, utils, prompt-workflows (`/chain` `/parallel` `/run-chain`
+`/chain-prompts`), selector, slash-bridge, subagents-admin, render-helpers,
+watchdog/{change-signature, child-status, model-selection, register-child, register-main,
+runtime, tool-actions}.
+
+## Deliberate fork-vs-upstream behavior decisions (the "how far" answer)
+
+Kept as fork behavior:
+
+1. **Execution surface** — top-level `chain` / `tasks` / `clarify` remain first-class
+   alongside `{ agent, task }` and `workflowScript`. Upstream v0.50.0 only exposes
+   structured single-child + workflowScript at the top level; our schemas, public
+   boundary, tool text, and skill docs advertise all four modes.
+2. **Artifact default** — `DEFAULT_ARTIFACT_CONFIG.dir = "project"` (cwd `.pi-subagents/`).
+   Upstream moved the default to "session" (#1062) so worktrees stay clean; the fork
+   keeps project-scoped artifacts and gitignores `.pi-subagents/` subdirs. Consequence:
+   a worktree with artifacts is not `git status`-clean; the upstream worktree-clean test
+   is adapted to expect exactly `.pi-subagents/`.
+3. **Mission storage** — upstream relocates automatic mission records out of project
+   worktrees (`<agentDir>/missions/projects/<hash>`); adopted as-is (fork's
+   `.pi-subagents/missions` was runtime state, not load-bearing).
+4. **Workflow auto-relaunch wiring** — upstream ships the decision module only; the fork
+   wires `config.maxWorkflowAutoRelaunches` into the async workflow loop with fresh
+   fan-out budgets per relaunch and a failed-run outcome at the cap.
+5. **Same-model transient retry** — fork's `MODEL_RETRY_DELAYS_MS` retry schedule on
+   503/429/no-body/econnreset, in addition to upstream's fallback-model switching.
+6. **Lineage carry-over** — upstream adopted the fork's session-lineage machinery; the
+   fork additionally (a) counts adopted jobs against the per-session active async cap,
+   (b) labels adopted jobs in carry-over summaries, and (c) scans flat result files
+   during the adoption window (upstream only scans its indexed inbox).
+7. **Branding** — `@selesai/code` host import, `~/.selesai` config dirs, `.pi-subagents`
+   runtime dir, `SELESAI_SUBAGENT*` / `SELESAI_SUBAGENTS_*` env vars with legacy `PI_`
+   fallback, extra builtin agents (architect, builder, commentator, explorer, recapper),
+   `SELESAI_SUBAGENT_EXTRA_AGENT_DIRS`, home directory never treated as a project root.
+
+Adopted as upstream behavior (fork's prior code superseded):
+
+1. Structured single-child converts to a `runs.run("main", …)` workflow internally.
+2. Generic `intercom` tool removed from supervisor coordination (#1107); ceiling audit
+   removes only `write` + `contact_supervisor`.
+3. `needs_attention` escalation for repeated mutating tool failures (was
+   `active_long_running` in the fork).
+4. `tools: "inherit"` builtin overrides, model-registry validation before spawn (#1093),
+   `agentContract.version` integer bounds (#1095).
+5. Retained-children resumability states, detached workflow children shown as paused.
+6. Result inbox indexing, async-status snapshots, Orca progress tabs, external-job
+   FleetView API, foreground detach shortcut, per-tool-call timeouts, debug.run.
+
+## Non-src mapping
+
+| Area | Resolution |
+| --- | --- |
+| `package.json` / `package-lock.json` | v0.50.0 (version 0.50.0, no new deps) + fork description + `@selesai/code` renames |
+| `CHANGELOG.md` | v0.50.0 changelog + branding transform + rewritten "Selesai fork (0.50.0)" section |
+| `README.md` | v0.50.0 + branding + fork's 12-row builtin-agent table |
+| `docs/*.md` (9 files) | v0.50.0 + mechanical branding transform (fork doc delta was pure branding) |
+| `skills/pi-subagents/SKILL.md` | fork version (upstream didn't change it) |
+| `skills/…/references/*.md` (4 files) | 3-way: v0.50.0 base + fork hunks; hand-added fork's Chain/Parallel execution sections and technique sections (context-build, handoff-plan) |
+| `agents/*.md` | upstream's oracle/reviewer/scout/worker/delegate updates + fork's researcher (Selesai-custom) + fork's architect/builder/commentator/explorer/recapper |
+| `prompts/*.md` | upstream's 5 + fork's parallel-context-build / parallel-handoff-plan |
+| `test/` | v0.50.0 base + fork hunks; 12 behavioral files took fork versions, then adjusted to merged behavior (single-child conversion, `needs_attention`, mission store location, `.pi-subagents`/`.selesai` paths, `SELESAI_*` env names, worktree-clean exception); 7 fork test files copied |
+
+## Test adjustments made after the merge (merged behavior wins)
+
+- `agent-overrides/agent-frontmatter/index-child-registration/pi-coding-agent-dir` —
+  `.selesai` paths and `SELESAI_CODING_AGENT_DIR` (v0.50 tests still used `.pi`).
+- `async-execution` — capability audit removes `["write", "contact_supervisor"]` (no `intercom`).
+- `external-cli-runner` — `sessionId: "session-external"` (v0.50 result-files requirement).
+- `orca-progress-tabs` — jiti path via `import.meta.resolve`, `SELESAI_*` env.
+- `single-execution` — live-activity uses `needs_attention`; detach test expects
+  `/run detaches: detached/`; mission tests rewritten to upstream's agent-dir store
+  (`resolveMissionStoreLocation`/`missionStatePath`); worktree-clean test expects
+  `.pi-subagents/` (fork artifact default); mutating-failure escalation → `needs_attention`.
+- `public-execution` / `schemas` / `slash-*` / `mission-lifecycle` / `builtin-agent-documentation`
+  — expectations aligned with merged surface (single→workflowScript conversion, four-mode
+  schema, "Workflow running." initial slash message, mode "workflow" snapshots,
+  `.pi-subagents` mission paths, 12-row README builtin table).
+- `tool-timeout` / `orca` unit tests — `SELESAI_*` env with `PI_` fallback assertions.

package/dist/extensions/pi-subagents/agents/oracle.md

@@ -2,7 +2,7 @@
 name: oracle
 aliases: advisor
 description: High-context decision-consistency oracle that protects inherited state and prevents drift
-tools: read, grep, find, ls, bash, intercom
+tools: read, grep, find, ls, bash
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -16,9 +16,11 @@ Your primary job is to prevent the main agent from making hidden, conflicting, o
 
 Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
 
-If you need clarification from the main agent and runtime bridge instructions are present, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
+If the task is framed as asking or consulting the oracle, treat it as a live consultation unless the parent explicitly requests a one-shot report. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
 
-Do not send routine completion handoffs. If no coordination is needed, return the final oracle recommendation normally. Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target.
+If you need clarification from the main agent and bridge instructions provide `contact_supervisor`, use it with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
+
+Do not send routine completion handoffs. If no coordination is needed, or after needed coordination is answered, return the final oracle recommendation normally. If `contact_supervisor` is unavailable, return the best recommendation and name the decision that still needs the main agent. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
 
 Core responsibilities:
 - reconstruct inherited decisions, constraints, and open questions from the context
@@ -39,8 +41,8 @@ What you do not do by default:
 
 Working rules:
 - Use `bash` only for inspection, verification, or read-only analysis.
-- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
-- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` before continuing.
+- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` when bridge instructions provide that tool. If no supervisor channel is available, return the best recommendation and name the unresolved decision instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` when bridge instructions provide that tool. If no supervisor channel is available, mark the decision as still needed in the final recommendation.
 - When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
 - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
 

package/dist/extensions/pi-subagents/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
-tools: read, grep, find, ls, intercom
+tools: read, grep, find, ls
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -62,7 +62,7 @@ Review a PR or issue by understanding the context, then verifying:
 ## Supervisor coordination
 If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
 
-Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
+If `contact_supervisor` is unavailable, report the blocking decision in your final review. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
 
 ## Review output format
 Structure your findings clearly:

package/dist/extensions/pi-subagents/agents/scout.md

@@ -1,7 +1,7 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff
-tools: read, grep, find, ls, bash, write, intercom
+tools: read, grep, find, ls, bash, write
 thinking: low
 systemPromptMode: replace
 inheritProjectContext: true

package/dist/extensions/pi-subagents/agents/worker.md

@@ -22,7 +22,7 @@ The builtin worker uses a strict tool allowlist. It does not inherit ambient ext
 
 If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
 
-If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. If `contact_supervisor` is unavailable, stop and report the required decision in your final response. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
 
 Default responsibilities:
 - validate the task or approved direction against the actual code

package/dist/extensions/pi-subagents/docs/configuration.md

@@ -24,9 +24,9 @@ By default, project settings resolve from the nearest parent directory that cont
 { "toolDescriptionMode": "compact" }
 ```
 
-Controls the parent-facing `subagent` tool description registered at startup. `full` is the default. `compact` keeps the execution modes, async/`subagent_wait` guidance, child-safety boundary, management/action split, one-writer review guidance, and artifact/status essentials with less prompt bloat.
+Controls the parent-facing `subagent` tool description registered at startup. `compact` is the default. `full` keeps the full execution, management/control, and async guidance with more prompt bloat.
 
-`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.selesai/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Selesai after changing the mode or custom file.
+`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.selesai/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the compact description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Selesai after changing the mode or custom file.
 
 ## `legacyChainControls`
 
@@ -44,6 +44,61 @@ Defaults to `false`. The default registered model-facing tool schema and descrip
 
 Controls the `subagent` tool result shown inline in chat. The default, `"rich"`, shows live child activity and expands to detailed output. `"summary"` keeps the inline result at one stable row for running, completed, failed, stopped, and paused runs; it does not animate, show elapsed time, preview child output, or change when Selesai's expand key is pressed. FleetView remains available for live progress and detailed inspection.
 
+## `mainWindowRenderer`
+
+```json
+{
+  "mainWindowRenderer": {
+    "horizontalSpacing": 0,
+    "compactResultMaxLines": 4
+  }
+}
+```
+
+Controls only the main chat `subagent` call/result renderer. It does not change child execution, orchestration, FleetView, artifacts, transcripts, or model-facing content.
+
+`horizontalSpacing` is an integer from `0` to `4`. The default preserves current spacing. Set it to `0` to remove the extra spaces before compact result details and between parts of the call row.
+
+`compactResultMaxLines` is a positive integer. It caps only collapsed rich-result rows and adds an expand hint when rows are hidden. Expanded output remains uncapped.
+
+With `"summary"`, a tool result looks like this:
+
+```text
+✓ reviewer · completed
+```
+
+## `foregroundDetachShortcut`
+
+```json
+{ "foregroundDetachShortcut": "ctrl+b" }
+```
+
+Optionally binds a shortcut that detaches the active foreground single-subagent run without terminating it. The running foreground card shows the configured shortcut beside its live-detail hint. The default is unset, so pi-subagents does not reserve a global key.
+
+Pi binds `Ctrl+B` to editor cursor-left by default. The extension shortcut takes precedence, but Selesai reports the conflict at startup. To reserve the key without that warning, override the editor action in `~/.selesai/agent/keybindings.json`:
+
+```json
+{
+  "tui.editor.cursorLeft": "left"
+}
+```
+
+## `orcaProgressTabs` (experimental)
+
+```json
+{
+  "orcaProgressTabs": {
+    "enabled": true
+  }
+}
+```
+
+Opt in to a best-effort Orca observer that creates one Orca terminal tab for each subagent child and mirrors its live tool, assistant, stdout, and stderr progress. Tab titles use a persistent worktree-local sequence (`subagent · <agent> · 1`, `... · 2`, and so on), so separate workflows and concurrent children do not reuse the same number. This does **not** replace Selesai as the child runner: native Selesai children keep the same process, lifecycle, status, control, artifact, and result paths. External CLI profiles also keep their existing runner and can mirror their stdout/stderr.
+
+The integration is off by default and supports macOS and Linux. It is disabled on Windows. When enabled, `pi-subagents` looks for executable `orca` on `PATH`, or uses the executable path in `SELESAI_SUBAGENT_ORCA_BINARY`. If no executable is available, Orca is not running, the cwd is not an Orca-managed worktree, or `terminal create` fails, the authoritative subagent still runs normally. Tab creation is deliberately best-effort and never changes the child result.
+
+Set `enabled` to `false` (or remove the block) as a kill switch. In that state, `pi-subagents` does not invoke `orca` and creates no Orca tabs. The temporary mirror files contain child output, use private file modes where supported, and are removed shortly after the child finishes. Each mirror is capped at 1 MiB. The observer stops accepting progress when the cap or stream backpressure is reached and appends a truncation notice. The viewer removes terminal control sequences with parser state that persists across file reads. On completion, the viewer exits back to the Orca terminal's shell prompt; the tab and its terminal scrollback remain open until the user closes the tab. A successfully completed native Selesai child with a recorded session ends with a safely quoted `rm -- <exact-session-path>` command; failed, stopped, timed-out, and sessionless children do not show the removal command.
+
 ## `asyncByDefault`
 
 ```json
@@ -127,6 +182,18 @@ Use it when foreground orchestration or plain async single-agent runs need a lon
 
 Composite async runs (async chains, parallel tasks, and scripted workflows) stay unbounded at the top level by design. Their runner children are bounded individually by their own agent or runner defaults, so this value does not cap them. Must be a positive integer no greater than `2147483647` (the largest delay a Node.js timer can honor, roughly 24.8 days); invalid or out-of-range values are ignored and the built-in defaults apply.
 
+## `toolTimeoutMs`
+
+```json
+{ "toolTimeoutMs": 600000 }
+```
+
+Optional hard per-tool-call deadline in milliseconds. When configured, a child that emits `tool_execution_start` but not `tool_execution_end` is terminated with `timedOut: true` and a tool-specific error. The effective value is resolved per child: explicit `subagent` call value, then agent frontmatter, then this config value, then `SELESAI_SUBAGENT_TOOL_TIMEOUT_MS`.
+
+Without a configured value, Selesai still applies a five-minute hard timeout to known-fast built-in tools: `read`, `grep`, `find`, `ls`, `edit`, `write`, and `structured_output`. Long-running tools such as `bash`, custom tools, and MCP tools do not get a hard default. They get the normal open-tool attention notice after `activeNoticeAfterMs` and remain bounded by the run-level deadline.
+
+The tool timer tracks each active `toolCallId` separately and never extends the run-level deadline: when the remaining run budget is shorter, the ordinary run-level timeout wins. `contact_supervisor`, `intercom`, and `subagent_wait` are exempt because their legitimate purpose can be to wait for a human, supervisor, or child run. Use hard tool timeouts only for wedge protection; an elapsed timeout is not a mutation-safe boundary. Configured values must be positive integers no greater than `2147483647`; invalid or out-of-range values are rejected with a visible error rather than silently ignored.
+
 ## `globalConcurrencyLimit`
 
 ```json
@@ -155,14 +222,6 @@ Caps cumulative logical child admissions in one top-level run tree. The default
 
 The budget counts single launches, expanded `tasks`/`count`, static chain steps and parallel groups, actual dynamic `expand` items, appended chain steps, workflow children, and nested child calls. Static and materialized dynamic groups are admitted atomically. Startup retries, model fallback, and retained-child resume reuse the original logical child claim. Claims are never released or refunded. This cap is independent from the session-wide cumulative spawn budget and `globalConcurrencyLimit`.
 
-## `maxWorkflowAutoRelaunches`
-
-```json
-{ "maxWorkflowAutoRelaunches": 12 }
-```
-
-Maximum automatic relaunches when an async scripted workflow ends with a fan-out `budget` result before the goal is clean. Each relaunch re-runs the same `workflowScript` as a fresh top-level run with a new fan-out budget, the same mission, and the same progress file, so the loop keeps building until the commentator reports clean. Defaults to 12; `0` means unlimited. When the cap is reached, the workflow completes as `failed` with a note to raise the cap or relaunch manually. Foreground workflows are unaffected — their budget results surface to the parent inline.
-
 ## `maxActiveAsyncRunsPerSession`
 
 ```json
@@ -244,7 +303,7 @@ Overrides the command used to launch child Selesai processes. Package wrappers c
 export SELESAI_SUBAGENT_TASK_DELIVERY=file   # auto | file (default: auto)
 ```
 
-Controls how the task text reaches the child Pi process. `auto` (default) passes short tasks as an inline argv token and writes tasks longer than 8000 characters to a temp `task.md` referenced as `@<path>`. `file` always uses a temp file, keeping the task out of argv entirely.
+Controls how the task text reaches the child Selesai process. `auto` (default) passes short tasks as an inline argv token and writes tasks longer than 8000 characters to a temp `task.md` referenced as `@<path>`. `file` always uses a temp file, keeping the task out of argv entirely.
 
 Use `file` on hosts where endpoint protection (EDR) pre-execution scanning denies child processes whose command line embeds a long natural-language task — that denial surfaces as an immediate zero-activity `SIGKILL`. Independently of this setting, startup retries automatically escalate to file delivery after an unexplained zero-activity `SIGKILL`. Empty, whitespace-only, or unrecognized values fall back to `auto`.
 
@@ -260,7 +319,7 @@ Use `file` on hosts where endpoint protection (EDR) pre-execution scanning denie
 }
 ```
 
-Controls whether subagents receive runtime intercom coordination instructions and whether `intercom` and `contact_supervisor` are auto-added to their tool allowlist when needed.
+Controls whether subagents receive runtime coordination instructions and whether `contact_supervisor` is auto-added to their tool allowlist when needed.
 
 Fields:
 
@@ -268,9 +327,9 @@ Fields:
 - `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.selesai/agent/extensions/subagent/`.
 - `resultDelivery`: default `false`; set `true` only when an external listener consumes `subagent:result-intercom` and acknowledges the grouped completion payload. This is optional external result delivery, not native supervisor messaging. Enabled delivery waits for acknowledgement and reports acknowledgement failures. It does not change supervisor asks or progress updates.
 
-Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply. The external `intercom` tool is fallback plumbing when present.
+Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply. Agents can still use an external `intercom` tool when they explicitly request a provider that supplies it.
 
-The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, generic `intercom` as fallback plumbing, and avoid routine completion handoffs.
+The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, and avoid routine completion handoffs.
 
 ## `worktreeBaseDir`
 
@@ -305,7 +364,6 @@ stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `i
 {
   "missions": {
     "enabled": true,
-    "directory": ".pi-subagents/missions",
     "globalIndex": true,
     "retainTerminal": 200
   }
@@ -314,7 +372,8 @@ stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `i
 
 Automatic missions are enabled by default for ordinary launches with a task. Use per-launch `mission: false` for intentionally ephemeral work, or set `enabled: false` to disable automatic creation globally; explicit mission actions and `missionId`/`mission` launch fields still work.
 
-- `directory` may be absolute, `~/...`, or project-relative.
+- Mission records default to a project-keyed directory under pi's agent directory (`~/.selesai/agent/missions/projects/<project-hash>/`). This keeps the project worktree clean.
+- `directory` may be absolute, `~/...`, or project-relative. Set it to `.pi-subagents/missions` to opt in to project-scoped records.
 - `retainTerminal` is a positive count (default `200`); pruning removes only the oldest completed, failed, or cancelled records and their pointers, never planned, active, waiting, needs-decision, or corrupt records.
 - The user-global index contains pointers only; missing-record pointers self-heal when globally listed. Set `globalIndex: false` to disable writes or `globalIndexDir` to redirect it.
 
@@ -343,11 +402,11 @@ Each fixed action resolves to `"auto"`, `"confirm"`, or `"forbid"`. This is inte
 
 Controls where subagent artifact files (inputs, outputs, transcripts, metadata) are stored:
 
-- `"project"` (default): writes to `<cwd>/.pi-subagents/artifacts/`.
-- `"session"`: stores artifacts under pi's session directory (`~/.selesai/agent/sessions/<session>/subagent-artifacts/`), keeping the working directory clean.
+- `"project"`: writes to `<cwd>/.pi-subagents/artifacts/`.
+- `"session"` (default): stores artifacts under pi's session directory (`~/.selesai/agent/sessions/<session>/subagent-artifacts/`), keeping the working directory clean. It falls back to the OS temp directory when no session file exists.
 - `"temp"`: uses the OS temp directory.
 
-This preference also controls the default chain scratch directory. `"project"` uses `<cwd>/.pi-subagents/chain-runs/`, while `"session"` and `"temp"` use the user-scoped temp chain directory.
+This preference also controls the default chain scratch directory. `"project"` uses `<cwd>/.pi-subagents/chain-runs/`, while the default `"session"` and `"temp"` use the user-scoped temp chain directory.
 
 The `"session"` option uses the same directory that `cleanupAllArtifactDirs` already scans for age-based cleanup, so artifacts are still cleaned up automatically. Temporary chain directories are cleaned up separately after 24 hours.
 

package/dist/extensions/pi-subagents/docs/extension-api.md

@@ -56,6 +56,42 @@ The DTO intentionally never exposes run, async, or tool IDs. Clients must ignore
 
 `pi.events` is in-process only. It does not reach separate Selesai processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
 
+## External jobs in FleetView
+
+Use `pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:
+
+```ts
+import {
+  registerExternalRun,
+  updateExternalRun,
+  unregisterExternalRun,
+} from "pi-subagents/external-runs";
+
+registerExternalRun({
+  id: "dependency-review",
+  sessionId: ctx.sessionManager.getSessionId(),
+  source: "interactive-shell",
+  label: "Dependency review",
+  state: "running",
+  startedAt: Date.now(),
+  currentAction: "Inspecting package metadata",
+});
+
+updateExternalRun(ctx.sessionManager.getSessionId(), "dependency-review", {
+  state: "completed",
+  updatedAt: Date.now(),
+  endedAt: Date.now(),
+  preview: "No dependency blockers found.",
+  reportPath: "/tmp/dependency-review.md",
+});
+
+unregisterExternalRun(ctx.sessionManager.getSessionId(), "dependency-review");
+```
+
+The API validates and caches bounded display fields when the caller registers or updates a job. FleetView reads that cache only. It does not poll caller code. `snapshotExternalRuns(sessionId)` and `listExternalRuns(sessionId)` return bounded current-session snapshots. By default, malformed cached records throw with the validation error. Display-only Fleet callers can pass `{ ignoreMalformed: true, onMalformedRecord }` to remove bad records and keep rendering with a programmatic diagnostic.
+
+External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or Herdr controls for them. Supplied report and transcript paths are shown as bounded text only; FleetView does not read arbitrary external paths.
+
 ## Launch contract preflight
 
 Use `pi-subagents/preflight` when an extension needs to inspect the resolved child launch contract before deciding whether to run anything:

package/dist/extensions/pi-subagents/docs/missions.md

@@ -11,7 +11,9 @@ Missions are durable wrappers around runs. The noun map:
 - **Run** — one actual subagent execution.
 - **Receipt** — proof or a link for an external outcome, such as a PR, CI check, deployment, or release.
 
-Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under `<cwd>/.pi-subagents/missions/` linking objectives, run ids, lifecycle status, decisions, artifact paths, and delivery receipts. Workflow children do not create separate missions. Each workflow child attempt is stored in the enclosing mission with its stable workflow key, run id when known, agent, task metadata, timestamps, session and artifact paths, and latest status heartbeat.
+Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under `~/.selesai/agent/missions/projects/<project-hash>/` linking objectives, run ids, lifecycle status, decisions, artifact paths, and delivery receipts. Workflow children do not create separate missions. Each workflow child attempt is stored in the enclosing mission with its stable workflow key, run id when known, agent, task metadata, timestamps, session and artifact paths, and latest status heartbeat.
+
+Records created under the old default `<project>/.pi-subagents/missions` stay on disk. Continue them by setting `missions.directory` to that path for the project or by copying the record into the new agent-dir project store. There is no automatic migration.
 
 Behavior:
 
@@ -19,7 +21,7 @@ Behavior:
 - Human receipts end with `Mission: <id> (<status>)`, while JSON/structured output text stays unchanged and `details.missionId` is authoritative.
 - Pass `mission: false` for an intentionally ephemeral workflow. It creates no mission for the workflow or its children and has no `state` global.
 - Set `missions.enabled: false` to disable automatic mission creation; explicit mission fields and actions still work.
-- A workflow with a mission can use `await state.get(key)` and `await state.set(key, value)` for durable JSON state. Missing keys return `undefined`. Keys use the same format as `runs.run` keys. Each set takes the state-file lock, reads the latest file, merges the key, and atomically writes `<cwd>/.pi-subagents/missions/<mission-id>/state.json`. The complete file cannot exceed 256 KiB. Each workflow caches the file on its first `get`. A `mission:false` workflow has no `state` global.
+- A workflow with a mission can use `await state.get(key)` and `await state.set(key, value)` for durable JSON state. Missing keys return `undefined`. Keys use the same format as `runs.run` keys. Each set takes the state-file lock, reads the latest file, merges the key, and atomically writes `<mission-directory>/<mission-id>/state.json`. The complete file cannot exceed 256 KiB. Each workflow caches the file on its first `get`. A `mission:false` workflow has no `state` global.
 
 An explicit `mission` object must have exactly one non-empty `title` or `summary`. `objective` and `labels` are optional. When supplied, `goal` must be `true` and requires `budget: { tokens: <positive integer> }`.
 
@@ -56,7 +58,7 @@ subagent({
 })
 ```
 
-After each parent turn, an idle goal mission sends one needs-attention notice with its title, remaining token budget, and next ready action. The action comes from `state.nextReadyAction`, `state.nextAction`, a state item with `status: "ready"`, an open decision, or linked-run state. A workflow can write `state.nextReadyAction` to tell the next notice exactly what work is ready. When the latest linked workflow has a completed retained child, the notice names that child as the `resume` target. The extension never launches or replans goal work by itself.
+After each parent turn, an idle goal mission sends one needs-attention notice with its title, remaining token budget, and next ready action. The action comes from `state.nextReadyAction`, `state.nextAction`, a state item with `status: "ready"`, an open decision, or linked-run state. A workflow can write `state.nextReadyAction` to tell the next notice exactly what work is ready. When the latest linked workflow has a resumable retained child, the notice names that child as the `resume` target. Non-resumable retained children stay visible in `children.list` with their reason, but goal notices do not present them as resume targets. The extension never launches or replans goal work by itself.
 
 Linked-run token totals are stored on each run and folded into mission `usage`. An active linked run suppresses notices. Reaching the token budget changes the goal status to `budget-exhausted` and stops notices without closing the mission or reporting success.
 

package/dist/extensions/pi-subagents/docs/models.md

@@ -128,7 +128,7 @@ To see what `pi-subagents` has actually loaded right now:
 /subagents-models reviewer
 ```
 
-That reports the live runtime mapping, which can differ from settings on disk until you reload Selesai.
+That reports the live runtime mapping, which can differ from settings on disk until you reload Pi.
 
 ## Fuzzy model matching
 

package/dist/extensions/pi-subagents/docs/observability.md

@@ -23,13 +23,37 @@ subagent({ action: "status", id: "..." })      // one run
 
 Or ask naturally: "Show me the current async runs."
 
+The under-editor async widget gives a short view while work runs. Its expand key follows your Selesai keybinding:
+
+```text
+async subagent worker · background
+● worker
+  ● Step 1/1: worker · running
+    ⎿  read: src/auth.ts | 2.0s
+    Press configured-expand-key for live detail
+```
+
 To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
 
 ## FleetView
 
 In the TUI, a persistent FleetView below the editor keeps active work visible as a compact summary. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor.
 
-When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with task, elapsed time, and token totals. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to inspect it. Printable navigation keys are never intercepted before activation.
+```text
+2 active agents · ↓ 4.2k tokens · ↓/← to inspect
+```
+
+After you expand it:
+
+```text
+↑↓/jk select · enter inspect · esc back
+
+> main
+    scout · running                  1m 12s · ↓ 2.8k tokens
+    reviewer · running                 38s · ↓ 1.4k tokens
+```
+
+When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token totals. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to inspect it. Printable navigation keys are never intercepted before activation.
 
 FleetView replaces the legacy above-editor async widget by default. Successful background completions stay quiet so inactive Selesai tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child process.
 
@@ -57,6 +81,22 @@ Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "statu
 
 Use `/subagents-detach [run-id]` only for an active foreground single-subagent run you want to leave running without terminating; the eventual result remains available through status/wait.
 
+Set `foregroundDetachShortcut` in `~/.selesai/agent/extensions/subagent/config.json` to bind the same action to a shortcut. The running foreground card shows the configured shortcut beside its live-detail hint:
+
+```json
+{
+  "foregroundDetachShortcut": "ctrl+b"
+}
+```
+
+Pi binds `Ctrl+B` to editor cursor-left by default. The extension shortcut takes precedence, but Selesai reports the conflict at startup. To reserve the key without that warning, override the editor action in `~/.selesai/agent/keybindings.json`:
+
+```json
+{
+  "tui.editor.cursorLeft": "left"
+}
+```
+
 If something feels misconfigured, run `/subagents-doctor` or ask: "Check whether subagents and intercom are set up correctly."
 
 ## Async run artifacts
@@ -126,7 +166,7 @@ Foreground and async runners share bounded child-protocol handling:
 
 ## Chain and debug artifacts
 
-Each chain run creates a scratch directory under its resolved chain root. With the default `artifactDir: "project"`, that root is `<cwd>/.pi-subagents/chain-runs/`. With `artifactDir: "session"` or `"temp"`, it is user-scoped temp storage:
+Each chain run creates a scratch directory under its resolved chain root. With the default `artifactDir: "session"` or with `"temp"`, it is user-scoped temp storage. With `artifactDir: "project"`, the root is `<cwd>/.pi-subagents/chain-runs/`:
 
 ```text
 <tmpdir>/pi-subagents-<scope>/chain-runs/{runId}/