@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/docs/extensions/check.md

@@ -8,22 +8,20 @@ framework, or CI system.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Plan-mode refusal | `/check`, the read-only policy | Plan mode refuses a check because tests still write caches, snapshots, or generated files; approve the plan first. | Shipped |
-| Single active run | `run_check`, `/check` | A second run is refused with the corrective action while one process is active, instead of starting a parallel check. | Shipped |
-| Supervised run | `/check`, `run_check` | One process per command, with a wall-clock timeout, a bounded log, and `Esc` to cancel the process tree. | Shipped |
-| Command detection | a project manifest, `check.command` | The project's test, lint, and typecheck commands are found without configuration, with a shell command override. | Shipped |
-| Target selection | `/check` with a target, `run_check.target` | Run `test`, `lint`, `typecheck`, or `all`; `all` is the default. | Shipped |
-| Structured failures | `run_check` | The model gets `path`, `line`, `column`, `test`, `message`, and `command` instead of a wall of log text. | Shipped |
-| Failure list | `/check` | A navigable list with a detail view for the focused failure, drawn from a source excerpt or the bounded tail. | Shipped |
-| Rerun from the list | `r` in the failure list | Rerun the same check after reading a failure; `Enter` opens its detail and `Esc` closes. | Shipped |
-| Live run screen | `/check` | A scrolling tail that repaints while the command runs, so a silent compiler still shows progress. | Shipped |
-| Capped transcript | `run_check` | One status summary and at most five failure rows, expanded with `ctrl+o` to the model's 20-failure cap. | Shipped |
-| Headless report | `/check`, `run_check` | RPC, JSON, and print sessions post the summary plus the failure list, with no screen. | Shipped |
-| Honest fallback | `/check`, `run_check` | An unparsed failure names the exit status and the last output lines, never an invented location. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Plan-mode refusal | `/check`, the read-only policy | Plan mode refuses a check because tests still write caches, snapshots, or generated files; approve the plan first. |
+| Single active run | `run_check`, `/check` | A second run is refused with the corrective action while one process is active, instead of starting a parallel check. |
+| Supervised run | `/check`, `run_check` | One process per command, with a wall-clock timeout, a bounded log, and `Esc` to cancel the process tree. |
+| Command detection | a project manifest, `check.command` | The project's test, lint, and typecheck commands are found without configuration, with a shell command override. |
+| Target selection | `/check` with a target, `run_check.target` | Run `test`, `lint`, `typecheck`, or `all`; `all` is the default. |
+| Structured failures | `run_check` | The model gets `path`, `line`, `column`, `test`, `message`, and `command` instead of a wall of log text. |
+| Failure list | `/check` | A navigable list with a detail view for the focused failure, drawn from a source excerpt or the bounded tail. |
+| Rerun from the list | `r` in the failure list | Rerun the same check after reading a failure; `Enter` opens its detail and `Esc` closes. |
+| Live run screen | `/check` | A scrolling tail that repaints while the command runs, so a silent compiler still shows progress. |
+| Capped transcript | `run_check` | One status summary and at most five failure rows, expanded with `ctrl+o` to the model's 20-failure cap. |
+| Headless report | `/check`, `run_check` | RPC, JSON, and print sessions post the summary plus the failure list, with no screen. |
+| Honest fallback | `/check`, `run_check` | An unparsed failure names the exit status and the last output lines, never an invented location. |
 
 ## Quickstart
 
@@ -252,7 +250,7 @@ never turned into an invented location.
 | `source.ts` | Guarded source excerpt around a failure's `path:line`. |
 | `runtime.ts` | Planning, sequencing, aggregation, live lines, cancel/shutdown. |
 | `format.ts` | Summary, failure rows, source-excerpt/detail text, model report. |
-| `tui.ts` | `CheckRunComponent` (a live tail) and `CheckResultComponent` (a `DockListScreen` over the failures). |
+| `view/check-screens.ts` | `CheckRunComponent` (a live tail) and `CheckResultComponent` (a `DockListScreen` over the failures), loaded on first use. |
 | `tools.ts` | `run_check` schema, registration, the running partial result, and the call/result renderers. |
 | `render.ts` | The transcript result block: status summary, capped failure rows, tail fallback. |
 | `commands.ts` | `/check`, target parsing, completions, TUI/headless flow. |

package/docs/extensions/context.md

