@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/docs/terminal-tui.md

@@ -1,6 +1,6 @@
 # Harness terminal frontend
 
-Status: release candidate `@xingular/harness` 4.0.0; npm publication blocked by registry authorization. Last updated: 2026-10-24.
+Status: current terminal behavior, checked against `@xingular/harness` 1.3.0. Last updated: 2026-11-19.
 Decision: [ADR-0001](decisions/ADR-0001-owned-terminal.md),
 [ADR-0006](decisions/ADR-0006-opentui-only-terminal.md),
 [ADR-0009](decisions/ADR-0009-xharness-command.md),
@@ -29,12 +29,19 @@ overrides the Bun executable.
 `TerminalRuntime`, session replacement, commands, decisions, account pinning and run records. It
 projects the runtime's snapshot and transcript into an OpenCode-inspired view, with a native
 OpenTUI textarea for the prompt, `Ctrl+K` for the command palette, `Return` to send (or to queue behind a running reply),
-`Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline. With an
-empty composer, unmodified Up recalls the latest non-empty user message from the active session.
-After recall, unmodified Up/Down are available for normal editor movement and do not browse history
-while the draft is non-empty. Ctrl+Up/Down remain explicit history shortcuts; Down past the newest
-entry restores a blank draft. History comes from the active Pi session's saved messages, so `/new`
-and `/session` (also `/resume`) switch to that session's history. Steering needs a terminal that reports Cmd with the
+`Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline. Typing `/` or `$` filters
+matching commands or skills; `Tab` inserts the selected entry and leaves the cursor at the end of the inserted text.
+With an empty composer, unmodified Up recalls the latest non-empty user message from the active session.
+With a draft, unmodified Up browses older history and Down browses newer history when the caret is at
+either absolute draft endpoint (start or end). Down past the newest entry restores the draft, cursor
+and attachments that were present when history browsing began. At non-endpoint positions, Up on the
+first visual line moves the cursor to the first character and Down on the last visual line moves it
+to the final character; elsewhere, Up/Down move the caret normally. Ctrl+Up/Down remain explicit
+history shortcuts from anywhere. History includes
+user messages and Bash commands from the active Pi session; recalled Bash commands return to `!`
+mode. Executed slash commands from this terminal instance are included too, across session switches.
+`/new` and `/session` (also `/resume`) switch the saved-message and Bash history to that session.
+Steering needs a terminal that reports Cmd with the
 kitty keyboard protocol; elsewhere `Alt+Return` steers. In the composer, `Tab` opens up to eight matching filesystem entries for the path token at the cursor, or current-folder entries when the token is empty. The list has no heading or hint row. Up/Down select; Enter or Tab inserts the selection; Escape closes the list. Directories end in `/`, and Bash mode escapes shell-special characters. Use `/effort` or Shift+Up/Down to change effort. The command palette opens above the composer under a muted (`dim`) top rule, and has no other border. Its rows align slash commands and descriptions in two columns: the command column sizes to the widest visible name, bounded to preserve description space, and both columns wrap instead of truncating. The plan-choice rule, question block's top-only divider, and `/btw` block's top rule use the same muted color as the normal composer divider. The console has no background of its own: the renderer, root surface
 and transcript are transparent, so the terminal's own background shows through, while panels,
 dialogs and the scrim stay opaque. The composer has no panel background: it is bounded by a top and
@@ -63,7 +70,9 @@ colour. A full-screen scrim dims the console behind the panel so the transcript
 visible. Centered Harness dialogs fit their rendered content, capped by the available dialog
 height, with four columns of horizontal padding and two rows of vertical padding to account for
 the terminal's taller-than-wide cells. They use a plain title with a muted `Esc` hint and
-omit divider rules and footer hints. Shortcut behavior remains available. Searchable lists share
+omit divider rules and footer hints. Shortcut behavior remains available. Bracketed paste and the
+clipboard-paste shortcut insert text into the active dialog input or search field, using that
+component's input semantics; images and file attachments remain composer-only. Searchable lists share
 the same glyph, placeholder, spacing, and muted result note, with search context included on that
 row. A terminal too small for a 30-column by
 12-row dialog falls back to the full-screen page chrome. A plugin's full-screen surface stays full
