@xingular/harness 1.6.0-unstable → 2.0.1-unstable

package/dist/terminal-pi.js

@@ -384,6 +384,15 @@ var questionRequestedPayload = z.object({
   multiSelect: z.boolean(),
   allowText: z.boolean(),
   userOnly: z.boolean().optional(),
+  /** The Pi extension dialog this question stands for (ADR-0083); a host may ignore it. */
+  dialog: z.object({
+    kind: z.enum(["select", "confirm", "input", "editor"]),
+    title: z.string().max(4e3),
+    message: z.string().max(4e3).optional(),
+    placeholder: z.string().max(4e3).optional(),
+    prefill: z.string().max(1e5).optional(),
+    options: z.array(z.string().max(4e3)).max(200).optional()
+  }).optional(),
   ...questionBatchFields
 }).superRefine(questionBatchRefinement).superRefine((value, context) => {
   const error = questionSketchError(value.uiSketch, value.options);

package/docs/architecture/02-sessions-and-runs.md

@@ -261,6 +261,58 @@ not positional message counts. A host can route `/history` to Harness `sessions.
 navigate the same saved session; it must not substitute a fork. Shared session catalog registration
 is approved but remains in progress; no completed cross-surface catalog is implied (PAR-008).
 
+## Live sessions (ADR-0083)
+
+A *live session* is a Pi session the harness keeps open between the runs of one conversation, so a
+later run reuses it instead of opening and loading a new one. `sessions/live.ts::LiveSessions` holds
+them, one per `run.sessionId`.
+
+- **Opt in.** `SessionRunInput.live: true` keeps the session open after the run and reuses an open
+  one. It is refused (`invalid_request`) for an unattended, child, nested, probe, improver or
+  reflection run, and refused with `session_busy` while another run of the session is using it.
+  Without `live` a run opens and disposes its own session, as before.
+- **Pins.** A live session serves a run only when everything the run pins equals what the session
+  was opened with: account and its config folder, variant scope and version, variant extensions and
+  skill paths, the frozen capability set, working folder, workspace root and history folder, plan
+  and plan-repair flags, the allowed, gated and bound tool names, the stable system prompt, model,
+  effort, the run-scoped extension names and whether provider tools are asked. A supplied history
+  file and native session id must be the session's own. Any difference closes the idle session at
+  the turn boundary and the run opens a fresh one on the same native history.
+- **Rebinding.** `piSessionFactory` reads the run's gate, bound tools, extension host and
+  plan flag through a binding that `PiSessionLike.rebind` replaces at the start of each run. The
+  run-scoped inline extensions (lineage join, subagents, compaction checkpoint, work slice, goal,
+  first-party hooks) are loaded in slots: a rebind removes the last run's handlers (Pi's `on`
+  returns the remover) and runs the next run's factory against the same extension. A session whose
+  run-scoped extension registers anything but handlers is not reusable. Between runs an extension
+  dialog is refused with `run_not_active`.
+- **One writer of the history.** A top-level run of the same session that is not live (a command
+  run, for example), and `sessions.navigate` or `sessions.rename` on its history folder, close an
+  idle live session first so nothing holds a stale copy of the file; while the live session is
+  replying they are refused with `session_busy`.
+- **Settling.** `runTurn` calls `TurnParams.release` instead of disposing the session. An idle live
+  session closes after 30 minutes (`SessionsOptions.liveIdleMs`), on `sessions.close`, or when the
+  harness closes.
+- **Follow-ups.** `sessions.followUp { sessionId, text }` starts the next run at once when the
+  session is idle, or queues the text (at most 20) for after the active run. The queue follows the
+  queued-message dispatch rule above: it is sent after a reply that completed or that the person
+  stopped, and parked after a failure or any other interruption; a work-slice continuation runs
+  first. A follow-up run repeats the last live run's input with its own text and no Bash, images,
+  command, continuation or goal. `runs.steer` steers the active run as before.
+- **Other run inputs a live client uses.** `newHistory: true` starts a new native history in
+  `sessionDir` (refused with `resume`, `continueFrom` or `command`). `hiddenNotes` (at most 8, each a
+  lower-case type and up to 20,000 characters) are saved as hidden messages before the request, as
+  the context update is. `planTools: 'active'` makes a plan run's frozen tool set the plan's own
+  (`planModeTools`), so the request carries only those tools; the default `gate` keeps every tool in
+  the request and refuses at the gate. An initial Bash command is accepted on a live turn that
+  resumes its history.
+- **Question dialogs.** `question.requested` may carry `dialog { kind: select | confirm | input |
+  editor, title, message?, placeholder?, prefill?, options? }` when a Pi extension's dialog asked it
+  (`sessions/extensionUi.ts`). A host may ignore it; the answer is the usual `QuestionAnswer`.
+- **Methods.** `sessions.live {}` → `{ sessions: LiveSessionStatus[] }`; `sessions.close { sessionId }`
+  → `{ closed, afterRun }` (a busy session closes when its run settles);
+  `sessions.followUp { sessionId, text }` → `{ runId } | { queued }`;
+  `sessions.followUp.clear { sessionId }` → `{ removed }`.
+
 ## Invariants
 
 - **INV-RUN-1** A run pins one account, one variant version, one capability set and one canonical
@@ -387,10 +439,16 @@ is approved but remains in progress; no completed cross-surface catalog is impli
   the tools running at that moment). Every live reply emits a
   heartbeat every 30 seconds, terminal replies included. A heartbeat older than five minutes while
   the owner process lives marks the run `interrupted` with reason `stalled`; a run that never emitted
-  one keeps the 30-minute silence rule. A reply whose heartbeat keeps arriving but which produces no
-  other event for fifteen minutes is a wedged turn, not a busy one: the terminal ends it through the
+  one keeps the 30-minute silence rule. A heartbeat of a run with no work slice carries zero slice
+  counters. A reply whose heartbeat keeps arriving but which produces no
+  other event for fifteen minutes is a wedged turn, not a busy one: the harness ends it through the
   native abort and records `interrupted` with reason `stalled`, and grants a reply whose oldest
-  running tool has run for thirty minutes the same ending. A reply whose only running tools are
+  running tool has run for thirty minutes the same ending. `runTurn` applies this to every run
+  (a structured session, a live session, the client terminal, an unattended run) with the same
+  windows (`sessions/stallWatch.ts`); the in-process terminal's controller applies it to its own
+  reply. A live session whose turn stalled is closed rather than reused, its queued follow-ups
+  parked for the next session, and closed under the turn after thirty seconds if the abort did not
+  unwind it (ADR-0083). A reply whose only running tools are
   `wait_subagents` or `spawn_subagent` is judged by its children instead: each child has its own
   clock (its last event other than a heartbeat; its running tools), and a child quiet for the same
   windows is interrupted with reason `stalled`, so the wait returns and the parent carries on by

package/docs/architecture/04-prompt.md

@@ -91,17 +91,19 @@ by ADR-0079: the reply is self-contained, outcome-first, explains the work and i
 limits, and gives the reader enough context to pick it up cold. It explicitly reports checks that
 were not run or failed; a person-owned next step appears only when one is needed. For substantial
 replies with distinct parts, it often uses content-named Markdown `#` and `##` headings; there is no
-fixed heading vocabulary or required template, and short replies may stay in prose. Tables are used
-for mappings and comparisons. Length follows complexity; prose comes first, with lists when the
-information is genuinely parallel, sequential or easier to compare. References and formatting
+fixed heading vocabulary or required template, and short replies may stay in prose. Code fences name
+the language; commands the person must run use a `bash` fence, while short references stay inline.
+Tables are used for mappings and comparisons. Length follows complexity; prose comes first, with
+lists when the information is genuinely parallel, sequential or easier to compare. References and formatting
 follow rules supplied by the active session or host. Progress updates stay in the standard `writing`
 section, not `reporting`. A subagent's reply gives its caller the concise work
 summary and key findings, with useful absolute paths and evidence; snippets appear only when exact
 text is load-bearing, and code merely read is not recapped. The section ships two examples (a
 headed screen change and a heading-free blocked publish), the shape-by-work table and a four-line
-pre-send list; the exact command for a blocked login is in `autonomy`. A person, application or mode
-format takes precedence. The section names no application, is never dynamic, and is never cut; its
-budget is 12,000 characters, with 4,853 currently delivered (ADR-0079).
+pre-send list; the blocked-publish example puts its login command in a `bash` fence. A person,
+application or mode format takes precedence. The section names no application, is never dynamic, and is never cut; its
+budget is 12,000 characters, with 5,081 currently delivered (ADR-0079, amended for language-labeled
+code fences).
 
 ## When a reply may end
 

package/docs/architecture/10-server-protocol.md

@@ -96,6 +96,10 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 - Run streams also carry `tool.refused` with the call id, name, refusal code and bounded reason.
   Run records expose nullable `terminalCode`; `terminalReason` remains descriptive text. Older
   records and events may omit the code. Trajectory search exposes both fields (pages 02 and 08).
+- `sessions.run` accepts `live: true` (ADR-0083): the Pi session stays open for the conversation's
+  next run. `sessions.live`, `sessions.close`, `sessions.followUp` and `sessions.followUp.clear`
+  manage live sessions (page 02). A run refused because the live session is replying fails with
+  `session_busy`.
 - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
 
 ## Browser configuration and extension (ADR-0082)
@@ -199,6 +203,23 @@ export instead of prompt submission (page 02). These retain tracked run lifecycl
 Saved-history helpers currently validate file scope but do not themselves fence active work;
 host adapters must not infer concurrency safety from method availability.
 
+## Socket transport and the long-lived harness (ADR-0083)
+
+`server/socket.ts::serveSocket` serves the same framing on a Unix socket, readable and writable by
+its owner only, with one peer per connection; a closed connection stops receiving events and
+notices. `connectHarness` is the matching client. The long-lived harness (page 11) adds
+`daemon.status` → `{ pid, startedAt, variantScope, live, detached }` and `daemon.stop` on its own
+socket only.
+
+| Method | Input | Reply |
+|---|---|---|
+| `terminal.detach` | `{ sessionId }` | `{ detached, activeRunId }`; a client terminal with a running reply keeps it without a window, anything else is disposed |
+| `terminal.detached` | `{}` | `{ sessions: DetachedTerminal[] }`: session id, folder, history folder, account, active run, history file, time |
+| `terminal.takeRelaunch` | `{ sessionId }` | the `TerminalRelaunch` the session asked for, or null |
+
+`terminal.prepare` accepts `attach: true` to reconnect to a detached session of the same id, folder,
+history folder and account. The private `terminal.live.*` routes are listed on page 11.
+
 ## Invariants
 
 - **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. Adding a method
@@ -207,7 +228,8 @@ host adapters must not infer concurrency safety from method availability.
 - **INV-SRV-2** A method handler calls the same in-process API a Node application uses. The server
   holds no logic of its own beyond parameter checking.
 - **INV-SRV-3** Events reach the host only after they are persisted and redacted (`INV-RUN-3`).
-- **INV-SRV-4** Changing the framing or `PROTOCOL_VERSION` is an architecture change.
+- **INV-SRV-4** Changing the framing or `PROTOCOL_VERSION` is an architecture change. A transport
+  that carries the same framing (stdio, the owner-only socket) is not; a new one is listed here.
 - **INV-SRV-5** The harness works with none of the host calls supplied (`INV-EXT-2`).
 - **INV-SRV-6** After a change to the server, the CLI or startup, `npm run prove` must pass: it
   starts the server on a throwaway data root with no application present and exercises accounts,

package/docs/architecture/11-terminal.md

@@ -144,13 +144,67 @@ The `/plugins` Proposals tab previews the complete stored files and generated ma
 confirmation. Accept and reject pass the preview hash through the control-key-protected socket;
 the proposal service checks it again. Acceptance leaves the package switched off and untrusted.
 
+## Client terminal and the long-lived harness (ADR-0083)
+
+The OpenTUI frontend is a client of the harness by default: `tui/harnessRuntime.ts` implements the
+same `TerminalRuntime` as `tui/runtime.ts`, so the screen code is shared.
+`XINGULAR_TERMINAL_RUNTIME=inprocess` runs the in-process runtime instead, for plugins that need
+their own terminal components (INV-TUI-8).
+
+- **Parent.** `terminal/liveTerminal.ts::LiveTerminal`, created on the first `terminal.live.*`
+  call, runs each turn as `sessions.run { live: true }` of the terminal's own session id, account,
+  folder, history folder, pinned variant version (`{ dir, scope }`), launch sections, Pi's four
+  default tools plus the launch and switched-on world tools, and no gated tools, as the in-process
+  terminal's policy has it. It journals the live session's native events (a newer
+  `message_update` replaces an unread one; at most 4,000) and serves them by long poll.
+- **Routes.** `terminal.live.state`, `.events { after, wait?, waitMs? }`, `.run { text, model?,
+  effort?, resume? | newHistory?, images?, plan?, goal?, command?, initialBashCommand?,
+  hiddenNotes? }`, `.steer`, `.followUp`, `.followUp.clear`, `.interrupt`, `.close { forget? }`,
+  `.rename`, `.pending`, `.pending.wait`, `.approve`, `.answer`, `.answers`. Once a client exists,
+  `terminal.pending|pending.wait|approve|answer|answers|interrupt` and remote control's send and
+  stop reach it instead of `TerminalController`. Pending decisions include the active reply's
+  subagents.
+- **Client.** It keeps the model catalogue, settings, the skills, prompts and themes it lists, and
+  `ModeChoices`. `$name` skills and goal notes go as `hiddenNotes`; a plugin command is sent as its
+  `/<prefix>:<name>` text; `/compact`, `/tree` navigation and HTML export are command runs;
+  `/new`, `/resume`, fork and import change the file it resumes and close the live session; `/session`
+  takes a history file or the session id its runs record. A `!` command is the run's initial Bash.
+  A plan run sends only the plan's tools (`planTools: 'active'`). A mode with no saved model keeps
+  the current one. Closing the client never interrupts a reply; the parent decides.
+- **What the window draws.** Besides the native events, the journal carries `harness_notice` (a
+  plugin's notice, status line, widget or title, and a failed reply's message), `harness_settled`
+  (the reply is over, with its goal state and history file, even when Pi's loop never started) and
+  `harness_dialog` / `harness_dialog_done` (a plugin's `select`, `confirm`, `input` or `editor`,
+  shown with the window's own dialog and closed when another surface answers first; the window's
+  question dock asks `terminal.pending.wait { ownDialogs: true }` and leaves them out). Before the
+  first turn the parent lists the trusted extensions' commands by loading them without a session;
+  one that cannot load stops the window's start, as in process. A session change or a steer first
+  asks the harness whether a reply really runs, so a window a moment behind its event stream does
+  not refuse `/new` or steer a reply that has ended.
+- **Failure.** When the window's harness is unreachable twice in a row, the window closes cleanly.
+  An error nothing caught in the standalone host (a plugin's timer, say) closes the window first,
+  then exits 1. The long-lived harness logs such an error and keeps its other sessions.
+- **Identity.** A client terminal's runs are harness runs: they record Pi's session id as
+  `nativeSessionId`, where an in-process terminal's record the history file. `/todo`,
+  `/trajectory`, `/context`, subagent rows and remote-control history match by the client's id, and
+  a relaunch resumes its history file.
+- **Long-lived harness.** `xagent daemon start|stop|status` runs one harness per state folder
+  (`terminal/daemon.ts`): a lock (`harness.lock`) refuses a second, and `harness.sock` (owner-only)
+  serves the protocol with `daemon.status` and `daemon.stop`. `xagent --daemon` starts it when
+  needed, prepares its terminal there and runs the client frontend. When the window closes while a
+  reply runs, `terminal.detach` keeps the reply and its live session without a window until it
+  settles; `xagent attach [session]` reattaches a new window to it (`prepare { attach: true }`, same
+  folder and account). Without a running reply, closing the window ends the session as before.
+
 ## Invariants
 
 - **INV-TUI-1** OpenTUI is the only terminal frontend. Pi's `InteractiveMode` is never constructed
   ([ADR-0006](../decisions/ADR-0006-opentui-only-terminal.md)).
 - **INV-TUI-2** The harness owns screen composition, input, scrolling, command routing and plugin
   UI. Pi owns the execution runtime, native history and rich content components. A host owns the
-  PTY and process supervision ([ADR-0001](../decisions/ADR-0001-owned-terminal.md)).
+  PTY and process supervision ([ADR-0001](../decisions/ADR-0001-owned-terminal.md)). In the default
+  client terminal the Pi session runs in the harness process as a live session (ADR-0083); the
+  window keeps composition, input and rendering.
 - **INV-TUI-3** Execution, account isolation, trust, authorization and run recording stay behind
   their existing layers. The terminal adds no second path for any of them; its runs are written
   through the controller and the run store.
@@ -167,8 +221,14 @@ the proposal service checks it again. Acceptance leaves the package switched off
   reconnects and resynchronizes after errors, and cancels its outstanding request on shutdown.
 - **INV-TUI-5** Every resource reload revalidates the original trusted selection; changed or
   revoked code needs review and a fresh terminal.
-- **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The terminal keeps a
-  persistent child instead of opening a session per turn.
+- **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The in-process terminal
+  keeps a persistent child instead of opening a session per turn; the client terminal (below) runs
+  every turn as a `sessions.run { live: true }` of one live session, which is equally persistent.
+- **INV-TUI-8** A client terminal runs no agent loop, tool or Pi extension of its own. It draws the
+  live session from its native events and its own read of the history file, and every action is a
+  protected `terminal.live.*` call (ADR-0083). Plugin presentation that needs an in-process
+  terminal (custom components, key handlers, renderers, shortcuts) is unavailable there, as it is
+  in a host: extensions get the dialog, notice, status and text-widget subset.
 - **INV-TUI-7** Harness core commands use unprefixed names and are registered independently of
   feature-plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents`
   and `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections
@@ -439,6 +499,10 @@ has run for thirty minutes ends the same way, and a reply waiting on an approval
 cut short. An interrupt, a stall included, also ends a settling reply's wait for its subagents
 (`terminal.subagents.delivery`).
 
+The client terminal (ADR-0083) has no controller of its own: its replies are harness runs, so
+`runTurn` heartbeats and applies the same stall rule (page 02, INV-RUN-14), and the live session of a
+stalled reply is closed. The in-process runtime keeps the controller's watch.
+
 ## Subagent activity monitor
 
 During an active parent run, the terminal polls a private read-only monitor once per second. It

package/docs/architecture/12-storage.md

@@ -49,7 +49,9 @@ index.
   browser.json        device-local BrowserConfig: backend, CDP, private-address policy and domains   (13)
   browser/             isolated profiles, downloads, and owner-only extension-bridge.json pairing state   (13, ADR-0082)
   notes-bridge.json    the page bridge's port and token, kept so an app's script tag stays valid   (13, PROP-0018)
-  harness.log          standalone terminal diagnostics
+  harness.log          standalone terminal and long-lived harness diagnostics
+  harness.sock         the long-lived harness's protocol socket, owner-only, while it runs   (10, ADR-0083)
+  harness.lock         { pid, startedAt, socket } of the one long-lived harness for this folder   (10, ADR-0083)
 ```
 
 `/remote-control` (page 15) stores nothing here: its pairing and device keys live in memory and end

package/docs/architecture/14-surfaces-and-parity.md

@@ -113,6 +113,10 @@ terminal command or page, a host screen.
   harness serves. It is not a host and owns no capability. A paired device acts through the same
   `Terminals` and controller paths as the terminal, and reaches no command, shell, link, plugin or
   account control.
+- The terminal is a client of the harness by default (page 11, ADR-0083): it presents the same
+  capabilities over harness live sessions, and its plugin presentation is the host subset
+  (INV-TUI-8). Its runs, approvals and questions are the structured path's, so the terminal and a
+  host share one lifecycle. `XINGULAR_TERMINAL_RUNTIME=inprocess` keeps the in-process runtime.
 - The register of capabilities and their surfaces is [`docs/parity.md`](../parity.md). It is
   descriptive; the invariants below are binding.
 - A host keeps its own register of host-only surfaces. The Harness names no host surface.

package/docs/architecture/15-remote-control.md

@@ -78,7 +78,9 @@ Phone browser ── http://<tailscale or LAN address>:<port> ──> RemoteCont
   the data root or the state directory; a phone keeps its own device key in its browser storage.
 - **INV-RC-3** A paired device acts only through the terminal's existing paths: `Terminals.send`,
   and `TerminalController.control` for `terminal.interrupt`, `terminal.approve`,
-  `terminal.answer`, `terminal.answers` and `terminal.pending.wait`. The validation those paths
+  `terminal.answer`, `terminal.answers` and `terminal.pending.wait`. For a client terminal
+  (ADR-0083) the same calls reach its `LiveTerminal`, and a message goes as a new reply or a
+  follow-up of the live session. The validation those paths
   apply (a busy session, a terminal draft, the rememberable check on "always allow", the policy
   recheck of a direct approval) applies unchanged.
 - **INV-RC-4** A decision is shown on the phone with its complete action text, never shortened,

package/docs/architecture/README.md

@@ -109,6 +109,11 @@ resolve relevant drift by updating the implementation and specification together
 
 | ID | Where | What disagrees |
 |---|---|---|
+| D-32 | Ordered and nested list wrapping, `opentui/markdown.ts` (`alignListItems`) | The transcript renderer was written to keep a list item's wrapped lines beneath its text (nested lists and ordered markers wider than one digit). A general OpenTUI `renderNode` drops the blank rows between paragraphs and headings, so the renderer is code-block-only (`codeBlockOnly`) and lists no longer reach `alignListItems`: they wrap as in the previous release, continuation rows at column 4 where 7 was wanted. The verifier no longer checks it. Open; needs either structured lists with the block spacing restored, or OpenTUI support for both. |
+| D-31 | `scripts/verify-terminal.py --markdown-only` — resolved 2026-11-04 | The fixture sent 100 list items and its checks read the 40 visible rows. It now sends three short lists (starting at 1, 10 and 100) on a 120x72 screen. The suite also found the blank rows between paragraphs and headings missing with the new renderer, which is why that renderer is now code-block-only (D-32). |
+| D-30 | `scripts/verify-terminal.py` focused suites — resolved 2026-11-04 | The `browser`, `palette`, `accounts` and `trajectory` suites asserted layouts the terminal no longer draws; the product was right. Browser: the skill's description wraps in the 40-column completion column ("Inspect a" / "browser fixture."). Palette: command names carry their owner (ADR-0061) and wrap, and a narrow palette shows three lines per row. Accounts at 120x40: the search field holds the typed text, so its placeholder is not shown. Trajectory at 120x40: a wide event row shows its summary, not the event type. The script now reads the name column down its rows, matches wrapped text and compares columns. |
+| D-29 | `scripts/verify-terminal.py`, approval titles — resolved 2026-11-03 | The script expected `Approve ask_user?` and `Approve workspace-write?`; the terminal titles dialogs with display names (`AskUser`, `WorkspaceWrite`), and a harness run asks `ask_user` questions without an approval. The script now accepts either title, and the question with or without an approval. |
+| D-28 | Client terminal record contract — resolved 2026-11-03 | The script asserted that a terminal run's `nativeSessionId` is a history file. Client terminal runs record Pi's session id, as host runs do (page 11, Identity); the script resolves either to the history file, and `/session` takes either. |
 | D-27 | Subagent compaction, pages 02 and 04 | A subagent compacted at the context threshold (run `5cd1d8aa`, 2026-11-01) produced a summary whose `## Goal` read "No specific research question or task was provided" while its split-turn section kept the brief. The model that continued still had the task through the turn context, but the summary's headline contradicts it. Not resolved here; the cause (the brief sits in the split part of the turn) is not confirmed. |
 | D-26 | App browser tool catalog, pages 13 and 14 (PAR-015) — rechecked with ADR-0082 | Brave mode now supplies all shared Harness browser tools except the App-only upload through `browserToolsForSession` (`agent-app/sidecar/src/app.ts:172-177`, `appTools.ts:91-126`); WebKit still filters unsupported snapshot/ref operations. The Rust `app.capabilities` response remains backend-agnostic (`src-tauri/src/app_tools.rs:111-123`), while its `TOOL_IDS` and shared contract contain the new Browser tools (`shared/contracts.ts:557-562`, `src-tauri/src/agents.rs:90-103`). Thus a connected Brave backend implements the advertised refs, but the capability catalog can still mark WebKit-unsupported tools available. Partly resolved; backend-aware capability reporting remains open. |
 | D-25 | Native WebKit interaction, page 13 — rechecked with ADR-0082 | The Brave adapter now uses the shared ref-based definitions, but the App's Rust backend still routes `browser_click`, `browser_type` and the App-only `browser_upload` by CSS `selector` (`agent-app/src-tauri/src/browser_workspace.rs:1493`, `agent-app/shared/appTools.ts:20`). The shared provider refuses those WebKit operations and never maps refs to selectors. Open: extend the contract to selectors or remove the native selector paths. |

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -4,9 +4,9 @@ title: Own the terminal frontend and keep Pi as the session runtime
 status: accepted
 created: 2026-10-17
 updated: 2026-10-17
-related: []
+related: [ADR-0083]
 supersedes: null
-superseded_by: null
+superseded_by: ADR-0083 (runtime only)
 ---
 
 # ADR-0001 — Own the terminal frontend and keep Pi as the session runtime
@@ -85,3 +85,10 @@ had been reached. The isolated credentials were deleted, the source sign-in rema
 and terminal restoration passed; see the [live evidence](../evidence/terminal-2026-10-17-followup/live-codex/README.md).
 Successful live streaming/tool acceptance and App renderer acceptance remain open. This evidence
 does not establish a released package or exhaustive platform/visual parity.
+
+## Partly superseded — 2026-11-03
+
+[ADR-0083](ADR-0083-one-live-session-runtime.md) moved the terminal's persistent Pi runtime into
+the harness as a live session that every front end reaches through server methods; the client
+terminal is the default. The owned OpenTUI presentation decided here stays. The in-process runtime
+this record describes remains available with `XINGULAR_TERMINAL_RUNTIME=inprocess`.

package/docs/decisions/ADR-0083-one-live-session-runtime.md

@@ -0,0 +1,256 @@
+---
+id: ADR-0083
+title: One live session runtime in the harness
+status: accepted
+created: 2026-11-03
+updated: 2026-11-03
+related: [ADR-0001, ADR-0035, ADR-0056, INV-RUN-1, INV-SRV-1, INV-SRV-4, INV-TUI-2, INV-RC-5, INV-PAR-1, INV-PAR-2, PAR-008, PAR-018]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0083 — One live session runtime in the harness
+
+## Context
+
+The harness runs a conversation in two different runtimes:
+
+- **Structured sessions** (`xagent serve`, the App sidecar): `Sessions.run` opens a Pi session for
+  one run and disposes it when the run settles (`sessions/runner.ts`, `piSessionFactory` and the
+  `finally` of `runTurn`).
+- **The terminal**: a Bun child keeps one Pi `AgentSessionRuntime` alive across turns
+  (`terminal/tui/runtime.ts`). Its gate, telemetry and run accounting go through
+  `terminal/piExtension.ts`, the session socket and `TerminalController`.
+
+ADR-0001 chose the second runtime because calling `sessions.run` per prompt "recreates and disposes
+the runtime per turn, losing persistent plugin UI/queue state". That reason still holds for the
+structured path as it is built today.
+
+Two runtimes mean many lifecycle features are built twice and drift: plan-outcome repair (D-22),
+the queued-message rules, work slices (a headless run continues as a new run, a terminal reply in
+place), stall guards (`terminal/stallWatch.ts`, now `sessions/stallWatch.ts`), `get_capabilities`, and about fifteen private
+`terminal.*` routes that mirror public methods. A terminal session cannot be reached from the App
+(PAR-018) and the two keep separate session catalogs (PAR-008). A run ends when its window closes.
+
+Codex keeps the agent loop in one server process (`codex app-server`) and makes every front end a
+client of it: threads, turns and items over JSON-RPC, approvals as server-to-client requests.
+Claude Code keeps the loop inside the CLI process and lets other front ends spawn that process.
+The harness's server protocol (page 10) and run events (page 02) already have Codex's shape
+(session ≈ thread, run ≈ turn, run events ≈ items). The missing part is a live session the server
+owns across runs.
+
+## Decision
+
+The harness owns one session runtime. A *live session* is a Pi session the harness keeps open
+across runs of the same native conversation. Every front end, including the terminal, reaches it
+through server methods. The terminal keeps its owned OpenTUI presentation (the screen half of
+ADR-0001); only its private runtime goes away.
+
+Work proceeds in phases; each lands with its spec pages and checks.
+
+1. **Live sessions.** A `LiveSessions` service in `src/sessions/` keeps a Pi session open between
+   runs. `Sessions.run` reuses it when the new run's pins match the open session, and opens a fresh
+   one otherwise. Unattended triggers (`probe`, `improver`, `reflection`) and refinement keep the
+   per-run open and dispose. A caller opts in with `sessions.run { live: true }`; the first such run
+   opens the live session. Additive methods: `sessions.live`, `sessions.close`, `sessions.followUp`,
+   `sessions.followUp.clear`. Steering stays `runs.steer`, and replay stays `runs.since`, which
+   already exist. The App adopts this first.
+2. **The terminal as a client.** The OpenTUI child talks to the harness over the protocol on a
+   local socket and renders from run events. The private `terminal.*` mirrors give way to the
+   public methods, scoped by the caller identity the control key proves. The old path stays behind
+   a flag until production PTY acceptance at 40x20, 80x24 and 100x30, then is removed.
+3. **Optional daemon.** Decided after phase 2: a long-lived `xagent serve --daemon` on a Unix
+   socket under the state directory, with one writer per data root, so a run outlives its window,
+   and remote control belongs to a live session rather than a terminal (PAR-018).
+
+### Phase 1 design: what a run binds
+
+A run pins its account, variant version and capability set (INV-RUN-1), so a live session may only
+serve a run whose pins equal the session's. The reuse key is: account, variant version, frozen
+capability fingerprint, working folder and workspace root, plan flag, allowed tool names, the
+stable system prompt, and the loaded plugin set. Model and effort changes go through Pi's own
+setters. Any other difference closes the live session at the turn boundary and opens a new one on
+the same native history, as `/variant` already does (ADR-0065).
+
+Today these are created per run and baked into the Pi session when it opens
+(`sessions/sessions.ts`, the `params` and `factory` call; `sessions/runner.ts`,
+`piSessionFactory`). Each must read a *current run binding* that `LiveSessions` swaps at the start
+of every run:
+
+| Bound per run today | Where | Becomes |
+|---|---|---|
+| The gate (`checkDetailed`, workspace scope requests, plan refusals) | `gatedExtension` in `piSessionFactory` | A session-level `tool_call` handler that asks the current binding's gate |
+| Custom tool specs bound to the run (`spec.execute`) | `customTools` in `piSessionFactory` | Session-level tool definitions that call the current binding's spec of the same name |
+| The extension host (`ask`, `notice`) | `bindExtensions` in `piSessionFactory` | A host that forwards to the current run, and refuses between runs |
+| `runLineageJoin(root, runId)`, `subagents.extension(runId)` | `params.inline` | Extensions that read the current run id |
+| Compaction checkpoint (`initialTodo`, plan instructions) | `params.inline` | Reads the current run's todo and plan flag |
+| Work-slice guard and goal loop (their state and controller) | `params.inline` | Installed once, enabled and fed by the current binding |
+| `onRefusal`, `activatedPlugins`, the heartbeat and `settle` | `params`, `runTurn` | Already per run in `runTurn`; unchanged |
+
+`runTurn` stops disposing the session; `LiveSessions` disposes it on `sessions.close`, on a pin
+change, after an idle timeout, and at harness shutdown. A live session runs one run at a time; a
+second `sessions.run` while one is active is refused, or delivered as a steer or follow-up when the
+caller asks for that.
+
+## Alternatives and rejection reasons
+
+- **Keep two runtimes.** Every lifecycle feature keeps its second copy, and the drift and parity
+  lists keep growing.
+- **Claude Code's model** (the terminal process is the engine, hosts spawn it). Simple for one front
+  end, but the App, the phone surface and evaluation would each drive a terminal process, and the
+  structured path would remain a second runtime.
+- **Make the terminal call today's `sessions.run`.** Rejected by ADR-0001 for the same reason it
+  gives: a per-run runtime loses queues and persistent plugin UI. Phase 1 removes that reason first.
+- **A rewrite in one release.** Too large to verify; each phase must pass the full checks and, for
+  phase 2, production PTY acceptance.
+
+## Consequences and risks
+
+- This is a 2.0-level change: it adds methods and a socket transport (INV-SRV-1, INV-SRV-4),
+  changes who owns execution in the terminal (INV-TUI-2), and moves remote control's lifetime
+  (INV-RC-5). Pages 02, 10, 11, 14 and 15 change as each phase lands.
+- Every inline extension must be safe to keep across runs. A missed per-run closure would leak one
+  run's state into the next; phase 1 tests run two turns on one live session and check each run's
+  events, refusals and records belong to that run only.
+- Streaming over IPC adds latency to the terminal; phase 2 measures first-delta latency before and
+  after.
+- Live checks may use real model requests only with the owner's permission (granted for this work
+  with a Codex account on Luna 6, or the OpenCode account on DeepSeek V4.1 Flash), never against
+  `~/.codex`, `~/.claude` or `~/.pi`.
+
+## Evidence — phase 1, 2026-11-03
+
+Implemented in `src/sessions/live.ts`, `src/sessions/runner.ts` (`rebind`, `release`, run slots),
+`src/sessions/sessions.ts` (`live`, follow-ups) and `src/server/methods.ts`. `src/sessions/live.test.ts`
+covers reuse across runs, a pin change, the per-run default, busy refusal, queued, idle and parked
+follow-ups, close and shutdown, refusal for unattended runs, and a rebind of a real Pi session (an
+`input` handler and a bound tool replaced by the next run's) with no model request. Harness:
+1,803 tests passed, `npm run prove` passed. App sidecar typecheck and 89 tests passed against this
+tree.
+
+Live check with owner permission, account OpenCode, model `opencode-go/deepseek-v4.1-flash`, a
+throwaway data root and the installed sign-in:
+
+| Run | Live | Status | Native session | Session ready (ms) | Input tokens | Cache read |
+|---|---|---|---|---|---|---|
+| b1 | no | completed | `01a19f83-2ef3…` | 1002 (cold start) | 4796 | 0 |
+| b2 | no | completed | same | 73 | 73 | 4736 |
+| l1 | yes | completed | `01a19f83-408c…` | 75 | 4796 | 0 |
+| l2 | yes | completed | same, reused | 52 | 73 | 4736 |
+| l3 | yes, steered | completed | same, reused | 59 | 326 | 9472 |
+
+The live session served three runs (`runs: 3`). Reuse keeps the provider cache exactly as the
+per-run path does. A steer sent after the first delta was recorded as `message.steered` and the
+model answered it in the same run. A reused session is ready slightly sooner (52–59 ms against 73 ms
+warm); the larger gains are steering, follow-ups and plugin state that survive between runs.
+
+## Evidence — phases 2 and 3, 2026-11-03
+
+**Phase 2, the terminal as a client.** `XINGULAR_TERMINAL_RUNTIME=harness` selects
+`terminal/tui/harnessRuntime.ts`; the parent side is `terminal/liveTerminal.ts`. The in-process
+runtime stays the default. Decision recorded with the owner: plugin presentation that needs an
+in-process terminal is unavailable in client mode (INV-TUI-8), as it is in a host.
+
+- Tests with real Pi and a scripted model: `terminal/liveTerminal.test.ts` (two turns on one live
+  session, the native event journal, a plan-mode `ask_user` answered through the decision routes,
+  busy refusal) and `terminal/tui/harnessRuntime.socket.test.ts` over the real session socket (the
+  mirrored transcript, one native session, the in-process tool set, `/todo` and `/trajectory`
+  lookup, the system prompt, a plan question, `/new` on a new file).
+- Live, OpenCode account, `opencode-go/deepseek-v4.1-flash`, real OpenTUI frontend in a PTY at
+  100x30, 80x24 and 40x20: five turns and a queued follow-up each, all completed on one native
+  session. Mean time from Enter to the reply on screen for turns 2–5: client 1.60 s, 1.79 s and
+  1.37 s against in-process 1.59 s at 100x30, within the model's own variation. The fixed overhead
+  from Enter to the harness run starting is about 30 ms against about 5 ms in process. Startup to
+  ready: 2.2–2.9 s client, 2.6–2.8 s in process.
+- Found and fixed on the way: the client first lacked the world tools and had `grep`, `find` and
+  `ls`, which the in-process terminal does not activate; a new conversation re-adopted the old file
+  from stale state; a mode with no saved model sent none; child runs inherited `live: true` (caught
+  by the App's sidecar test).
+- Not passing yet: the production PTY suite stops early in client mode on a record-contract
+  difference (Known drift D-28).
+
+**Phase 3, the long-lived harness.** `server/socket.ts`, `terminal/daemon.ts`, `Terminals.detach`
+and `prepare { attach }`, CLI `xagent daemon start|stop|status`, `xagent --daemon`, `xagent attach`.
+
+- Tests: `terminal/daemon.test.ts` (one lock per state folder and a stale lock replaced, the
+  protocol on an owner-only socket to several connections, a full daemon run that prepares over its
+  socket, reports and stops); `harnessRuntime.socket.test.ts` (a reply keeps running when its
+  window closes and a new window reattaches and sees it finish; a detached session ends when its
+  reply settles).
+- Live, same account and model: `xagent daemon start`, a `--daemon` window asked for 600 numbers,
+  the window was hung up (SIGHUP) mid-reply; it printed the `xagent attach <id>` line, `daemon
+  status` reported one live session and one reply without a window, `xagent attach` showed the
+  reply finish 3.6 s later, and the run recorded `completed`. Afterwards no live or detached
+  session remained and `daemon stop` removed the lock and socket.
+- Found and fixed: the daemon took its lock before the state folder existed.
+
+Checks at the end: harness typecheck clean, 1,820 tests pass, `npm run prove` passes; App sidecar
+typecheck and 89 tests pass against this tree, `check:layers` flags none of the new files. Open
+and unrelated to this change: the App's `soloCommands.test.ts` expects Solo to handle `/goal`
+(PAR-017), and the App's root typecheck reports button-prop errors in its UI.
+
+## The client terminal is the default — 2026-11-03
+
+The owner asked to finish the client terminal and make it the default once it works. `xagent` now
+runs the client terminal unless `XINGULAR_TERMINAL_RUNTIME=inprocess` is set. The in-process
+runtime stays for plugins that need their own terminal components.
+
+What finishing it took, each with a test:
+
+- Parity of what a person sees: plugin notices, status lines, widgets and titles (`harness_notice`);
+  a failed reply's message; a settle marker when Pi's loop never started; plugin `select`,
+  `confirm`, `input` and `editor` shown with the window's own dialogs (`question.requested.dialog`);
+  plugin commands listed before the first turn and sent by their owner-qualified route; a plugin
+  that cannot load stops the window's start; `/goal` run as a harness goal with its state shown.
+- Parity of what a turn does: plan runs carry only the plan's tools (`planTools: 'active'`); `!`
+  commands run as the turn's initial Bash on a resumed history; `/session` takes a file or a session
+  id; `/new` and steering ask the harness whether a reply really runs before refusing.
+- Lifecycle: `/stop` and Esc return at once and Pi's abort finishes behind them; the window closes
+  cleanly when its harness is gone; an uncaught error in the host closes the window before exiting
+  1; a frontend left after its terminal hangs up is ended after three seconds (this also leaked
+  in-process windows); the long-lived harness survives one plugin's uncaught error.
+- A harness fix every host gets: a provider request that timed out and was retried and answered no
+  longer marks the run failed.
+
+Evidence:
+
+- Harness: typecheck clean, 1,829 tests pass, `npm run prove` passes; App sidecar typecheck and 89
+  tests pass; `check:layers` flags none of the new files.
+- Production PTY suite (`scripts/verify-terminal.py`, its local provider, no real requests) in the
+  default client terminal: the full run passes at 40x20, 80x24, 100x30 and 120x40, and so do the
+  welcome, click-focus, composer, file-completion, history, resume, todo, questions, jump-latest,
+  help, command-completion, attachments, dialog-paste, thinking, queue and compaction suites. The
+  script now accepts what differs by design: either approval title, a question asked with or without
+  an approval, either `nativeSessionId` contract, a plugin overlay the client cannot draw, a size
+  shown in bytes, a varying usage-event count, and a long command name wrapped after its owner
+  prefix. Browser, palette, accounts at 120x40 and trajectory at 120x40 fail the same way on the
+  previous commit (Known drift D-30); markdown fails only with uncommitted work outside this change
+  (D-31). The full run's `/stop` step, which allows 0.8 seconds, failed twice while the machine's
+  load average was above 20 and passed every time below it.
+- Live, OpenCode account, `opencode-go/deepseek-v4.1-flash`, real frontend at 100x30: five turns
+  and a queued follow-up on one native session; `/stop` and Esc recorded the reply interrupted in
+  33–77 ms against 35–62 ms in process; turn latency within the provider's variation. One turn hit
+  a ten-minute provider timeout and its retry answered; the run now records `completed`. With
+  `--daemon`, a window hung up mid-reply left the reply running; `xagent attach` showed it complete.
+
+## Closing the migration — 2026-11-04
+
+- **Stall guard for every harness run.** The terminal's stall rule (15 minutes without an event, 30
+  with a tool running; ADR-0054, ADR-0078) lived only in the in-process controller, so a client
+  terminal reply, a live session and an App turn had only Pi's own request timeout (about ten
+  minutes, retried). `runTurn` now applies it to every run (`sessions/stallWatch.ts`, moved from
+  `terminal/`): the run settles `interrupted` with `stalled`, the native turn is aborted, and a live
+  session is closed (queued follow-ups parked), or closed under the turn if the abort has not
+  unwound it after 30 seconds. A pending approval or question, and a wait for subagents (each child
+  has its own guard), restart the clock. Pi's request timeout is unchanged: a shorter one multiplies
+  with the retry policy and could cut a slow reasoning model's first token, so the progress rule is
+  the cap.
+- **Heartbeat for every run.** `runTurn` emitted `heartbeat` only for work-slice runs, against
+  INV-RUN-14; a live reply with a quiet tool for 30 minutes could be settled `owner_gone`. It is now
+  unconditional (slice counters zero without a slice).
+- **Verifier.** The four D-30 suites asserted stale layouts, not product faults, and are fixed; the
+  `/stop` step polls the run record up to 8 seconds instead of reading for 0.8; the in-process
+  fallback's full run passes at 80x24 (the deny/approval-cancel stop did not reproduce). D-31 (the
+  markdown suite) is the other change's fixture overflowing the screen. Tests: `sessions/stall.test.ts`
+  (8) cover the guard and heartbeat.
+- Not done: PAR-018 (remote control bound to a live session). Notes in HANDOFF.md.