@@ -7,20 +7,18 @@ untouched.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Window headline | `/context` | Pi's own estimate: tokens, window, percentage, free space, and the auto-compaction threshold with the headroom left before it. | Shipped |
-| Composition breakdown | `/context` | Where the window went — system prompt, active tool definitions, the conversation by role, injected pack context, summaries, and shell output. | Shipped |
-| Guarded compaction | `/context compact [instructions]`, `c` on the screen | Compact from the report without interrupting a streaming turn or a running compaction. | Shipped |
-| Compact result | `/context compact` result | The before and after token counts are reported, so the effect of the compaction is visible. | Shipped |
-| Honest drift | `/context` | The difference between Pi's total and the composition estimate, named instead of hidden by forcing the parts to add up. | Shipped |
-| Compaction history | `/context` | How many compactions the branch has, what the newest one cut from and to, and what its summary costs. | Shipped |
-| Largest messages | `/context` | The five largest single messages, so a report that is mostly one tool result says so. | Shipped |
-| Gauge rendering | the `/context` screen | The window and composition bars show ten or eight cells, colored by role, instead of leaving the reader to infer the shape. | Shipped |
-| Pending total | `/context` after a compaction | The report shows a pending total instead of a fabricated estimate while Pi recalculates the window. | Shipped |
-| Mode coverage | `/context` | A scrollable screen in the TUI, the same facts as plain text in `rpc`, `json`, and `print`. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Window headline | `/context` | Pi's own estimate: tokens, window, percentage, free space, and the auto-compaction threshold with the headroom left before it. |
+| Composition breakdown | `/context` | Where the window went — system prompt, active tool definitions, the conversation by role, injected pack context, summaries, and shell output. |
+| Guarded compaction | `/context compact [instructions]`, `c` on the screen | Compact from the report without interrupting a streaming turn or a running compaction. |
+| Compact result | `/context compact` result | The before and after token counts are reported, so the effect of the compaction is visible. |
+| Honest drift | `/context` | The difference between Pi's total and the composition estimate, named instead of hidden by forcing the parts to add up. |
+| Compaction history | `/context` | How many compactions the branch has, what the newest one cut from and to, and what its summary costs. |
+| Largest messages | `/context` | The five largest single messages, so a report that is mostly one tool result says so. |
+| Gauge rendering | the `/context` screen | The window and composition bars show ten or eight cells, colored by the row's category — the same hue in the composition table and in the largest-message list — instead of leaving the reader to infer the shape. |
+| Pending total | `/context` after a compaction | The report shows a pending total instead of a fabricated estimate while Pi recalculates the window. |
+| Mode coverage | `/context` | A scrollable screen in the TUI, the same facts as plain text in `rpc`, `json`, and `print`. |
 
 ## Quickstart
 
@@ -83,6 +81,28 @@ first reply, when Pi's fallback leaves the prompt and the tools out. Each bar
 rounds to the nearest cell, so a bar sits within half a cell of the percentage
 printed beside it; the percentage itself is exact.
 
+## The table is a chart
+
+A row's bar and its percentage wear the hue of its category, and the
+largest-message list uses the same table, so a tool result is one colour wherever
+it appears. A hue identifies; it never judges — the gauge is the only verdict on
+the screen, and the footer's feedback line is the transient one. Labels, token
+counts, and notes stay in the body, secondary, and faint roles, so the text still
+reads on its own and the colour repeats an order the row already has.
+
+| Category | Hue | Bucket ids |
+|---|---|---|
+| System prompt | blue (`hue1`) | `system` |
+| Tool definitions | purple (`hue2`) | `tools` |
+| User messages | pink (`hue3`) | `user` |
+| Assistant | green (`hue4`) | `assistant` |
+| Tool results | amber (`hue5`) | `toolResults`, the `tool result` rows |
+| Everything else | neutral (`meta`, children `faint`) | injected context and its children, summaries, shell output |
+
+A category with no entry — an injected type, a role a future Pi adds — reads
+neutral rather than borrowing a hue, so the coloured rows always mean the five
+categories above.
+
 | Row | Source |
 |---|---|
 | Headline (`tokens`, `percent`) | `ctx.getContextUsage()`: the last valid provider usage plus Pi's estimate of the messages after it. `tokens` is `null` between a compaction and the next successful reply, because the last usage describes the pre-compaction context. |
@@ -175,7 +195,7 @@ printed beside it; the percentage itself is exact.
 | `collect.ts` | The host boundary: one read of usage, prompt, tools, settings, projection, and branch. |
 | `report.ts` | The pure builder: composition, reserve resolution, compaction history, largest messages. |
 | `format.ts` | The plain-text report for non-TUI modes. |
-| `tui.ts` | `ContextComponent`: gauge, rows, scroll, confirmation, feedback. |
+| `view/context-report.ts` | `ContextComponent`: gauge, rows, scroll, confirmation, feedback, loaded on first use. |
 | `types.ts` | `ContextInputs`, `ContextReport`, buckets, and the host types named through `ReturnType<…>`. |
 
 ## Testing

package/docs/extensions/file-browse.md