@@ -84,10 +93,11 @@ The frontend is verified with a real isolated PTY and a loopback provider. Run
 `python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
 welcome, product label, accent colors and `/help` transition. Run
 `python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
-and a user bubble, unknown-command and argument colors, explicit-newline and soft-wrap checks of both
-prompt gutters, and normal/plan/Bash mode exclusivity. Run it with `--sizes 40x20,80x24,120x40` for
-compact through wide layouts. Use `--file-completion-only` for filesystem completion and insertion,
-`--history-only` for active-session history across `/new` and `/session`, `--help-only` for `/help` replacing the welcome screen with grouped two-column output that wraps without per-command gaps, `--questions-only` for recommended choices,
+and a user bubble, enabled-skill colors in the composer, unknown-token and argument colors,
+explicit-newline and soft-wrap checks of both prompt gutters, and normal/plan/Bash mode exclusivity.
+Run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
+input dialog, `--file-completion-only` for filesystem completion and insertion,
+`--history-only` for active-session history across `/new` and `/session`, `--resume-only` for the full-screen searchable, unnumbered two-line saved-session picker, `--help-only` for `/help` replacing the welcome screen with grouped two-column output that wraps without per-command gaps, `--questions-only` for multi-select marker glyphs, recommended choices,
 selected-row and Continue/Submit colors, `--jump-latest-only` for scroll-away badge visibility and click-to-latest (screen-level click assertions use optional `pyte`), and choice-backed “Something else” answers, or `--thinking-only` for `/thinking` visibility toggles. The full suite covers a complete turn, `read`, `bash` approval, `ask_user_question` approval and picker, plugin overlay/widget/status
 disposal, a completed run record with usage and decision events, `/help`, `/permissions`,
 `/settings`, `/model`, palette selection, confirm cancel, and Ctrl+D exit. `--questions-only` checks
@@ -109,16 +119,29 @@ The terminal joins outstanding children before its final reply, projects child a
 with their original run IDs, and stops descendants when interrupted or disposed. Connected apps
 need not be enabled. `TerminalPrepareInput.subagents: null` disables the capability.
 
