@xingular/harness 1.3.1-unstable.1 → 1.3.1-unstable.10

package/CHANGELOG.md

@@ -2,6 +2,261 @@
 
 ## Unreleased
 
+- **Codex's prompts and `/goal`; the completion check moves behind `/goal` (ADR-0072).**
+  - **Ordinary replies.** No model-judged check runs on them. The todo gate stays and says the list
+    is progress, not the limit of the work; `TODO_GUIDANCE` now says the request is the scope.
+  - **Prompt.** A person's own session reads Codex's autonomy and persistence, when-to-ask,
+    steering and compaction, and writing-style rules as separate sections, and a longer reporting
+    section: unfinished work says so on the first line, with the reason and the next step.
+    `ask_user` is never used to ask permission, and no answer means continue.
+  - **Failures from outside the session.** A test or error that does not come from the session's
+    work is reported with its command and output, not fixed, unless the person asks. It stays off
+    the todo list, and it is a reason to stop that the autonomy rules name.
+  - **`/goal <objective>`.** A long run the person starts. Codex's `get_goal` and `update_goal`,
+    continuation, round-cap and edit prompts, `blocked` after the same blocker on three turns, and
+    brakes for idle, failing and erroring rounds. `/goal edit|pause|resume|clear`, a footer label,
+    Esc pauses. Caps: 30 rounds or 8 hours (`--rounds`, `--hours`).
+  - **A completion claim is checked** once by the same model at low effort with a fresh context.
+    `sessions.run` takes `goal`; `run.json` records `goalMode`.
+  - **Fixed.** The check sends a session id, so opencode-go no longer answers 400 `MissingSessionID`.
+  - Adapted from OpenAI Codex (Apache-2.0); see `NOTICE.md`.
+- **A completion check replaces `finish` (ADR-0071; the every-reply check is superseded by ADR-0072).**
+  - **The check.** When a reply that did work ends with its todo list closed or absent, the run's
+    own model, at low effort and with a fresh context, judges the person's request against what the
+    reply did: `done`, `continue` (the reply is sent back with the reason and next step), or
+    `needs_person`. The request is the goal; there is no `/goal` command.
+  - **Shared cap.** It shares the stop gate's cap of three nudges per reply and its no-progress rule.
+  - **Usage and failure.** Its request counts in the run's usage, and any failure leaves the reply
+    as it was.
+  - **`finish` is removed.** A live GPT 6 Luna run used `needs_decision` after 23 seconds to ask
+    something the handoff already answered. Only the check can now decide that the person is needed.
+  - **Prompt.** The `role` paragraph names which decisions are the agent's own, says a document the
+    request points to is the request, and says a question the request or files already answer is not
+    a question for the person. Its budget rises from 1,500 to 2,200 characters, so it fits uncut with
+    the subagent paragraph.
+  - **Kill switches.** `XINGULAR_STOP_GATE=off` and `XINGULAR_COMPLETION_CHECK=off` at launch switch a
+    layer off, for experiments.
+- **The model is told it has `edit` and `write`.** Pi's `createEditTool` and `createWriteTool` drop
+  the definition's prompt line and guidelines, and Pi lists only tools with a prompt line, so every
+  terminal and headless run's system prompt named only `read` and `bash`. Models edited files
+  through shell scripts instead: one 2-hour terminal run made 156 script edits (14 failed) and no
+  `edit` call. `createWorkspaceFileTools` now restores the prompt line and guidelines, as Pi's own
+  `createBashTool` does, for both the terminal and the runner. The stable prefix changes once.
+- **A plan no longer leaks its tools into normal mode.** A terminal plan request narrows the active
+  tools, and Pi records the restored normal set only with the next request. A rebuild before then
+  (a new runtime, resume, switch, fork or tree navigation) replayed the plan set, so normal work ran
+  without `edit`, `write`, browser and connected-app tools. One recorded session implemented a whole
+  plan that way. The terminal now marks each plan request in the session and restores the normal
+  set after any rebuild.
+- **Terminal replies continue across work slices (ADR-0070).** A terminal reply that reaches its
+  320-call or 60-minute budget after doing work now continues in place as the next slice, with a
+  checkpoint and a notice, up to 8 slices, instead of waiting for "continue" and re-sending the
+  whole context uncached. Fruitless, blocked, failed, aborted and plan slices still stop.
+  `XINGULAR_WORK_SLICE` also accepts key=value pairs such as `maxToolCalls=15,maxSlices=3`.
+- **One copy of each credential: no more `invalid_grant` from terminals.** A terminal's Pi kept the
+  account's tokens in `auth.json` under its own lock while the host, its subagents and usage probes
+  refreshed the same token in the Keychain under another, and `terminalEnd` copied the file back
+  over whatever the Keychain held. OpenAI rotates refresh tokens, so whichever side refreshed second
+  failed with `invalid_grant` and the account needed a new sign-in. A terminal now reads and refreshes
+  through the host store (`accounts.credentials.*`, INV-ACC-5), holding its lock for the refresh. An
+  `auth.json` left by an older terminal is folded in, newest token first.
+- **A stalled terminal reply is recorded as `stalled`.** Pi's abort reports back through
+  `terminal.interrupt` like a person's Esc, which closed the run as `user_abort` before the reply
+  settled as `stalled`; one silent 15-minute hang was recorded as the person's abort. The interrupt
+  now carries the stall. An interrupt also ends a settling reply's wait for its subagents.
+
+- **A reply can no longer quietly stop with work open (ADR-0069).**
+  - **Stop gate.** In attended top-level runs, terminal included, a reply that ends while its todo
+    list has open items is sent back to the model, naming the items, up to three times per reply,
+    and never after a nudge that produced no work.
+  - **`finish`.** Added here as the one explicit way to stop with work open; removed again by ADR-0071
+    above.
+  - **Honest stop codes.** Such a reply settles `interrupted` with the new stop codes `needs_person`
+    or `unfinished`, never `completed`, with a checkpoint the harness writes from the todo list,
+    files and checks.
+  - **`checkpoint_write` is removed.** A run used it as a sign-off and stopped with work open. At a
+    work-slice budget the harness now writes the checkpoint itself.
+  - **One budget per reply.** The work-slice budget now covers the whole reply: Pi's own
+    continuations (nudges, delivered subagent results, plan repair) no longer reset it.
+  - **Prompt wording.** The texts that read as permission to stop were rewritten: the todo guidance's
+    "final update before your final reply", and `## What would make this complete` "when the run
+    could be more complete".
+  - **Subagents.** `spawn_subagent` now returns the child's tools, and the read-only profiles say up
+    front when a brief needs a tool they lack.
+  - **Hosts.** Accept the two new stop codes and offer Continue for them.
+  - **Restart required.** A live terminal session keeps the code it started with, so restart it to
+    get the gate.
+- Do the job the request implies, and report it apart from the request. A standard session's role
+  paragraph now sets the scope of the work — the obvious adjacent step, what the work itself exposes,
+  the check it needs, inside the working folder and away from what a person must decide (a deploy, a
+  secret, remote data, money), without asking first inside those bounds — and the reporting guidance
+  requires two headings when they apply: `## Beyond what you asked` and
+  `## What would make this complete` (ADR-0068). The reporting budget rises from 2,000 to 2,400
+  characters so both fit uncut. All of it is stable-prefix text, so the cached prefix changes once
+  per session.
+- Say in the prompt when a reply may end. The standard session's role paragraph, the opening of the
+  reporting guidance and the todo guidance now say that an open todo item, a passing check or a
+  partial result is not a reason to end the turn, and name the reasons that are: the request is done,
+  the work-slice guard hands the reply back, a person's decision is needed, or the person interrupts.
+  ADR-0069 below now enforces it in the runner. A sweep of 822 runs in seven days found 207 that ended with work left
+  (137 within 30 tool calls, median 17, and 191 with no checkpoint), which is what the wording is
+  for. All three texts are in the stable prefix, so this changes the cached prefix once.
+- Reword the final-reply guidance so the outcome leads and structure follows what the answer needs. The
+  reporting guidance is part of every request's stable prefix, so this changes the cached prefix.
+- Keep the provider cache working after a compaction (ADR-0067). The compaction checkpoint now arms only
+  for a compaction during the running reply, is built once, and sits right after the summary instead
+  of being rebuilt at the end of every request. A request after a compaction is again the previous
+  request plus new items, so Codex WebSocket continuation and prefix caching apply. Before, every later
+  turn of a compacted session resent its whole context: one measured session fell from 94–99% to
+  18–24% cache hits after its first compaction.
+- Flag a low prompt-cache hit rate in the terminal's composer status bar. `R<percentage>%` now covers the
+  last 10 model responses instead of the whole session (`recentCacheUsage`, `CACHE_HIT_WINDOW`), and
+  gets a yellow `⚠` below 70 percent and a red one below 40 percent. Each drop to a worse level posts
+  one transcript notice. A window of one response, or one with no cache reads or writes, is not judged
+  (`cacheHitLevel`, `CACHE_HIT_WARNING_PERCENT`, `CACHE_HIT_CRITICAL_PERCENT`).
+
+- Refine a variant from the terminal and keep checkpoints of it (PROP-0052, ADR-0065, ADR-0066).
+  `/refine [what to look at]` replays the latest request typed in this chat from a snapshot of the
+  folder as that turn found it, in throwaway shared clones, after a confirmation that shows the run
+  count and models; it runs in the background, and `/refine review` shows every candidate's changes
+  and output and adopts any of them. Guidance reaches improvers and composers only, never the blind
+  selector. Task runs default to this chat's model; `--model` sets the improver's, and an adopted
+  version records the model it was tuned on. `/variant` switches this conversation to another
+  version at the next turn (resuming the same conversation), restores, compares, tags, and takes
+  single components back from an earlier version. New methods: `refine.fromRun`,
+  `refine.candidateDiff`, `refine.candidateOutput`, `variants.tag|untag|tags|resolve|revert`. Run
+  records gain `workspaceSnapshot`, version records `tunedFor`, and scopes `tags.json`.
+
+- Start a conversation this account cannot use on the account's newest selection. A resumed
+  conversation keeps its model while the account offers it and holds its provider's credentials;
+  otherwise the terminal starts it on the mode's choice, then normal's, then the newest selection in
+  any mode, with that selection's effort, writes the model change into the conversation, and says in
+  one notice which model it replaced. A fallback is never saved as the person's choice, and with no
+  usable saved model Pi's own fallback message stands (ADR-0064).
+
+- Make unfinished-work handoffs actionable: the stable reporting guidance now names the person’s
+  concrete decision or the next action and its owner for each material blocker, without imposing a
+  fixed heading (PROP-0051, ADR-0063).
+
+- Share the account sign-in between `npm run dev` and the installed `xagent`. A standalone launch
+  can now take its account identity from another state directory with `--account-state <dir>`
+  (`HarnessOptions.accountsDir` plus that state's `secrets.json`), and `npm run dev` passes the
+  installed one, so one provider sign-in serves both while development keeps its own data,
+  approvals and plugin trust (ADR-0062).
+
+- Require owner-prefixed plugin commands on terminal and structured sessions. Plugin-owned prompt
+  templates join extension commands under `/<owner-prefix>:<name>`, with no bare plugin aliases.
+  A package can select a root template with `harness.defaultPrompt`; owner and route collisions fail
+  closed. Standalone templates, `/skill:<name>` and core commands remain (ADR-0061).
+
+- Make an approval a control, never a typed permission. The compiled guidance now tells the model to
+  call the tool, the Harness pauses that exact call (`waiting_for_approval`), and Allow resumes it in
+  the same turn; a denial returns a tool result on the still-running turn and says so, instead of
+  inviting another prose request. Nothing outside the workspace changes before the click, and Full
+  Permission remains the standing bypass (INV-GATE-9, ADR-0060).
+
+- Record structured tool refusals and run stop codes, and expose them in trajectory search and the
+  terminal trajectory page. Compaction events include available token measurements; older run
+  records remain readable without these fields.
+
+- Keep a refused question answer in the terminal. A choice, note or typed answer that the Harness
+would reject now stays in the dock with an inline reason, instead of closing the form and losing the
+draft; the reason names the question and the field (selection, typed answer or note), and the answer
+is checked against the server rule before it is sent. The terminal was previously reopening an empty
+question after any rejection, so a second Continue skipped everything.
+
+- Scroll a `/btw` answer taller than its block. PageUp/PageDown now reach the side-question dock
+while it is open, and the mouse wheel over the block browses it too; before this the transcript
+consumed those keys, so the block's `PgUp/PgDn/wheel browse` hint did nothing. When the answer fits, the
+keys scroll the transcript as before.
+
+- Drop the context-use reading from the terminal's composer status line, so it no longer ends the
+token group with a figure such as `6.6%/?`. The line keeps the project and branch, account, model
+and effort, and input/cache hit rate/output tokens; the share of the window stays on the `/context`
+page. Both the OpenTUI status bar and the exported `tui/status` band lose the reading.
+
+- Render the `/btw` side answer as Markdown instead of plain text. Headings, emphasis, lists,
+  quotes, links, tables and fenced code use the theme's markdown colours, and a streaming answer
+  re-renders in place. Terminal control sequences in model output are still removed.
+
+- Add `/remote-control` (alias `/rc`): continue a terminal session from a phone or iPad, as Claude
+  Code's `/rc` does, without a cloud relay. The harness serves a small phone page on the computer's
+  Tailscale address, or its private Wi-Fi address, and the terminal shows a QR code for a one-device
+  pairing link. The person at the terminal allows each device; a paired phone then sends messages,
+  watches the reply stream, stops it, and answers approvals and questions through the same paths
+  the terminal uses. Every body is sealed with a key that reaches the phone only in the QR code's
+  fragment, keys live in memory, and remote control ends with the session. `xagent --remote-control`
+  turns it on at start; `/rc off` stops it. Terminal runs now also record streamed `message.delta`
+  events. New dependencies: `tweetnacl`, `uqr` (ADR-0056, page 15).
+
+- Recover a plan run whose reply loses its plan block. An attended top-level plan run now makes one
+  hidden format-repair turn in the same run, asking the model to re-send its own plan in one complete
+  block; a failed repair leaves the run completed and the terminal shows a warning instead of a plan
+  choice. The plan-research children, commands, probes, improvers, reflections and other unattended
+  runs are unchanged (ADR-0055).
+
+- A live terminal reply now reports a heartbeat every 30 seconds, and one that produces nothing but
+  heartbeats for 15 minutes is ended as `interrupted` with reason `stalled` instead of showing a run
+  that never settles. A running tool gets 30 minutes and an unanswered approval or question is never
+  cut short. Before this, a terminal reply reported no heartbeat at all, so the run sweep waited the
+  full 30-minute silence window and recorded `owner_gone` while the process was alive (ADR-0054).
+
+- Stop refusing repeated work. A reply is no longer refused, or ended, for calling the same tool
+  with the same arguments three times, for a Bash check that keeps failing, or for editing one path
+  more than four times: those calls are ordinary work, and the reply budget is the single bound. The
+  320-call/60-minute budget, its checkpoint handoff, slice continuation and the three-compaction
+  thrash rule are unchanged, and the `stuck` checkpoint reason stays readable in existing runs
+  (ADR-0053).
+
+- Make a skill named in a message required for that request. `$name` is a skill invocation at any
+  word start, not only as the first token: `Launch.requiredSkills` carries it and the compiler
+  renders a built-in dynamic `required-skills` section (order 52, 12,000 characters) from the pinned
+  variant's `SKILL.md`, naming an unavailable skill honestly and falling back to the shipped
+  `plugin-authoring` skill. It changes no tool or permission, and it belongs to the request, so an
+  identical one is delivered again; structured sessions deliver it through `sessionLaunch` and the
+  terminal appends the same text as a hidden `xingular-required-skills` message
+  (`requiredSkillsText`). The terminal no longer rewrites a leading `$name` to `/skill:name`, and its
+  `$` palette opens at the caret and inserts there, keeping the rest of the draft (ADR-0048).
+
+- Bound delegation per run and per profile. `spawn_subagent` and `wait_subagents` still exist, but a
+  run now starts at most four distinct child conversations: two `worker`, three `explorer`, one of
+  any other named profile and one with no profile. The parent's `subagents` option overrides them
+  (`maxChildren`, `maxByProfile`, `maxOther`, `maxUnprofiled`, clamped to 0–50), so a host and the
+  terminal receive the same defaults; `Subagents.spawn` refuses a child past a limit with an
+  `invalid_request` that tells the model to do the work itself, and starts no run. The count covers
+  the runs the parent was continued from, continuing a stopped child costs no slot, and a concurrent
+  spawn reserves its slot before it launches (ADR-0052).
+
+- Record where a request's characters went. `renderSized` returns the prompt and each section's
+  size, `Delivery.sizes` stores them on the recorded pack, and `Source.chars` attributes a variant's
+  tool guidance inside the tools section, so `context.attribution` (`terminal.context` in the
+  terminal) can return one row per contributor with its estimated tokens and share of the window,
+  reconciled to the provider's measured total, plus one row's text. `context.snapshot` also records
+  the compaction headroom the run was held to (`compaction: { enabled, reserveTokens }`) from Pi's
+  own settings.
+
+- Define an opt-in approved-window screenshot contract. `computer_screenshot` in
+  `src/computer/screenshot.ts` takes a host backend that captures exactly one currently approved
+  window, excludes the desktop, other windows and overlapping overlays, and refuses with
+  `COMPUTER_SCREENSHOT_UNAVAILABLE` instead of falling back to a display capture. It goes through
+  the ordinary tool gate and is not plan-mode safe; the standalone terminal has no backend, and the
+  existing macOS host capture has not adopted the contract (ADR-0050).
+
+- Watch approvals and questions through `terminal.pending.wait`: a control-key-protected revision
+  snapshot that returns as soon as the pending set changes and otherwise waits at most 20 seconds,
+  waking on additions, removals and disposal. `terminal.pending` stays available, the client
+  resynchronizes after errors, and no persisted state or public protocol changes (ADR-0051).
+
+- Swap the OpenTUI send keys back. `Return` sends, or queues a follow-up behind a running reply, and
+  `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers that reply. The `app.message.followUp` action is
+  `app.message.steer` again, so a `keybindings.json` entry under the newer name needs renaming.
+
+- Keep a stray mouse report out of input. When the terminal delivers a mouse report in two pieces
+  across the input parser's timeout, its `<button;column;row>` tail is dropped instead of being
+  typed into the composer or a single-line field, so a scroll can never become a run's prompt or a
+  filter. Text typed at human speed is never touched, pastes are never rewritten, and the Trajectory
+  page no longer prints a recorded mouse report.
+
 - Give top-level sessions a name and a current-state prompt. An unnamed session derives a
   provisional six-word name from its first substantive request; greetings and short replies stay
   unnamed, and the model can revise the name. Each top-level run also receives a request-scoped
@@ -141,7 +396,7 @@ The first published release of the 1.1 line, and npm `latest`. It follows the 1.
 
 - Keep the OpenTUI home screen when a notice arrives before any conversation, such as `Unknown command: /tihnk`. The notice shows beneath the product mark instead of replacing it, and the composer keeps its "Ask anything…" placeholder.
 
-- Swap the OpenTUI send keys: `Return` now queues a prompt behind a running reply (it still sends when idle), and `Cmd+Return` steers the reply mid-run. `Alt+Return` also steers, for terminals that do not report Cmd. The `app.message.followUp` action is renamed `app.message.steer`, so a `keybindings.json` entry under the old name needs renaming.
+- Swap the OpenTUI send keys back: `Return` sends, or steers a running reply, and `Cmd+Return`, `Ctrl+Return` or `Alt+Return` queues a follow-up. The `app.message.steer` action is renamed `app.message.followUp` again, so a `keybindings.json` entry under the older name needs renaming. Pending steering, follow-up and deferred plan/Bash inputs show above the working line with their delivery type, a queued plan or `!` command acts as a barrier that later inputs wait behind, and `Alt+Up` restores queued text to the draft.
 
 - Draw the OpenTUI `select`, `confirm`, `input` and `editor` dialogs, including `/effort` and the Thinking setting, as the same flat centered panel on the scrim that `/model` and the other pages use, instead of a rounded bordered box. The box clipped the heading's `Esc` hint and the option count; centered dialogs now cap their height at the rows the overlay shows.
 

package/NOTICE.md

@@ -58,3 +58,29 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## OpenAI Codex
+
+The standard session prompt (`src/prompt/standard.ts`: autonomy and persistence, when to ask the
+person, steering and compaction, writing style), the final-reply rules in `REPORTING_GUIDANCE`
+(`src/prompt/compile.ts`), the `/goal` prompts and tool descriptions (`src/sessions/goalPrompts.ts`,
+`src/sessions/goal.ts`), the goal brakes and status text, and the `/goal` command
+(`src/terminal/tui/goalCommand.ts`) adapt text and design from OpenAI Codex, mainly:
+
+- `codex-rs/models-manager/models.json` (`instructions_template` of `gpt-6.1-sol` and `gpt-6-luna`);
+- `codex-rs/ext/goal/templates/goals/{continuation,budget_limit,objective_updated}.md`;
+- `codex-rs/ext/goal/src/{spec,tool,accounting,runtime,api}.rs`;
+- `codex-rs/tui/src/{goal_display,slash_dispatch,goal_menu}.rs`;
+- `codex-rs/collaboration-mode-templates/templates/default.md` (the `ask_user` rule).
+
+Upstream: https://github.com/openai/codex (OpenAI Codex, Copyright 2025 OpenAI)
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use these files except
+in compliance with the License. You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in
+writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Changes from upstream: ported from
+Rust to TypeScript for Pi; text about Codex's own channels and tools (commentary channel,
+`apply_patch`, `functions.exec`, apps, plugins, visualizations) left out; the goal's token budget
+became rounds and hours; `update_plan` became `todo_write`; completing a goal is a claim that the
+harness checks; the model cannot create a goal.

package/README.md

@@ -37,7 +37,7 @@ index](docs/README.md) links the architecture and other project records.
 
 ### Session options for applications
 
-- Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
+- Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. `{ maxChildren, maxByProfile, maxOther, maxUnprofiled }` bounds breadth: by default a run starts at most four distinct child conversations, two `worker`, three `explorer`, one of any other named profile and one with no profile. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
 - `harness.subagents.spawn({ parentRunId, brief, agent?, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. `agent` names an agent profile (below). It returns `{ runId, nativeSessionId, agent?, unavailableTools? }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
 - **Agent profiles** (PROP-0029) are what a subagent starts from: the built-in `worker` (reads, edits, writes, runs commands) and `explorer` (reads only), a person's own `<data root>/agents/<name>.md`, a repository's `<project>/.xingular/agents/<name>.md`, and the variant's c5 subagents, later ones winning. A profile is Markdown with frontmatter (`description`, `color`, `tools`, `plugins`, `variant`, `model`, `effort`) and its body is the role. It only narrows the parent's tools and plugins. `listProfiles`, `resolveProfile`, `createProfile` and `removeProfile` (RPC `agents.list|get|create|remove`) read and write them, and the child's `RunRecord.profile` names the one it used.
 - The model's `spawn_subagent` returns immediately by default; `wait: true` returns an inline result. `wait_subagents` joins selected children. The SDK and standalone terminal share this execution service. Terminal calls use its private control channel, including when connected apps are disabled.
@@ -294,11 +294,13 @@ npm run dev
 
 `npm run dev` rebuilds the CLI and opens the Harness terminal in the current working directory.
 It uses separate development directories by default: `~/.xingular-harness-dev/data` and
-`~/.xingular-harness-dev/state`. This keeps development harness data and device settings—including
-accounts, Pi settings, approvals, and connections—separate from the installed command. Press
-`/quit`, Ctrl+C or Ctrl+D to close it. Override either directory with `--data <dir>` or
-`--state <dir>`; for example: `npm run dev -- --data <dir> --state <dir>`. An omitted option keeps
-its development specific default.
+`~/.xingular-harness-dev/state`, so development harness data, approvals, plugin trust and
+connections stay separate from the installed command. It signs in as the installed command's
+accounts, though: one provider sign-in serves both launches. Press `/quit`, Ctrl+C or Ctrl+D to
+close it. Override either directory with `--data <dir>` or `--state <dir>`; choose the accounts a
+launch signs in as with `--account-state <dir>`, for example
+`npm run dev -- --account-state ~/.xingular-harness-dev/state` for a fully separate identity. An
+omitted option keeps its development specific default.
 
 The OpenTUI/Solid frontend is the only terminal. Install Bun 1.3.14 or newer and run
 `npm run build:tui` (or `npm run build`); without Bun the build fails rather than producing a
@@ -404,10 +406,13 @@ still be removed; that session then asks for another account the next time it st
 The installed standalone command defaults to `~/.xingular-harness/data` and
 `~/.xingular-harness/state`; `npm run dev` instead defaults to the separate
 `~/.xingular-harness-dev/data` and `~/.xingular-harness-dev/state`. Override either with
-`--data <dir>` and `--state <dir>`. Session history is stored per working directory and can be
-reopened with the terminal's `/resume` command. The explicit `terminal` command is an alias for
-the default launch. Use `--help` to see the commands; `serve` remains the host-facing RPC service
-for integrations such as Xingular Agent/App.
+`--data <dir>` and `--state <dir>`. A launch signs in as the accounts kept in the state directory
+it uses; `--account-state <dir>` takes them from another state directory instead (its `accounts`
+folder and its `secrets.json`), which is how `npm run dev` reaches the installed command's sign-in.
+Session history is stored per working directory and can be reopened with the terminal's `/resume`
+command. The explicit `terminal` command is an alias for the default launch. Use `--help` to see
+the commands; `serve` remains the host-facing RPC service for integrations such as Xingular
+Agent/App.
 
 ## Storage