@@ -12,30 +12,28 @@ the shared loopback layer plus one small vanilla script.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| One-command browsing | `/browse` | The server starts at the effective working directory, prints its URL, and opens the browser. | Shipped |
-| Read-only serving | `/browse` | Nothing is edited or written, and the server binds `127.0.0.1` only. | Shipped |
-| Two-pane page | `/files/`, `/files/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. | Shipped |
-| File previews | `/view/<rel>` | Text, rendered Markdown, image thumbnails, and download cards for binary or over-size files, each with a per-language icon. | Shipped |
-| Quick open | `/files/`, `Ctrl/Cmd+K`, `/files/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. | Shipped |
-| Git diff view | `/diff`, `/diff/<rel>` | A change overview and one file's unified diff, scoped to `head`, `staged`, or `worktree`. | Shipped |
-| Live status | `/events`, the `◉ live` chip | An open page keeps its branch, change markers, and footer up to date without a reload. | Shipped |
-| Reload hint | `/api/dir-rev`, `⟳ reload` | A page whose folder gained or lost a file offers a reload control instead of changing its rows. | Shipped |
-| The session's page port | `serve`'s `◉ <port>` chip | The footer names the one port every page of the session answers on, this one included. | Shipped |
-| Listing controls | the `Name`, `Size`, and `Modified` headers | The current folder sorts by name, size, or modified time, directories first, and the choice is remembered per browser. | Shipped |
-| Keyboard navigation | the tree's keymap, `?` | The tree is one tab stop with arrow, fold, and open keys; a shortcut sheet lists the page's own keys. | Shipped |
-| Diff hunk navigation | `n`/`p` in `/diff` | Jump between changed hunks without scrolling the whole file. | Shipped |
-| Fold and expand all | the `fold all` control | Collapse or expand the whole tree in one click. | Shipped |
-| Reading progress | `browse-progress` hairline | A long directory or diff read shows how much has loaded, and printing hides the indicator. | Shipped |
-| Printing | `@media print` styles | The page prints without the toolbar, progress hairline, or other screen-only chrome. | Shipped |
-| Syntax highlighting | `/view/<rel>`, `/view/<rel>?raw=1` | Supported code files show keywords, strings, numbers, and comments in colour in both themes; other text stays plain. | Shipped |
-| Markdown preview | `/view/<rel>`, `/view/<rel>?raw=1` | A README renders as headings, lists, tables, code, and links, with a one-click raw view. | Shipped |
-| Copy and wrap | the page toolbar, `y`, `u` | Copy a file's path or contents or a `path:12-30` line reference, and toggle line wrapping for text and raw views. | Shipped |
-| Theme toggle | the header button, `/theme.js` | Dark and light palettes, following the system until an explicit choice is remembered per browser. | Shipped |
-| Idle stop and prefix reuse | `/browse stop`, the idle grace | The page gives its prefix back when nobody is reading it, so a closed tab never holds the session's server. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| One-command browsing | `/browse` | The server starts at the effective working directory, prints its URL, and opens the browser; every later `/browse` opens the page it already serves. |
+| Read-only serving | `/browse` | Nothing is edited or written, and the server binds `127.0.0.1` only. |
+| Two-pane page | `/files/`, `/files/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. |
+| File previews | `/view/<rel>` | Text, rendered Markdown, image thumbnails, and download cards for binary or over-size files, each with a per-language icon. |
+| Quick open | `/files/`, `Ctrl/Cmd+K`, `/files/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. |
+| Git diff view | `/diff`, `/diff/<rel>` | A change overview and one file's unified diff, scoped to `head`, `staged`, or `worktree`. |
+| Live status | `/events`, the `◉ live` chip | An open page keeps its branch, change markers, and footer up to date without a reload. |
+| Reload hint | `/api/dir-rev`, `⟳ reload` | A page whose folder gained or lost a file offers a reload control instead of changing its rows. |
+| The session's page port | `serve`'s `◉ <port>` chip | The footer names the one port every page of the session answers on, this one included. |
+| Listing controls | the `Name`, `Size`, and `Modified` headers | The current folder sorts by name, size, or modified time, directories first, and the choice is remembered per browser. |
+| Keyboard navigation | the tree's keymap, `?` | The tree is one tab stop with arrow, fold, and open keys; a shortcut sheet lists the page's own keys. |
+| Diff hunk navigation | `n`/`p` in `/diff` | Jump between changed hunks without scrolling the whole file. |
+| Fold and expand all | the `fold all` control | Collapse or expand the whole tree in one click. |
+| Reading progress | `browse-progress` hairline | A long directory or diff read shows how much has loaded, and printing hides the indicator. |
+| Printing | `@media print` styles | The page prints without the toolbar, progress hairline, or other screen-only chrome. |
+| Syntax highlighting | `/view/<rel>`, `/view/<rel>?raw=1` | Supported code files show keywords, strings, numbers, and comments in colour in both themes; other text stays plain. |
+| Markdown preview | `/view/<rel>`, `/view/<rel>?raw=1` | A README renders as headings, lists, tables, code, and links, with a one-click raw view. |
+| Copy and wrap | the page toolbar, `y`, `u` | Copy a file's path or contents or a `path:12-30` line reference, and toggle line wrapping for text and raw views. |
+| Theme toggle | the header button, `/theme.js` | Dark and light palettes, following the system until an explicit choice is remembered per browser. |
+| Idle stop and prefix reuse | `/browse stop`, the idle grace | The page gives its prefix back when nobody is reading it, so a closed tab never holds the session's server. |
 
 ## Quickstart
 
@@ -66,11 +64,12 @@ selects the root.
 
 - The root is the effective cwd, so an active `worktree` session serves the
   worktree. `<path>` must resolve inside it.
-- The port is the session's: `serve` picks one in `4780`–`5779` (and `serve.port` pins
-  it), so the origin stays stable across roots and restarts. A busy pinned port is
-  reported, not silently changed.
-- Starting while already running with the same root reprints the URL without
-  restarting; a different root restarts the page.
+- The port is the project's: `serve` hashes the repository key into `4780`–`5779`
+  (and `serve.port` pins it), so the origin stays stable across roots and restarts. A
+  busy pinned port is reported, not silently changed.
+- Starting while already running with the same root opens that page again and
+  reprints its URL, without restarting the server; a different root restarts the page.
+  With `autoOpen` off, the second `/browse` only reprints the URL.
 - The server is closed when its last page has been gone for ten seconds, so
   closing the browser window ends the session's browse server and `/browse`
   starts it again on the session's port. A reload or a new tab inside that grace keeps