-The terminal also projects the active parent's subagent descendants into live rows under the
-status line and a searchable `/subagents` page. The rows poll a private monitor route once per
-second during a turn. They sit one blank row below the status line, with no heading, and each
-reads: the status mark, the agent profile name in its colour (`subagent` for a copy of the
-parent), the title the parent gave the child (PROP-0030), and `n of m tasks` from the child's own
-checklist. At most three show, active first, then `+N more · /subagents`. The `/subagents` page
-adds status, elapsed time and the latest tool name. The projection is read-only, flat across nested
-descendants, and scoped to the current parent run; it keeps finished child rows until that parent
-settles. It never includes tool arguments (beyond the title), output or
-checklist item text.
+The terminal also projects the latest parent's subagent descendants into rows under the status line
+and a searchable `/subagents` page. The rows poll a private monitor route once per second
+during a turn and make a final read at settlement. They sit one blank row below the status line, with
+no heading, and each reads: the status mark, the agent profile name in its colour (`subagent` for a
+copy of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` from the
+child's own todo list. At most three show, active first, then `+N more · /subagents`. The
+`/subagents` page uses a colored profile and normal-color title on the first line, then muted account,
+effective model, effort and cumulative usage metadata on the second. One blank row separates each
+two-line entry. The page also shows status, elapsed time and the latest tool name. Runtime metadata
+stays in the private terminal projection.
+Usage contains safe token/cache/cost/context totals, not per-request payloads or reasoning summaries.
+The projection is read-only, flat across nested descendants, and scoped to the latest parent run in
+this terminal session; finished rows remain visible until the next parent run starts. The page also
+pins a `main` row for the parent run itself, with the same details; the rows under the status line
+leave it out. Reopening a conversation (a new launch, `/resume`, or a switch) rebuilds the rows from
+the branch's latest parent run and its saved child runs, with their final status, until the next run
+starts. A switch to a conversation without one clears them, as does disposal. It never includes tool
+arguments (beyond the title), output or todo item text.
+
+An interrupted or failed child keeps its saved conversation. The next reply is told which children
+stopped before it answers, and the parent continues one with `spawn_subagent { continue: <runId> }`,
+which reopens that child's own history with its profile and tools (ADR-0043). Esc therefore does
+not lose a child's progress.
 
 `/agents` opens the Agents page (PROP-0029): built-in, global, project and variant profiles with
 their tools, plugins, variant, model and instructions. Enter on a row edits a person's own profile
@@ -136,7 +159,7 @@ Harness owns its interactive terminal application in
 [`src/terminal/opentui/`](../src/terminal/opentui/). [`app.ts`](../src/terminal/opentui/app.ts)
 owns terminal lifecycle, submission, commands, decisions and run records;
 [`root.tsx`](../src/terminal/opentui/root.tsx) owns composition, the transcript, the composer,
-palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.2.0 supplies the
+palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.4.0 supplies the
 persistent agent session, model and auth runtime, native JSONL history, tool execution and rich
 content components.
 
@@ -199,8 +222,10 @@ before the compaction (rebuilt from Pi's session history, kept messages included
 rule; then the work that followed. The summary is shown by default. Clicking either rule hides or
 shows it, and Ctrl+O shows every summary again. On a narrow screen the rule drops the click hint, then
 the token count. Earlier compactions in the same session keep their own rules and summary in place.
-Notices stay after the message they followed. The model still sees only the summary and the recent
-messages; this is presentation only.
+Notices stay after the message they followed. The model sees the summary and recent messages plus a
+bounded, hidden checkpoint of the active request, todo list and plan instructions when available;
+the checkpoint is regenerated for each post-compaction request until the run settles. The visible
+transcript remains a presentation of the full history, not the model context.
 Transcript entry ids follow positions in the displayed message list, so when a rebuilt list moves a
 different kind of entry onto an id, the renderer builds a new component for it instead of reusing the
 old layout, and each entry draws inside its own error boundary. A run therefore keeps updating live
@@ -251,13 +276,20 @@ OSC 8 support. Inline and fenced code use a subtle panel fill with syntax colors
 list markers, tables, dividers and task-list markers use the existing titanium palette. Images
 display their alt text and are not fetched or rendered as image files.
 
-## Checklist block
+## Todo block
 
-`checklist_write` is registered in terminal sessions (PAR-001). Each call renders in the
-transcript as a checklist block: a status mark, `Checklist · n of m done`, then one line per item
-with `✓` (done, success colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim). A call whose
-arguments are not a checklist, or that failed, stays an ordinary tool row. The prompt's Progress
-group asks the model to keep the list current because the user follows work from it.
+`todo_write` is registered in terminal sessions (PAR-001). Each call renders in the transcript as
+a todo block: a status mark, `Todo · n of m done`, then one line per item with `✓` (done, success
+colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim). Each row reserves a one-cell
+status column and one-cell gap; item text and wrapped lines share the same starting column. A call
+whose arguments are not a todo list, or that failed, stays an ordinary tool row. The prompt's
+Progress group asks the model to keep the list current and write a final update before replying;
+unfinished work remains unfinished rather than being marked complete.
+
+`/todo` (alias `/checklist`) appends a snapshot of the current list: the same header and rows, with
+no status mark on the header, because it is not a tool call. It reads the latest non-side-question
+run of this terminal's native session and makes no model request; an empty list is a one-line
+notice.
 
 ## Blocks and pages
 
@@ -282,20 +314,36 @@ frontends draw that field from the same muted-blue selection palette (`selection
 explicit high-contrast text on it instead of the accent colour, so a choice reads the same in every
 list. Rules use the theme's `warning` and `dim` colors, so a custom theme restyles them.
 
-The Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills, Plugins,
-Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/plugins`, `/connections`
-(`/mcp`) and `/tools` open sections. `/hub` selects Discover and `/components` selects Library.
-The existing Accounts, Permissions, Settings, Trajectory and Log pages retain their own tabs.
+The broad Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills,
+Plugins, Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/connections`
+(`/mcp`), `/tools` and `/components` open sections. `/plugins` is a separate
+full-screen local manager with Plugins, Trust and Packages tabs; `/hub` is a separate
+full-screen Community catalog with Catalog and Installed tabs. Both keep a searchable
+inventory beside selected-item details on wide terminals, stacking details below the list
+on compact terminals. The existing Accounts, Permissions, Settings, Trajectory and Log
+pages retain their own tabs.
 
 `/settings` includes a Browser tab with the device-local **Private address access** setting. It is
 off by default. Enabling it asks for confirmation and allows agent browsing and annotation capture
 to reach localhost and private networks.
 
-Resource sections share Installed/Discover and source filters. Installed includes locally present
-resources; current-session availability comes only from the runtime loader and active tool registry.
-Discover uses the existing Hub with All/Community/Official filtering and an explicit remote refresh.
-No matching community entries is an empty result, never replaced with built-in resources.
-The view preserves search across source switches and restores section selection on return.
+Within the broad `/harness` browser, resource sections share Installed/Discover and source filters.
+Installed includes locally present resources; current-session availability comes only from the runtime
+loader and active tool registry. Discover uses the unfiltered Hub service with All/Community/Official
+filters and an explicit refresh. No matching Community entries is an empty result, never replaced with
+built-in resources. The view preserves search across source switches and restores section selection.
+
+The dedicated `/hub` Catalog shows Community entries across supported types only. Its Installed tab
+shows receipts from every channel with the channel labeled. On each page entry, cached/bundled entries
+appear first, then the remote catalog refreshes; the status keeps the origin, last-refresh time and any
+stale/error feedback visible. Manual refresh remains available. Catalog installs are pinned to the
+selected version, and Hub uninstalls remove only receipt-owned resources. Registry/document entries
+offer a bounded payload Preview; Pi packages have no JSON payload Preview.
+
+The `/plugins` manager keeps local switching, code trust and settings separate from public discovery.
+Its Packages tab adds local package installation, update and removal. Hub-owned packages remain pinned
+to exact catalog versions; removal goes through Hub receipt cleanup, and updating requires an explicit
+Hub version replacement.
 
 The browser fills the terminal (PROP-0014), with Overview, Foundation, Variant, Skills, Plugins,
 Connections, Tools and Library as persistent top tabs. The section dropdown and sidebar are removed.
@@ -310,8 +358,8 @@ Left/Right changes the focused tab or control; Enter on the tab strip returns to
 Ctrl+F focuses search. Escape returns from content to actions, returns to the list, clears search,
 then closes. Mouse clicks select tabs directly, activate resource actions and focus filters;
 wheel scrolling targets the list or inspector under the pointer. Other command pages keep their
-centered presentation; `/settings` and `/accounts` use full-screen page layouts. Closing the browser preserves
-the composer draft and attachments.
+centered presentation; `/settings`, `/accounts`, `/plugins` and `/hub` use full-screen page layouts.
+Closing the browser preserves the composer draft and attachments.
 
 Foundation explains fixed runtime ownership; it is read-only. Variant shows c1–c8 with the
 prepared version and current head separately. It previews pinned files from the preparation
@@ -342,7 +390,7 @@ skill import rejects symbolic links and limits bytes, files and traversal. See
 
 ## Annotate pane (PROP-0018)
 
-`/plugin:annotate` opens a full-screen page that works beside the window being inspected. That window is one of:
+`/annotate:` opens the full-screen capture pane (equivalent to `/annotate:annotate`) beside the window being inspected. Add a page address with `/annotate:annotate [url]`. The target window is one of:
 - the visible capture browser
 - an app's own windows attached over its DevTools port (`--app`)
 - app windows that loaded the page bridge script (`--bridge`)
@@ -357,7 +405,7 @@ The header shows the target and window and whether the inspector is on. The list
 | `t` | choose a window |
 | `Enter` | the note menu |
 
-The page has no search row, so these letters are free for actions. `/plugin:notes` keeps the searchable list.
+The page has no search row, so these letters are free for actions. `/annotate:notes` opens the searchable Web annotations list.
 
 ## Plan mode and thinking keys
 
@@ -365,11 +413,20 @@ Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi'
 queue until the active response settles, then runs by itself. Later messages remain behind it, even
 when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
 (`read`, `grep`, `find`, `ls`), web search/page reading, questions (`ask_user`, `ask_user_question`)
-and recall (history and Wiki reads, `memory_facts`). Normal mode omits both question tools from the
-active set; the plan request enables registered questions temporarily and restores the normal set
-when it settles, including on failure or interruption. Providers may mark individual calls as safe for
-research; every other call is blocked before approval. Edits, writes, shell commands, memory writes,
-subagents and connected-app tools remain unavailable. The plan instructions arrive as a
+and recall (history and Wiki reads, `memory_facts`). The parent may also run Bash in the
+OS-enforced read-only sandbox: no network and no writes except a discarded per-command temporary
+directory (PROP-0043). It may delegate bounded research to a named profile whose effective tool and
+plugin allowlists qualify for research; the child inherits plan mode and receives only the
+intersection of the parent's frozen capabilities, profile and plan-research set. Children cannot
+write, run commands, ask the user, use connectors or spawn more children; they remain bounded by the
+configured work-slice policy without gaining `checkpoint_write`, and the Harness records an
+evidence-derived checkpoint if the child stops at a boundary. Normal mode omits both question tools
+from the active set; the plan request enables registered questions and research delegation
+temporarily and restores the normal set when it settles, including on failure or interruption.
+Providers may mark individual calls as safe for research; every other call is blocked before
+approval. Edits, writes, memory writes and connected-app tools remain unavailable to parent and
+child; generic browser controls are also blocked. Sandboxed read-only Bash is the parent's only
+plan-mode shell exception; children cannot run commands. The plan instructions arrive as a
 request-scoped prompt section, which the next ordinary request withdraws.
 
 Each mode keeps its own model and effort for the account. Every selection the person makes (the model
@@ -382,7 +439,7 @@ and the App reads and writes them through `accounts.choices` and `accounts.choos
 A bare `/plan` toggles plan mode, and Shift+Tab cycles between normal and plan mode. Normal, plan
 and Bash are mutually exclusive composer modes. While plan mode is on, each submitted message is sent
 as a plan request through that same queue, and the composer's top and bottom rules take the plan colour.
-Commands still run as commands. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
+Commands still run as commands. The model may run Bash during a plan request, only in the read-only sandbox scope (PROP-0043); your own `!` commands are not part of the plan. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
 switches to plan mode and keeps the draft text. Turning plan mode off returns to normal mode. The old
 on/off/toggle forms are rejected; a bare `/plan` is the switch.
 
@@ -417,13 +474,17 @@ the marker and rules blue; in the normal prompt, the marker matches the divider
 an empty Bash body returns to the normal prompt. Submitting while a reply is active queues
 the command as a standalone turn; it does not steer the current model request.
 
-The terminal extension checks Bash policy and requests approval before using Pi's native
-`executeBash`. Output streams into the transcript while the command runs, so browser-login URLs are
-visible before the command finishes; the running item shows that Escape stops the command. The
-native result is recorded in run activity and session history before the model is prompted to read
-and explain it. This does not attach interactive stdin to the shell. SDK callers may opt into this
-behavior with `SessionRunInput.initialBashCommand`; it is restricted to a new interactive user turn
-and the session runner applies the same Bash gate.
+The terminal checks Bash policy before using Pi's native `executeBash`. Ordinary `!command` runs
+workspace-scoped; `!outside <command>` explicitly requests human-only approval before the command
+runs once with broader filesystem access. The complete command is shown as escaped, scrollable
+approval details; if the terminal is too small to show both details and choices, the request is
+denied. Shell output never triggers approval or replay. Output streams into the transcript while the
+command runs, so browser-login URLs are visible before the
+command finishes; the running item shows that Escape stops the command. The native result is
+recorded in run activity and session history before the model is prompted to read and explain it.
+This does not attach interactive stdin to the shell. SDK callers may opt into this behavior with
+`SessionRunInput.initialBashCommand`; it is restricted to a new interactive user turn and the
+session runner applies the same Bash gate and explicit outside-scope request.
 
 ## Reference and reproduced presentation
 
@@ -467,7 +528,7 @@ Full upstream copyright and MIT permission notices are in [NOTICE.md](../NOTICE.
 ## Runtime compatibility adapter
 
 Most integration uses public Pi exports. [`piAdapter.ts`](../src/terminal/tui/piAdapter.ts)
-contains the remaining presentation dependencies and requires exactly Pi **1.2.0** before
+contains the remaining presentation dependencies and requires exactly Pi **1.4.0** before
 loading them. The shared [`runtime.ts`](../src/pi/runtime.ts) loader imports Pi first, then invokes
 the same HTTP dispatcher hook as Pi's CLI before any Harness Pi runtime is used. This reapplies
 the process `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` settings after Pi's bundled Undici has
@@ -477,7 +538,7 @@ concurrent initialization.
 
 | Internal dependency | Reason |
 |---|---|
-| `dist/bundle/chunks/chunk-TJXZSVTD.js:configureHttpDispatcher` | Restore Pi's environment-aware HTTP proxy dispatcher after the SDK import |
+| `dist/bundle/chunks/chunk-MM3LKT73.js:configureHttpDispatcher` | Restore Pi's environment-aware HTTP proxy dispatcher after the SDK import |
 | `dist/extensions/index.js` builtin inventory | Preserve selected `llama.cpp`, `codemode`, `tool-search` and MCP builtins with the CLI's replacement semantics |
 | `dist/modes/interactive/theme/theme.js:setThemeInstance` | Keep public native rich components on the same active theme as the Harness screen |
 | `dist/core/tools/renderers/index.js:withBuiltInRenderers` | Preserve existing read/edit/bash/write formatting without replacing tool execution |
@@ -584,13 +645,16 @@ The bridge registers the shared `ask_user` batch tool alongside the single-quest
 `ask_user_question` contract; only plan requests activate them. Each question has a concise 1–2 word
 label, at least one choice, and at least one recommended choice; recommendations remain visual and
 never preselect. Choice-based questions also retain a free-text “Something else” answer. A pending
-question appears in a flat block immediately above the composer, not in a modal. It has only a muted
-top divider and separates its hint from the content by one blank line; below 60 terminal columns,
-it uses a compact hint. The body is height-bounded and vertically scrollable, with tabs and
-answer/action controls outside that region. While the dock is active, PageUp/PageDown scroll its
-body and Ctrl+Home/End jump to its beginning/end instead of the transcript. Focused choices and
-note fields are brought into view. A tab strip shows each
-question label above the active question title, with one blank row below the tabs and below the title;
+question occupies the composer position in a flat block, not a modal, with the chat transcript
+above it. The dock fits its content and grows to at most two-thirds of the terminal height; each
+question tab is sized from its own content. When content overflows, its body scrolls while tabs and
+answer/action controls stay outside that region.
+The final choice sits one blank row above “Something else”. The block has only a muted top divider
+and separates its hint from the content by one blank line; below 60 terminal columns, it uses a
+compact hint. While the dock is active, PageUp/PageDown scroll its body and Ctrl+Home/End jump to
+its beginning/end instead of the transcript. Focused choices and note fields are brought into view.
+A tab strip shows each question label above the active question title, with one blank row below the tabs
+and below the title;
 clicking a tab or using Left/Right changes questions without discarding staged answers. The header has
 no pager controls, and the block cannot be collapsed. Choices and descriptions appear above the numbered free-text answer and Continue or Skip
 action. Selected choices fill the whole row with subtle dark green; Continue and Submit uses a
@@ -614,6 +678,8 @@ The dock uses one shared measured layout for all choices: marker gutter, one-thi
 two-cell gap, and remaining description cell. Boundaries align across rows at every width, including
 compact terminals; both cells wrap independently, missing descriptions keep their cell, and columns
 never stack. Recommendation text becomes `(Rec.)` when the label column is fewer than 14 cells.
+Multi-select choices use `✓` when selected and `○` when unselected, matching checklist glyphs;
+single-choice options remain numbered.
 
 One shared border-only monospace preview below the choices follows the hovered choice, falling
 back to keyboard focus. It has no visible caption or extra left rule. Under the approved
@@ -662,12 +728,21 @@ and prompts. `/session` selects a saved session (`/resume` remains an alias), an
 branches in the current session (`/tree` remains an alias). `/btw <question>` asks a side question;
 `/side` is its alias. Help and the slash-command palette show each pair once, as `/session (resume)`,
 `/history (tree)` and `/btw (side)`; aliases still match palette searches.
-The separate `$` palette completes enabled skill invocations; `/skills` always browses skills. `/help`
-renders the command list as one transcript entry, grouped under Core, Run, Model, Session, Inspect,
-Harness, Plugins and Prompts; command names and descriptions wrap in aligned columns, with no
-blank rows between choices. `/plugins` opens the browser with protected code trust and plugin settings actions. Settings use
-`plugins.configure`; on/off settings and bounded whole-number settings keep their existing ranges.
-Saved settings are read when the plugin next uses them and do not require a restart. The standalone
+With no path argument, `/session` opens a full-screen searchable page. Each unnumbered row shows a
+normal-color title and a muted second line with relative activity time, `<project>:<branch>` and JSONL
+file size separated by ` · `. One blank line separates each session. Enter resumes the selected
+session; account and folder scope checks
+remain enforced. Supplying an explicit path continues directly without opening the picker.
+The `$` palette completes enabled skill invocations using the same two-column palette as slash
+commands; `/skills` always browses skills. Choosing a skill inserts `$name ` without submitting.
+A recognized leading `$name` uses the blue accent in the composer, while its arguments, unavailable
+names and ordinary currency text keep the normal color. `/help` renders the command list as one
+transcript entry, grouped under Core, Run, Model, Session, Inspect, Harness, Plugins and Prompts;
+command names and descriptions wrap in aligned columns, with no blank rows between choices. `/plugins`
+opens the focused local manager; its Packages tab installs, updates and removes packages with protected
+Harness operations. Settings use `plugins.configure`; on/off settings and bounded whole-number settings
+keep their existing ranges. Saved settings are read when the plugin next uses them and do not require a
+restart. The standalone
 terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/share`, `/scoped-mode` or
 `/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
 main run's effective instructions, visible conversation and redacted public tool inputs/results.
@@ -696,14 +771,18 @@ and URL queries and omits response bodies, prompts and message contents. Embedde
 
 ## Slash command ownership
 
-Core commands and commands owned by required built-in plugins stay unprefixed. The required
-plugin commands are `/subagents`, `/agents`, `/trajectory`, `/doctor`, and `/worktree`. Optional built-in
-plugin commands (currently `/plugin:notes` and `/plugin:annotate`) and Pi extension commands use
-`/plugin:<command>`. A bare core command, alias, required built-in command, or loaded prompt owns its
-name; a colliding prefixed command is omitted and rejected with a hint to use the bare command.
-Duplicate extension names are rejected with the extension paths shown in the diagnostic. Old
-`/plugin:` forms of required built-in commands are not aliases. Prompt templates and
-`/skill:<name>` keep their existing forms.
+Harness core commands are unprefixed and live in the core terminal command registry, independently
+of feature-plugin command metadata: `/doctor`, `/worktree`, `/trajectory`, `/subagents`, and `/agents`.
+`/history` (also `/tree`) continues to navigate session branches. `/mcp` and `/connections` open the
+Connections browser. Feature descriptors and their services remain registered; only these terminal
+routes move out of the plugin command registry. Other plugin-owned commands continue to use
+`/<owner-prefix>:<command>`. The annotations plugin uses `/annotate:annotate` and `/annotate:notes`;
+`/annotate:` opens its default capture pane. Pi package extensions use their normalized package name
+as owner prefix unless `harness.commandPrefix` overrides it; loose extensions use their normalized
+extension name. A plugin prefix collision or a duplicate command within one owner is rejected with
+owner paths in the diagnostic. The former owner-qualified and `/plugin:<command>` routes of promoted
+Harness commands remain hidden compatibility aliases for one release, omitted from help and
+completion. Prompt templates and `/skill:<name>` keep their existing forms.
 
 ## Input performance profile
 
@@ -853,8 +932,9 @@ inherit that retained ledger.
 
 ## Agent-managed session names
 
-Agents can use `session_name({ name: string })` to name meaningful work early and revise
-its name when the objective changes. Names submitted by agents are short imperative
+Agents can use `session_name({ name: string })` to name work before their first other tool call
+when a request needs tools or changes state, and revise the name only when the objective changes.
+Names submitted by agents are short imperative
 sentences with at most six words. The agent may revise a manual name; `/name` remains
 available and manual names have no new word limit. Pi stores the name in native history,
 so resuming the same conversation restores it without another model request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "1.1.1",
+  "version": "1.3.1-unstable.0",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness built on recursive harnessing (Harness²): versioned eight-component variants, refinement from evidence, multi-account sessions, a compiled prompt, project notes, tools, and MCP",
   "repository": {
@@ -35,6 +35,7 @@
     "test": "vitest run",
     "profile:terminal-input": "node scripts/profile-terminal-input.mjs",
     "profile:terminal-latency": "python3 scripts/profile-terminal-latency.py",
+    "profile:session-runtime": "node scripts/profile-session-runtime.mjs",
     "prove": "npm run build && node scripts/prove-standalone.mjs",
     "build:sdk": "node scripts/build-sdk.mjs",
     "release:pack": "node scripts/release-pack.mjs",
@@ -42,8 +43,8 @@
     "release:preflight": "node scripts/release-preflight.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "1.2.0",
-    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@modelcontextprotocol/client": "^2.2.0",
     "@modelcontextprotocol/server": "^2.2.0",
     "@opentui/core": "^0.6.6",

package/dist/sdk/tools/checklist.d.ts

@@ -1,9 +0,0 @@
-import { type ChecklistItem, type RunEvent } from "../sessions/contracts.js";
-import type { ActiveRun } from "../sessions/registry.js";
-import type { ToolSpec } from "./types.js";
-export declare const CHECKLIST_WRITE = "checklist_write";
-/** The checklist as the model reads it back. */
-export declare function describeChecklist(items: readonly ChecklistItem[]): string;
-/** The latest checklist a run wrote, or an empty list. */
-export declare function checklistOf(events: readonly RunEvent[]): ChecklistItem[];
-export declare function checklistTool(run: Pick<ActiveRun, 'emit'>): ToolSpec;

package/dist/sdk/tools/checklist.js

@@ -1,54 +0,0 @@
-// The run's own checklist: the model writes the whole list each time, and the run records it as
-// a `checklist.updated` event. It only changes run state, so it stays callable in plan mode.
-import { checklistItemSchema, MAX_CHECKLIST_ITEMS } from "../sessions/contracts.js";
-export const CHECKLIST_WRITE = 'checklist_write';
-const MARK = { pending: '[ ]', in_progress: '[~]', completed: '[x]' };
-/** The checklist as the model reads it back. */
-export function describeChecklist(items) {
-    if (!items.length)
-        return 'The checklist is empty.';
-    return items.map((item) => `${MARK[item.status]} ${item.text}`).join('\n');
-}
-/** The latest checklist a run wrote, or an empty list. */
-export function checklistOf(events) {
-    const last = events.filter((event) => event.type === 'checklist.updated').at(-1);
-    const items = last?.payload?.items;
-    return Array.isArray(items) ? items.flatMap((item) => {
-        const parsed = checklistItemSchema.safeParse(item);
-        return parsed.success ? [parsed.data] : [];
-    }) : [];
-}
-export function checklistTool(run) {
-    return {
-        name: CHECKLIST_WRITE,
-        label: 'Write the checklist',
-        description: 'Keep a checklist of the steps of the current work. The user watches this list to follow your progress, so write it early and keep it current. Send the whole list every time; it replaces the previous one. ' +
-            'Use it whenever the work has several distinct steps or will take several tool calls, when the user gives several things to do, and when a subagent brief asks for more than one thing. Do not use it for a single, simple step or for conversation. ' +
-            'Statuses: pending, in_progress, completed. Keep exactly one step in_progress while you work, mark a step completed as soon as it is done (not in batches), and add steps you discover. ' +
-            'Only mark a step completed when it is fully done; if something blocks it, keep it in_progress and add a step for the blocker.',
-        parameters: (Type) => Type.Object({
-            items: Type.Array(Type.Object({
-                text: Type.String({ description: 'One step, as a short imperative line' }),
-                status: Type.Union([Type.Literal('pending'), Type.Literal('in_progress'), Type.Literal('completed')])
-            }), { maxItems: MAX_CHECKLIST_ITEMS })
-        }),
-        readOnly: true,
-        planModeSafe: () => true,
-        execute: async (input) => {
-            if (!Array.isArray(input.items))
-                return 'Send items: the whole checklist as an array.';
-            if (input.items.length > MAX_CHECKLIST_ITEMS)
-                return `Keep the checklist to ${MAX_CHECKLIST_ITEMS} steps or fewer.`;
-            const items = [];
-            for (const raw of input.items) {
-                const entry = raw;
-                const parsed = checklistItemSchema.safeParse({ text: typeof entry?.text === 'string' ? entry.text.trim() : entry?.text, status: entry?.status });
-                if (!parsed.success)
-                    return 'Every step needs text of 1 to 500 characters and a status of pending, in_progress or completed.';
-                items.push(parsed.data);
-            }
-            run.emit('checklist.updated', { items });
-            return describeChecklist(items);
-        }
-    };
-}