@@ -101,7 +100,7 @@ global document then project document, project wins — are in
 
 | Key | Default | Meaning |
 |---|---|---|
-| `autoOpen` | `true` | Open the browser on start; `false` for headless. |
+| `autoOpen` | `true` | Open the browser on start and on every later `/browse`; `false` for headless. |
 | `maxFileBytes` | `1048576` | Larger files show a download card only. |
 | `maxThumbBytes` | `5242880` | Larger images get an icon, not a thumbnail. |
 | `maxTextLines` | `5000` | Rendered lines before truncation. |
@@ -524,7 +523,7 @@ stops at the first difference because the control, not the checker, is the fix.
 | `view/diff-html.ts` | The unified-diff body: the gutter, the sign, the hunk sections, and per-hunk highlighting |
 | `transport/router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
 | `transport/server.ts` | This extension's routes over `lib/http`'s loopback server: the request count, the stream cap, and the idle policy |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: one server entry (`serveHttp`) and the mount contract a page claims a prefix with (`requestMount`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | The served-page kit shared with `plan`: one server entry (`serveHttp`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace. The mount contract is the leaf [`mount.ts`](../../lib/http/mount.ts), which is the only one a registration graph may reach |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
 
 ## Testing

package/docs/extensions/file-open.md

@@ -7,17 +7,15 @@ effective working directory.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Native open | `/open`, `open_path` | The file or directory opens in the application the OS associates with its type. | Shipped |
-| Reveal in the file manager | `/open -r`, `open_path` with `reveal: true` | The target is selected in the file manager instead of opened. | Shipped |
-| Working-directory resolution | `/open`, `open_path` | A relative path resolves against the effective working directory, so under [`worktree`](./worktree.md) `/open .` opens the isolated worktree. | Shipped |
-| Codemode-only exposure | `exposure: "codemode"` | The model cannot call `open_path` directly unless a codemode script asks for it; the table does not promise otherwise. | Shipped |
-| Pasted-path cleanup | `/open`, `open_path` | The editor's `@` mention prefix, surrounding quotes, and control characters are stripped before the path is used. | Shipped |
-| Failure reporting | `/open`, `open_path` | A missing path, a launcher that cannot start, and a non-zero exit after a successful start on macOS/Linux are reported. | Shipped |
-| Session-outliving launch | `/open`, `open_path` | The handler runs detached, so the application outlives the Pi session. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Native open | `/open`, `open_path` | The file or directory opens in the application the OS associates with its type. |
+| Reveal in the file manager | `/open -r`, `open_path` with `reveal: true` | The target is selected in the file manager instead of opened. |
+| Working-directory resolution | `/open`, `open_path` | A relative path resolves against the effective working directory, so under [`worktree`](./worktree.md) `/open .` opens the isolated worktree. |
+| Codemode-only exposure | `exposure: "codemode"` | The model cannot call `open_path` directly unless a codemode script asks for it; the table does not promise otherwise. |
+| Pasted-path cleanup | `/open`, `open_path` | The editor's `@` mention prefix, surrounding quotes, and control characters are stripped before the path is used. |
+| Failure reporting | `/open`, `open_path` | A missing path, a launcher that cannot start, and a non-zero exit after a successful start on macOS/Linux are reported. |
+| Session-outliving launch | `/open`, `open_path` | The handler runs detached, so the application outlives the Pi session. |
 
 ## Quickstart
 

package/docs/extensions/file-read.md

@@ -10,20 +10,18 @@ path tools use.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Document extraction | `read_doc` | Plain text from a document or workbook whose bytes the built-in `read` cannot decode. | Shipped |
-| Paged reading | `read_doc` (`startIndex`, `maxChars`) | A long file arrives in slices, and a truncated result names the offset to ask for next. | Shipped |
-| Workbook text | `read_doc` on `.xlsx` | One `[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of the file survives. | Shipped |
-| Confined reads | `read_doc` | A path outside the effective working directory is refused, symlinks resolved, before any parser runs. | Shipped |
-| Progress and cancellation | `startToolProgress`, the abort signal | A slow extraction shows `Reading... <elapsed>` and can be cancelled instead of looking dead. | Shipped |
-| Bounded extraction | `file-read.maxFileBytes`, `file-read.extractTimeoutMs` | An over-size file or a parser past its deadline fails the read instead of parking the turn. | Shipped |
-| Per-format switches | `file-read.formats` | Any of the six formats can be turned off, and a disabled read names the key that did it. | Shipped |
-| Unsupported-format hint | `read_doc` on another extension | The refusal names the supported formats and the legacy `.xls` conversion hint instead of a generic read error. | Shipped |
-| Lazy parsers | `read_doc` | Only the format you read loads a library, so registration costs nothing at startup. | Shipped |
-| Code-point slicing | `read_doc` (`startIndex`, `maxChars`) | CJK and emoji stay well-formed across a page boundary. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Document extraction | `read_doc` | Plain text from a document or workbook whose bytes the built-in `read` cannot decode. |
+| Paged reading | `read_doc` (`startIndex`, `maxChars`) | A long file arrives in slices, and a truncated result names the offset to ask for next. |
+| Workbook text | `read_doc` on `.xlsx` | One `[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of the file survives. |
+| Confined reads | `read_doc` | A path outside the effective working directory is refused, symlinks resolved, before any parser runs. |
+| Progress and cancellation | `startToolProgress`, the abort signal | A slow extraction shows `Reading... <elapsed>` and can be cancelled instead of looking dead. |
+| Bounded extraction | `file-read.maxFileBytes`, `file-read.extractTimeoutMs` | An over-size file or a parser past its deadline fails the read instead of parking the turn. |
+| Per-format switches | `file-read.formats` | Any of the six formats can be turned off, and a disabled read names the key that did it. |
+| Unsupported-format hint | `read_doc` on another extension | The refusal names the supported formats and the legacy `.xls` conversion hint instead of a generic read error. |
+| Lazy parsers | `read_doc` | Only the format you read loads a library, so registration costs nothing at startup. |
+| Code-point slicing | `read_doc` (`startIndex`, `maxChars`) | CJK and emoji stay well-formed across a page boundary. |
 
 ## Quickstart
 

package/docs/extensions/goal.md

@@ -5,21 +5,19 @@ every turn. The goal is the *what*; the [`todo`](./todo.md) list is the *how*.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Goal recording | `goal`, `/goal set`, `/goal raw`, `/goal clear` | The objective is replaced whole, cleared by an empty value, and recorded verbatim when you ask for it. | Shipped |
-| Phase tracking | `goal`, `/goal done` | The goal is `planning`, `active`, or `achieved`, and only the workflow can open a draft. | Shipped |
-| Plan-first question | `goal`, `/goal <prompt>`, `/goal raw` | One dialog decides whether a new goal enters plan mode before it is pursued. | Shipped |
-| Plan-mode allowlist | `goal` in plan mode | The model can record or update the objective while plan mode keeps the rest of the session read-only. | Shipped |
-| Plan-phase settlement | `planning` goal, `exit_plan_mode` | Leaving plan mode without approval makes the draft `active`; approving the plan writes its `## Goal` into it. | Shipped |
-| Understanding loop | `/goal <prompt>`, `/goal set`, `/goal edit` | A typed goal is restated, questioned when it is unclear, and confirmed in the editor before it is recorded. | Shipped |
-| Goal rail | the `Goal · active · …` widget, the `achieved` key | The objective stays one line above the editor while it is pursued. | Shipped |
-| Per-turn restatement | the `[SESSION GOAL]` reminder | The model reads the pursued objective before each turn, without it entering the transcript. | Shipped |
-| Open-list check | `goal`, `/goal done` | Completing the goal names the todo items the list still has open. | Shipped |
-| Branch-following state | tool-result `details`, the `goal` session entry | The goal survives `/resume` and `/tree`, and abandoned branches never leak in. | Shipped |
-| Command help | `/goal help`, `/goal -h`, `/goal --help` | The verb list and the usage of each form, without changing the goal. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Goal recording | `goal`, `/goal set`, `/goal raw`, `/goal clear` | The objective is replaced whole, cleared by an empty value, and recorded verbatim when you ask for it. |
+| Phase tracking | `goal`, `/goal done` | The goal is `planning`, `active`, or `achieved`, and only the workflow can open a draft. |
+| Plan-first question | `goal`, `/goal <prompt>`, `/goal raw` | One dialog decides whether a new goal enters plan mode before it is pursued. |
+| Plan-mode allowlist | `goal` in plan mode | The model can record or update the objective while plan mode keeps the rest of the session read-only. |
+| Plan-phase settlement | `planning` goal, `plan` action `exit` | Leaving plan mode without approval makes the draft `active`; approving the plan writes its `## Goal` into it. |
+| Understanding loop | `/goal <prompt>`, `/goal set`, `/goal edit` | A typed goal is restated, questioned when it is unclear, and confirmed in the editor before it is recorded. |
+| Goal rail | the `Goal · active · …` widget, the `achieved` key | The objective stays one line above the editor while it is pursued. |
+| Per-turn restatement | the `[SESSION GOAL]` reminder | The model reads the pursued objective before each turn, without it entering the transcript. |
+| Open-list check | `goal`, `/goal done` | Completing the goal names the todo items the list still has open. |
+| Branch-following state | tool-result `details`, the `goal` session entry | The goal survives `/resume` and `/tree`, and abandoned branches never leak in. |
+| Command help | `/goal help`, `/goal -h`, `/goal --help` | The verb list and the usage of each form, without changing the goal. |
 
 ## Quickstart
 
@@ -137,7 +135,7 @@ and stores the objective as `planning`, so a plan can be designed against it;
 declining stores it `active`, the final objective. The question is skipped for
 an update to a goal that is already pursued, without a dialog UI, and when
 `plan` is not loaded. The question and its consent sentence come from
-`lib/plan-entry.ts`, the same ones `enter_plan_mode` shows, so the user answers
+`lib/plan-entry.ts`, the same ones the `enter` action shows, so the user answers
 once.
 
 A draft whose plan never arrived is settled rather than stranded. If plan mode is
@@ -215,7 +213,7 @@ that is what it is. The `goal` tool stays the silent setter.
   the extension that asks also has to act on the answer — which a command context
   cannot do, since `ExtensionCommandContext` has no `executeTool`. So the consent
   sentence and the request channel live in `lib/plan-entry.ts`: `goal` asks, and
-  `plan` enables silently over `pi.events`. `enter_plan_mode` keeps its own
+  `plan` enables silently over `pi.events`. The `enter` action keeps its own
   confirm for the model-initiated path, using the same sentence, so the user is
   never asked twice and the two texts cannot drift.
 - **The draft is settled, not stranded.** A `planning` goal is normalised by the

package/docs/extensions/job.md

@@ -7,25 +7,23 @@ for it, or kill it.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Background execution | `job` (`start`) | A long build, test suite, server, or watcher keeps running while the turn moves on. | Shipped |
-| Job listing | `job` (`list`), `/jobs` | This session's jobs with status and elapsed time, and a live peer session's tagged `peer`. | Shipped |
-| Polling and waiting | `job` (`status`, `logs`, `wait`) | One call returns a job's status, a bounded output tail, or blocks until it finishes. | Shipped |
-| Stopping jobs | `job` (`kill` with `signal`) | A running job receives `SIGTERM`, `SIGKILL`, or `SIGINT`, and a finished one can be cleared. | Shipped |
-| Selective clear | `job` (`clear` with `id`, `all`) | Clear one finished record by id, or remove running jobs with `all` after a confirmation in the screen. | Shipped |
-| Start deadline | `timeoutMs` on `start` | A job is killed after the requested wall-clock limit instead of running until the session ends. | Shipped |
-| Kill escalation | `killGraceMs` | A kill sends `SIGTERM` first, then `SIGKILL` after the grace period, on a user kill and on shutdown. | Shipped |
-| Stdin driving | `job` (`send` with `input`, `newline`, `eof`) | A line or a bare keystroke reaches a running job started with `stdin: true`, and `eof` closes its input. | Shipped |
-| Rotating logs | `job` (`logs`), `job.maxLogBytes` | stdout and stderr stream to an append-only log that rotates at 8 MiB, so a chatty job cannot fill the disk. | Shipped |
-| Status chips | `job.showStatus` | `▸ N` running and `✗ N` unreported-failure counts in the footer. | Shipped |
-| Completion reporting | `job` (`wake`), `job.wakeOnFinish` | A finished job is reported at the next turn, or triggers one as soon as the agent is idle. | Shipped |
-| Job screen | `/jobs` | Select a job, open its log, kill it, or clear finished ones, with a confirmation on the destructive verbs. | Shipped |
-| Detached lifetime | `job` (`start`, `detached`) | A POSIX job outlives the session and is reattached next time; Windows refuses the detach instead of faking one. | Shipped |
-| Finished-job pruning | `maxJobs` | The registry drops the oldest finished records once the configured count is exceeded. | Shipped |
-| Structured result | tool-result `details` | Every call returns a `JobDetails` record of the job and the action's outcome. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Background execution | `job` (`start`) | A long build, test suite, server, or watcher keeps running while the turn moves on. |
+| Job listing | `job` (`list`), `/jobs` | This session's jobs with status and elapsed time, and a live peer session's tagged `peer`. |
+| Polling and waiting | `job` (`status`, `logs`, `wait`) | One call returns a job's status, a bounded output tail, or blocks until it finishes. |
+| Stopping jobs | `job` (`kill` with `signal`) | A running job receives `SIGTERM`, `SIGKILL`, or `SIGINT`, and a finished one can be cleared. |
+| Selective clear | `job` (`clear` with `id`, `all`) | Clear one finished record by id, or remove running jobs with `all` after a confirmation in the screen. |
+| Start deadline | `timeoutMs` on `start` | A job is killed after the requested wall-clock limit instead of running until the session ends. |
+| Kill escalation | `killGraceMs` | A kill sends `SIGTERM` first, then `SIGKILL` after the grace period, on a user kill and on shutdown. |
+| Stdin driving | `job` (`send` with `input`, `newline`, `eof`) | A line or a bare keystroke reaches a running job started with `stdin: true`, and `eof` closes its input. |
+| Rotating logs | `job` (`logs`), `job.maxLogBytes` | stdout and stderr stream to an append-only log that rotates at 8 MiB, so a chatty job cannot fill the disk. |
+| Status chips | `job.showStatus` | `▸ N` running and `✗ N` unreported-failure counts in the footer. |
+| Completion reporting | `job` (`wake`), `job.wakeOnFinish` | A finished job is reported at the next turn, or triggers one as soon as the agent is idle. |
+| Job screen | `/jobs` | Select a job, open its log, kill it, or clear finished ones, with a confirmation on the destructive verbs. |
+| Detached lifetime | `job` (`start`, `detached`) | A POSIX job outlives the session and is reattached next time; Windows refuses the detach instead of faking one. |
+| Finished-job pruning | `maxJobs` | The registry drops the oldest finished records once the configured count is exceeded. |
+| Structured result | tool-result `details` | Every call returns a `JobDetails` record of the job and the action's outcome. |
 
 ## Quickstart
 
@@ -210,7 +208,7 @@ are in
 | `maxLogBytes` | `8388608` | Bytes a log segment may reach before it rotates to `<id>.log.1`; `0` keeps logs unbounded. |
 | `killGraceMs` | `5000` | Grace before SIGTERM escalates to SIGKILL. |
 | `repaintMs` | `1000` | Status-chip refresh interval while jobs run. |
-| `sessionTtlMs` | `60000` | How long a session heartbeat is trusted before its jobs may be reaped. |
+| `sessionTtlMs` | `60000` | How old a session heartbeat may be before its pid is re-checked for reuse. |
 | `registryDir` | — | Override the registry/log directory. |
 
 ## Security
@@ -236,7 +234,9 @@ rewritten.
   kill or clear it, and the tool's `clear` refuses that record too; the tool can
   still take one over by explicit id (`status`/`logs`/`kill`, where `kill`
   adopts it). Chips, completion notices, and pruning stay this session's own, so
-  a peer's finished job waits for that session to clear it.
+  a peer's finished job waits for that session to clear it — including when that
+  session has been idle long enough for its heartbeat to age, because the
+  heartbeat only ticks while a job is running.
 - **A carriage return is not a line break.** Output is split on `\n` only; a
   progress rewrite (`10%\r50%\r100%`) is one line whose sanitized form keeps the
   text after the last `\r`. A program that only ever emits `\r` therefore
@@ -279,7 +279,7 @@ rewritten.
 | `outputSchema` / `structuredContent` | None. Results return `JobDetails` in tool-result `details` only. |
 | State storage | One durable registry file per session, `~/.pi/agent/jobs/<projectKey>/registry-<sessionHash>.json` (keyed by the session cwd, so entering a worktree does not move it), merged from every session file on load; a dead session's records are adopted and a legacy shared `registry.json` is migrated once. Ids are reserved with an atomic `O_EXCL` `<id>.lock` before `start`, and a POSIX job's exit code is written to a per-job `.status` file. Tool results carry `JobDetails`; unreported completions arrive as a shared transcript notice (`my-pi-agent/notice`) at `before_agent_start`. |
 | Lifecycle | `session_start` loads and reconciles the registry and arms `onFinish` and `onComplete`; `session_shutdown` kills session-owned jobs and clears both status chips. `session_tree` repaints; `agent_start`/`agent_settled` track busy; `context` prunes stale notices of its own source. |
-| Event bus | Each job that reaches a terminal state is published on `my-pi-agent/job-finished` (`lib/events.ts`) with its id, label, status, exit code, and signal, from the one `settle` path every transition goes through. bytefly's notify capability subscribes there instead of importing this extension. |
+| Event bus | Each job that reaches a terminal state is published on `my-pi-agent/job-finished` (`lib/events.ts`) with its id, label, status, exit code, and signal, from the one path every transition goes through — a close event, a pid observed gone on the clock, a gone peer's leftover reaped, and an orphan killed while the registry loads — which announces the completion and fires the one wake turn together. A peer's record settled here is adopted, so its completion is this session's to report. bytefly's notify capability subscribes there instead of importing this extension. |
 
 ## Design notes
 
@@ -322,10 +322,13 @@ rewritten.
   per session, `start` claims the next `j<n>` with an `O_EXCL` `<id>.lock`
   before spawning, so two sessions cannot pick the same id from a stale read;
   the reservation is pruned once the id is committed to a registry file.
-- **Sessions heartbeat; reconciliation is owner-aware.** Each session writes a
-  liveness marker, so a peer's live non-detached job is not reaped until its
-  owner's marker expires. `persist` merges onto a fresh read and drops ids this
-  session deleted.
+- **Sessions heartbeat; ownership is the process.** Each session writes a liveness
+  marker (its pid, that process's start time, and its last beat), and the beat only
+  ticks while a job runs — so a session that has finished its work goes quiet rather
+  than dying. Only a session that is *gone* — its pid is dead, or a reused one —
+  gives up its records: a quiet peer keeps its file, its marker, and its jobs, and a
+  peer's live non-detached job is never reaped. `persist` merges onto a fresh read and
+  drops ids this session deleted.
 - **Exit codes survive a session boundary.** A POSIX job is spawned behind an
   `EXIT` trap that writes `$?` to a per-job `.status` file (path passed in the
   environment); a later session reads it when it finds a dead pid and reports
@@ -336,14 +339,17 @@ rewritten.
   `detached` dev server survives.
 - **Pid reuse is guarded by a start-time token.** Before signalling an unowned
   pid, its best-effort start token (`ps -o lstart=`) is re-checked; a mismatch
-  is treated as gone instead of as a signal. Where no token is available the
-  check degrades to liveness.
+  is treated as gone instead of as a signal. The same token is written into a
+  session's marker, so a pid that has been reused is a gone session rather than a
+  quiet one. Where no token is available the check degrades to liveness.
 - **Reattached jobs are polled.** A reattached detached job has no child
   handle, so its `close` event never fires; the repaint clock polls it and
   settles it (recovering an exit code from the status file, else `unknown`)
   when the pid disappears.
 - **Shared seams, job policy.** The spawn/tree-kill/liveness seam
-  (`lib/spawn.ts`), the byte-safe line splitter (`lib/lines.ts`), the
+  (`lib/spawn.ts`), the command supervisor (`lib/child.ts`, which `watch` drives
+  too: one SIGTERM → SIGKILL body, each extension's own grace), the byte-safe
+  line splitter (`lib/lines.ts`), the
   untrusted-line boundary (`lib/format.ts`), the pending-report coordinator
   (`lib/report.ts`), the status chips (`lib/tui/status-controller.ts`), and the
   `/jobs` screen frame (`lib/tui/dock-screen.ts`) are shared with `watch`; this
@@ -387,19 +393,22 @@ rewritten.
 | `index.ts` | Factory: registers the tool/command and wires events, including the shared `lib/report.ts` completion reporter. |
 | `schema.ts` | Parameter schema and pure validation (a `JobCall` union). |
 | `config.ts` | The `job` section of `bytefly.json`: loading and clamping. |
-| `format.ts` | Pure formatting, duration, and transcript outcome-line helpers; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
+| `format.ts` | Pure formatting, duration, and transcript outcome-line helpers, plus the job row both surfaces draw; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
 | `paths.ts` | Session/marker/registry/status file-name helpers. |
-| `registry.ts` | Per-session registry load/merge, legacy migration, and pure reconciliation. |
+| `registry.ts` | Per-session registry load/merge under `<agent-dir>/jobs/<project>/`, legacy migration, and the pure reconciliation a load runs — `loadRecords` merges every file, recovers dead pids, and classifies the survivors and orphans. |
 | `reservations.ts` | Atomic `O_EXCL` job-id reservation and release. |
 | `status.ts` | `EXIT`-trap exit-status file (write path via env, read on reattach). |
-| `session.ts` | Per-session heartbeat markers and owner-liveness rules. |
-| `store.ts` | Durable store: registry dir, this session's atomic merge-write, deletions. |
+| `session.ts` | Per-session heartbeat markers and the ownership rule: `live`, `quiet`, or `gone`. |
+| `store.ts` | Durable store: the registry directory (`<agent-dir>/jobs/<project>/`), this session's atomic merge-write, deletions. |
 | `logs.ts` | Bounded, sanitized log-tail reading. |
 | `ui.ts` | Footer status chips and the failure alert, over the shared `lib/tui/status-controller.ts` (chips, attached context, `notify`). |
 | `waiters.ts` | `wait` resolver bookkeeping. |
 | `log-writer.ts` | Per-job log sink: write stream, line split, rotation queue, and the output-driven repaint window. |
-| `runtime.ts` | Composition: job table, child handles, process events, repaint clock. |
-| `tui.ts` | The `/jobs` screen (a `DockListScreen` subclass: job rows, focus block, counts, verbs) and the `JobResult` transcript block over the shared `TailResult`. |
+| `runtime.ts` | The job table and the durable record: load and reconcile, the one settle path that announces a completion and its wake turn (holding either until the session arms its listener), waiters, clear, shutdown. |
+| `child.ts` | A job's process and its output: the spawn policy, the handle, the log stream and stdin, close/error settle, the signal and its SIGKILL grace, and the files a job leaves, over the shared `lib/child.ts` supervisor. |
+| `clock.ts` | The periodic work: the repaint clock that re-asserts the chip, and the sweep that polls the jobs this session reattached. |
+| `render.ts` | The `JobResult` transcript block over the shared `TailResult`. |
+| `view/jobs-screen.ts` | The `/jobs` screen (a `DockListScreen` subclass: job rows, focus block, counts, verbs), loaded on first use. |
 | `tools.ts` | The `job` tool and its transcript rendering. |
 | `commands.ts` | The `/jobs` command. |
 | `types.ts` | Shared types. |
@@ -409,10 +418,13 @@ rewritten.
 `extensions/job/` covers schema validation (`schema`), pure formatting and
 sanitization (`format`), the durable store (`store`), per-session reconciliation
 (`registry`), id reservation (`reservations`), exit-status recovery (`status`),
-session markers (`session`), bounded log reads and tail flags (`logs`), wait
-bookkeeping (`waiters`), the `job` tool (`tools`), the `/jobs` screen (`tui`),
-the runtime's session-scoped list and failure notification (`runtime`), `send`
-to a job's stdin and the pipe's lifecycle (`runtime`), log rotation, its two
-segments, and the cross-segment read (`runtime`), and the
-install/resume/shutdown lifecycle (`extension`). Tests drive a scripted
-`FakeChild` and a temp registry, so the suite runs without launching a process.
+session markers and the ownership rule (`session`), bounded log reads and tail
+flags (`logs`), log rotation and its two segments (`log-writer`), wait
+bookkeeping and the wait promise (`waiters`), the `job` tool (`tools`), the
+`/jobs` screen (`view/jobs-screen`), the table's session-scoped list,
+reattachment, clear and failure notification (`runtime`), a job's spawn, finish,
+kill, Windows policy, detached output, bounded tail and pid questions (`child`),
+`send` to a job's stdin and the pipe's lifecycle (`stdin`), the repaint clock and
+the external sweep (`clock`), and the install/resume/shutdown lifecycle
+(`extension`). Tests drive a scripted `FakeChild` and a temp registry, so the
+suite runs without launching a process.