@xingular/harness 0.1.7 → 2.0.0

package/docs/decisions/ADR-0004-fullscreen-terminal-layout.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0004
+title: Fullscreen terminal layout with a fixed dock
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0004 — Fullscreen terminal layout with a fixed dock
+
+## Context and decision
+
+The owned terminal drew its transcript and composer as one flowing list on the main screen. With a
+short transcript the composer sat under the last line and moved down as the transcript grew. Harness
+also kept its own scroll offset, mouse regions and paging, which duplicated the viewport Pi already
+provides in fullscreen.
+
+Harness now uses Pi's fullscreen renderer by default. The welcome and transcript form a scroll view
+that fills the terminal; the dock (working line, queue and notices, widgets, editor and status band,
+footer) sits fixed below it. Pi's `tuiMode`, `fullscreenScrollbar`, `fullscreenWheelScrollLines`,
+`fullscreenCopyOnSelect` and `fullscreenExitOutput` settings are read from the account and honoured.
+`tuiMode: "regular"` keeps the flowing layout on the main screen. When fullscreen ends with
+`fullscreenExitOutput: "transcript"`, the rendered conversation is copied into the normal scrollback.
+
+## Consequences
+
+- While fullscreen is running, the transcript is not in the terminal's scrollback. Mouse capture is
+  on, so terminal drag-selection gives way to the application's selection, which copies on release.
+  These are Pi's defaults and remain changeable in settings.
+- Harness no longer owns scroll state, wheel handling or paging. Those come from Pi's viewport and its
+  `tui.altScreen.*` bindings, and the keyboard list shows the scroll keys only in fullscreen.
+- Regular mode has no Harness-managed scroll position; scrolling there belongs to the terminal.
+- When the screen is short, a long notice shows its first rows and scrolls for the rest. The prompt
+  and status are never clipped; the head of a notice stays readable, so the newest line of a long
+  list may need a scroll.
+- Only `transcript` exit output is implemented. Other values write nothing on exit.
+
+## Alternatives considered
+
+Padding the main-screen output to the terminal height also keeps the composer on the last rows for a
+short transcript. It keeps native scrollback, but Harness would still own its scrolling and mouse
+handling, and the composer would scroll away with the terminal's scrollback once the transcript
+overflowed. That was rejected because it keeps the duplicated code this change removes.
+
+## Evidence
+
+The layout is covered by `src/terminal/tui/screen.test.ts`: the dock stays on the last rows as the
+transcript grows and scrolls, regular mode flows in order, and the exit copy is written with its styles
+reset. The PTY verification of the built CLI is recorded in [the terminal reference](../terminal-tui.md).

package/docs/decisions/ADR-0005-app-provided-oauth-clients.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0005
+title: Application-provided OAuth clients for connected apps
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0005 — Application-provided OAuth clients for connected apps
+
+## Context and decision
+
+Every remote connected app so far authenticated one of two ways: the server registers this app
+dynamically (RFC 7591), or the person registers a client with the provider and pastes its ID and
+secret into Connections. Google's Workspace MCP servers support neither in practice: they have no
+dynamic registration, and requiring every person to create a Google Cloud project before connecting
+Gmail is not a product.
+
+A connection's `oauthClient` now has a third value, `app`: **the application supplies the client**.
+The host does so through one extension point on the harness:
+
+```ts
+export interface AppOAuthClients {
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+```
+
+`HarnessOptions.oauthClients` carries it. Only a connection whose `catalogId` appears in `ids()` can
+use it — a hand-typed connection, a Hub connector recipe, and a plugin template cannot, because none
+of them can name a client the application actually holds. `connections.appClients` reports the ids so
+an application can offer only the connectors it can actually sign in for.
+
+The client is resolved inside `Connections.oauthLoad` and placed in the OAuth state as
+`staticClient`, exactly where a user-registered client goes. `oauthSave` already strips
+`staticClient`, so the client is never written to `connections.json` or the secret store; it is
+re-resolved on each load. Refresh tokens continue to be stored per connection.
+
+## Consequences
+
+- The harness learns no product concept: it knows a catalog entry id, a client, and a sign-in. Which
+  entries an application can serve is entirely the host's answer.
+- A build without a client is a first-class state, not an error: `ids()` is empty, `signIn` refuses
+  with "This connector has no app sign-in in this build", and the application hides those catalog
+  entries instead of offering a dead end.
+- A client secret in a distributed desktop build is extractable, so it is treated as public. The real
+  controls stay Google's consent screen, the requested scopes, and the tool approval gate.
+- One client can serve several catalog entries (five Google servers, one client). Each entry is still
+  its own connection with its own tokens, so signing in to one does not authorize another.
+- The per-user path is untouched: `oauthClient: 'user'` still stores a person's own client in
+  Keychain, and it remains the only route for providers or accounts an application cannot pre-register
+  for.
+- Google's Developer Preview terms, app verification and CASA assessment for restricted scopes are
+  outside this decision; they decide who can use the shipped client, not how it is delivered.

package/docs/terminal-tui.md

@@ -1,8 +1,23 @@
 # Harness terminal frontend
 
-Status: implemented in the working tree; publication is separate. Last updated: 2026-10-17.
+Status: implemented in the working tree; publication is separate. Last updated: 2026-10-18.
 Decision: [ADR-0001](decisions/ADR-0001-owned-terminal.md).
 
+## Native subagents (2026-10-18)
+
+Interactive terminal turns use the same `harness.subagents` service as SDK callers. The bridge
+registers the current run's effective tools, resolved model, thinking level and pinned account
+through its private control channel; a read-only terminal narrows child capabilities and broker
+access. `spawn_subagent` returns immediately, `wait_subagents` joins selected children, and
+`wait: true` on spawn returns an inline result. Native receipts deduplicate automatic delivery.
+The terminal joins outstanding children before its final reply, projects child approvals/questions
+with their original run IDs, and stops descendants when interrupted or disposed. Connected apps
+need not be enabled. `TerminalPrepareInput.subagents: null` disables the capability.
+
+Real scripted Pi execution over the actual terminal socket verifies result delivery and decision
+routing. It does not establish live-provider behavior or new visual UI parity. See
+[ADR-0003](decisions/ADR-0003-shared-asynchronous-subagents.md) for recovery and lifecycle details.
+
 ## Ownership and process boundary
 
 Harness owns its interactive terminal application in [`src/terminal/tui/`](../src/terminal/tui/).
@@ -24,7 +39,8 @@ Harness parent: account + compiled context + trusted resources + run writer
        | launch specification / existing session socket
 Harness terminal child: TerminalApplication + persistent Pi AgentSessionRuntime
        | typed native events / plugin UI callbacks
-Harness screen: welcome, transcript, status band, editor, dialogs and overlays
+Harness screen: transcript, with the product lockup above it until the first message, above a dock
+       (status, editor, footer), with dialogs and overlays
 ```
 
 [`runtime.ts`](../src/terminal/tui/runtime.ts) builds a public `AgentSessionRuntime` around
@@ -41,6 +57,47 @@ prompts. Reusing `sessions.run` for each prompt would recreate and dispose a ses
 turn and overlap the terminal controller's run lifecycle. That API remains the embedding and
 unattended execution path.
 
+## Screen layout
+
+[`screen.ts`](../src/terminal/tui/screen.ts) chooses the screen from Pi's `tuiMode` in the
+account's `settings.json`; the default is `fullscreen`. Fullscreen uses Pi 1.2.0's
+`TuiAltScreen` with a layout root: a `ScrollView` holds the transcript (with the product lockup
+above it) and fills the terminal, and a `VStack` dock sits below it. The dock holds the working
+line, queued messages, widgets, the editor with its status band, and the footer. Terminal notices
+(mode changes, errors, the keyboard list) are rows in the transcript, so they scroll with the
+conversation and clear with its session. The dock stays on the last rows as the transcript grows,
+and scrolling moves only the transcript. When the screen is short, the prompt and status keep
+their full height, and queued messages and widgets show their first rows and scroll for the rest. Pi's `tui.altScreen.*` bindings
+(PgUp/PgDn, Ctrl+Home/End and the rest), mouse wheel, selection and search apply. The scrollbar,
+wheel step and copy-on-select behaviour are read from Pi's `fullscreen*` settings. Submitting a
+message and changing session return the transcript to its latest row. The product lockup
+(`welcome.ts`) is the first row of the transcript only while the current chat has no user
+message, so a resumed session with history starts without it and a new, cleared or switched-to
+empty chat shows it again. A header set by a trusted extension with `setHeader` replaces the
+lockup and is never hidden. Hiding the lockup shrinks the rendered rows, so the main screen clears
+and reprints once when the first message is sent.
+
+`regular` uses the main screen with the same components flowing in order, and the terminal keeps
+the scrollback. Leaving fullscreen with `fullscreenExitOutput: "transcript"` (Pi's default) copies
+the rendered conversation into the normal scrollback once the alternate screen is gone; a session
+with no messages writes nothing, and a started chat copies it without the product lockup. Other
+exit-output values are not implemented and write nothing.
+The decision and its consequences are recorded in
+[ADR-0004](decisions/ADR-0004-fullscreen-terminal-layout.md).
+
+## Plan mode and thinking keys
+
+Shift+Tab switches the terminal between normal and plan mode. The switch is announced in the
+transcript. Plan mode narrows the session to read-only inspection (`read`, `grep`, `find`, `ls`),
+questions (`ask_user`, `ask_user_question`) and recall (history and Wiki reads, `memory_facts`). Edits,
+writes, shell commands, memory writes, subagents and connected-app tools are withdrawn until plan mode
+is switched off, and switching back restores the tools the session had. Plan mode belongs to the open
+conversation: a new or resumed session starts in normal mode.
+
+The model is not yet told about the mode through the prompt; it only sees the narrower tool set. That
+instruction belongs in the prompt compiler, the one place model instructions are built. Shift+Up and
+Shift+Down step the thinking level within the levels the model supports, and do not wrap.
+
 ## Reference and reproduced presentation
 
 The reference is **Oh My Pi 18.11.3**, identified from npm and GitHub on 2026-10-17; its release
@@ -58,9 +115,15 @@ In the extracted `pi-tui` package, `src/theme/defaults/titanium.json` establishe
 palette and `src/prompt/welcome.ts` establishes the five-row Pi logo, exact diagonal RGB stops
 and indexed-color fallback, centered lockup and narrow-width behavior. Harness adapts these
 into [`theme.ts`](../src/terminal/tui/theme.ts) and [`welcome.ts`](../src/terminal/tui/welcome.ts),
-with its own product name, package version and existing-command tips. The status band and
-curved `╰─` input framing are implemented in [`status.ts`](../src/terminal/tui/status.ts) and
-[`editor.ts`](../src/terminal/tui/editor.ts). Startup selects the Harness titanium presentation
+with its own product name, package version and existing-command tips. The text-only status band in
+[`status.ts`](../src/terminal/tui/status.ts) shows the project name, branch, account/model/effort,
+the last completed response's output rate and current-session input/output totals. Input totals add
+cache reads and exclude cache writes. The prompt
+frame is implemented in [`editor.ts`](../src/terminal/tui/editor.ts): two full-width neutral
+rules around the prompt, a dim `❯` glyph, a `Try "…"` placeholder before the first prompt of a
+launch, and a `? for shortcuts` footer line above the band. The frame follows the observed
+composer of Claude Code 2.1.302, reproduced from its visible values; no code is copied, and
+`?` opens the same list as `/hotkeys`. Startup selects the Harness titanium presentation
 without rewriting the user's saved theme settings. The shipped OMP light palette is also
 available as `light`; native rich components and the status band switch together. Missing
 Pi-specific color tokens use documented Harness fallbacks in `theme.ts`.
@@ -122,12 +185,22 @@ second key once with `control.claim`, before plugin code loads. [`control.ts`](.
 retains it in a process-local promise shared with the bridge; it is never written to disk or
 placed in the environment. It survives `/new`, resume, fork and reload.
 
-The private key is required for `terminal.pending`, `terminal.approve`, `terminal.answer`,
-`terminal.draft`, `terminal.interrupt` and `terminal.resources`, as well as existing account and
-plugin mutations. A model-spawned shell with only the environment token cannot answer its own
-pending questions or approvals. The application renders decisions obtained from the existing
+The private key is required for `terminal.policy`, `terminal.approval`, `terminal.pending`,
+`terminal.approve`, `terminal.answer`, `terminal.draft`, `terminal.interrupt` and
+`terminal.resources`, as well as existing account and plugin mutations. A model-spawned shell with
+only the environment token cannot submit policy or approval decisions, change permissions, or
+answer its own pending questions. The application renders decisions obtained from the existing
 controller and returns the person's answer through these calls.
 
+Approval prompts offer **Allow once**, **Always allow this tool everywhere** when the host policy
+marks the decision rememberable, and **Deny**. A tool grant covers every call with that tool name
+in Pi terminal sessions using this device's local Harness state directory; for example, Bash grants
+cover every Bash command. `/permissions` lists those grants and lets the person revoke them. Its
+Full Permission switch approves future eligible prompts across those terminal sessions, asks for
+confirmation when enabled, and is off by default. Neither choice approves an already-pending
+request. Hard denials and disabled tools remain enforced; human-only requests stay manual unless
+the host explicitly permits Full Permission for them. Chat approvals keep their separate profile.
+
 The editor sends exact draft state to `terminal.draft`; host delivery waits for that state
 instead of overwriting a draft. Interruption resolves pending socket-backed questions and
 approvals in the run registry before awaiting Pi abort. Disposal uses that order too, avoiding
@@ -156,9 +229,26 @@ reviewable Harness issue draft after confirmation, without attaching history. `/
 reads bundled Harness change notes. `/reload` also applies the isolated account's edited
 keyboard bindings through the public TUI manager.
 
+`/trajectory` opens the newest recorded run for the current native conversation; `/trajectory <run-id>`
+opens a selected run from that conversation. Left/right changes runs, up/down selects recorded
+events, PageUp/PageDown scrolls event details, and `c` copies the selected event. Active runs
+refresh while the overlay is open. The protected terminal socket scopes both the run list and event
+reads to the current terminal and native session file.
+
 ## Verification and remaining limits
 
-Harness typecheck, **419 passing tests / two platform skips**, build and standalone proof
+Fullscreen layout verification, 2026-10-18: [`screen.test.ts`](../src/terminal/tui/screen.test.ts)
+covers the dock on the last rows as the transcript grows and scrolls, notice clipping, regular
+flow, and the exit copy. The PTY verifier against the built CLI passed all 14 interaction groups at
+40×20, 80×24 and 120×40; the retained result is
+[docs/evidence/terminal-2026-10-18-fullscreen](evidence/terminal-2026-10-18-fullscreen/verification.json).
+The verifier's keyboard-list check now waits for the list's first line, because a long notice shows
+its first rows in the dock and scrolls for the rest. The App sidecar's suite passes 30 of 30 and
+`cargo test` passes 217 tests against this tree. The App's root Vitest suite has one failure, the
+pre-existing `PendingRequestDock` expectation. The App sidecar's own `tsc` run reports four errors
+in `agentRuns.ts` and `app.test.ts` that also occur on the checkpoint commit.
+
+Earlier verification, before the fullscreen layout: Harness typecheck, **419 passing tests / two platform skips**, build and standalone proof
 passed on 2026-10-17. A final cleanup-order adjustment was rechecked with all **91 frontend
 tests**, typecheck, build and standalone proof. Coverage includes the real isolated persistent SDK/socket boundary,
 exact history scope and symlink rejection, resource-trust refusal before new/reload, event and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "0.1.7",
+  "version": "2.0.0",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
   "repository": {
@@ -37,9 +37,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.1",
-    "esbuild": "^0.25.10",
+    "esbuild": "^0.28.2",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22.19"
@@ -51,6 +51,7 @@
     "README.md",
     "NOTICE.md",
     "CHANGELOG.md",
-    "docs"
+    "docs",
+    "!docs/evidence/**"
   ]
 }

package/src/accounts/accounts.test.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmdirSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { expect, test } from 'vitest'
@@ -209,6 +209,92 @@ test('a terminal round-trips credentials through auth.json', async () => {
   expect((await accounts.readCredential(account.id, 'anthropic'))?.refresh).toBe('r')
 })
 
+test('a key saved while a terminal runs is kept when that terminal ends', async () => {
+  const { dir, accounts } = service()
+  const account = addAccount(dir, 'A', 'apiKey')
+  ensureHome(dir, account)
+  await accounts.terminalBegin(account)
+  await accounts.writeCredential(account.id, 'deepseek', { type: 'api_key', key: 'k-late' })
+  await accounts.terminalEnd(account)
+  expect((await accounts.readCredential(account.id, 'deepseek'))?.key).toBe('k-late')
+  expect(loadState(dir, account.id).piProviders).toEqual(['deepseek'])
+})
+
+test('a terminal leaves auth.json alone while another live process has a terminal on the account', async () => {
+  const { dir, accounts } = service()
+  const account = addAccount(dir, 'A', 'apiKey')
+  ensureHome(dir, account)
+  await accounts.writeCredential(account.id, 'openai', { type: 'api_key', key: 'k1' })
+  const auth = join(configDir(dir, account), 'auth.json')
+  const leases = join(dir, account.id, 'terminal-leases')
+  mkdirSync(leases, { recursive: true })
+  // The parent process stands in for another Harness that is running.
+  const other = join(leases, String(process.ppid))
+  writeFileSync(other, '{}')
+  writeFileSync(auth, JSON.stringify({ openai: { type: 'oauth', access: 'fresh', refresh: 'r2', expires: 2 } }))
+  await accounts.terminalBegin(account)
+  expect(readFileSync(auth, 'utf8')).toContain('fresh')
+  await accounts.terminalEnd(account)
+  expect(existsSync(auth)).toBe(true)
+  rmSync(other)
+  await accounts.terminalBegin(account)
+  writeFileSync(auth, JSON.stringify({ openai: { type: 'oauth', access: 'fresh', refresh: 'r2', expires: 2 } }))
+  await accounts.terminalEnd(account)
+  expect(existsSync(auth)).toBe(false)
+  expect((await accounts.readCredential(account.id, 'openai'))?.refresh).toBe('r2')
+})
+
+test('a terminal that joins a running one gets the keys saved since, and keeps the tokens already in auth.json', async () => {
+  const { dir, accounts } = service()
+  const account = addAccount(dir, 'A', 'apiKey')
+  ensureHome(dir, account)
+  const auth = join(configDir(dir, account), 'auth.json')
+  const leases = join(dir, account.id, 'terminal-leases')
+  mkdirSync(leases, { recursive: true })
+  writeFileSync(join(leases, String(process.ppid)), '{}')
+  writeFileSync(auth, JSON.stringify({ openai: { type: 'oauth', access: 'fresh', refresh: 'r2', expires: 2 } }))
+  await accounts.writeCredential(account.id, 'openai', { type: 'api_key', key: 'k1' })
+  await accounts.writeCredential(account.id, 'deepseek', { type: 'api_key', key: 'k-late' })
+  await accounts.terminalBegin(account)
+  const merged = JSON.parse(readFileSync(auth, 'utf8'))
+  expect(merged.openai.access).toBe('fresh')
+  expect(merged.deepseek.key).toBe('k-late')
+  rmSync(join(leases, String(process.ppid)))
+  await accounts.terminalEnd(account)
+  expect(existsSync(auth)).toBe(false)
+  expect((await accounts.readCredential(account.id, 'deepseek'))?.key).toBe('k-late')
+})
+
+test('a refresh made by a terminal is saved when it ends, even while another process still uses auth.json', async () => {
+  const { dir, accounts } = service()
+  const account = addAccount(dir, 'A', 'apiKey')
+  ensureHome(dir, account)
+  await accounts.writeCredential(account.id, 'openai', { type: 'oauth', access: 'a1', refresh: 'r1', expires: 1 })
+  const auth = join(configDir(dir, account), 'auth.json')
+  const leases = join(dir, account.id, 'terminal-leases')
+  mkdirSync(leases, { recursive: true })
+  const other = join(leases, String(process.ppid))
+  writeFileSync(other, '{}')
+  await accounts.terminalBegin(account)
+  writeFileSync(auth, JSON.stringify({ openai: { type: 'oauth', access: 'a2', refresh: 'r2', expires: 2 } }))
+  await accounts.terminalEnd(account)
+  expect((await accounts.readCredential(account.id, 'openai'))?.refresh).toBe('r2')
+  expect(existsSync(auth)).toBe(true)
+})
+
+test('a lease left by a process that has ended is removed and does not keep the account busy', async () => {
+  const { dir, accounts } = service()
+  const account = addAccount(dir, 'A', 'apiKey')
+  ensureHome(dir, account)
+  const leases = join(dir, account.id, 'terminal-leases')
+  mkdirSync(leases, { recursive: true })
+  writeFileSync(join(leases, '2147483646'), '{}')
+  await accounts.terminalBegin(account)
+  expect(existsSync(join(leases, '2147483646'))).toBe(false)
+  await accounts.terminalEnd(account)
+  expect(existsSync(join(configDir(dir, account), 'auth.json'))).toBe(false)
+})
+
 test('creating, renaming and removing an account is audited and announced', async () => {
   const { dir, accounts, secrets, notices } = service()
   const created = accounts.create('  Work  ', 'apiKey').accounts[0]

package/src/accounts/accounts.ts

@@ -1,7 +1,7 @@
 // The accounts service: everything that needs the secret store, the Pi runtime, or a notice.
 // Credentials go to the embedding application's secret store; nothing here writes one to the
 // harness's own files, except a terminal session's `auth.json` while that terminal runs.
-import { chmodSync, rmSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
 
@@ -38,6 +38,36 @@ export interface ModelOption {
 
 type Credential = Record<string, unknown> & { type: 'api_key' | 'oauth' }
 
+/** The lease files of an account: one per process that has a terminal on it. */
+const leaseFolder = (dir: string, accountId: string): string => join(dir, accountId, 'terminal-leases')
+
+/** Whether a process with this id exists. One that exists but belongs to another user still counts. */
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/** The credentials in an auth.json, or null when there is no readable file. */
+function readAuth(path: string): Record<string, Credential> | null {
+  try {
+    const parsed = readJson<Record<string, Credential>>(path)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** Compares two credentials by their fields, not their key order, which Pi may change when it rewrites the file. */
+function sameCredential(a: Credential | undefined, b: Credential | undefined): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return JSON.stringify(a, Object.keys(a).sort()) === JSON.stringify(b, Object.keys(b).sort())
+}
+
 function validProvider(provider: string): string {
   if (provider && provider.length <= 64 && /^[A-Za-z0-9._-]+$/.test(provider)) return provider
   throw invalid('Invalid provider name.')
@@ -90,7 +120,10 @@ export class Accounts {
   private readonly runtimes = new Map<string, Promise<ModelRuntime>>()
   private readonly logins = new Map<string, PendingLogin>()
   private readonly latestLogins = new Map<string, AccountLoginSnapshot>()
+  /** How many of this process's terminals use each account's auth.json. */
   private readonly terminals = new Map<string, number>()
+  /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
+  private readonly terminalSnapshots = new Map<string, Record<string, Credential>>()
   private installationDeviceIdPromise: Promise<string> | null = null
 
   constructor(options: AccountsOptions) {
@@ -564,26 +597,44 @@ export class Accounts {
     return this.terminals.get(accountId) ?? 0
   }
 
+  /**
+   * Starts a terminal's use of the account's auth.json. The file is written from the store when the
+   * first terminal of the account begins. While another process's terminal still uses it, the tokens
+   * already in the file stay, because that terminal may have refreshed them; only a provider the file
+   * lacks is added from the store, so a key saved after the other terminal began still reaches this one.
+   */
   async terminalBegin(account: Account): Promise<void> {
     const count = (this.terminals.get(account.id) ?? 0) + 1
     this.terminals.set(account.id, count)
     if (count > 1) return
     const path = join(env.configDir(this.dir, account), 'auth.json')
+    let shared = false
     try {
-      const data: Record<string, unknown> = {}
-      for (const provider of store.loadState(this.dir, account.id).piProviders) {
-        const credential = await this.readCredential(account.id, provider).catch(() => null)
-        if (credential) data[provider] = credential
+      shared = this.otherTerminalProcesses(account.id)
+      this.claimLease(account.id)
+      const existing = shared && existsSync(path) ? readAuth(path) : null
+      const data = await this.storedCredentials(account.id, existing ?? {})
+      if (!existing || Object.keys(data).length > Object.keys(existing).length) {
+        atomicWrite(path, JSON.stringify(data, null, 2))
+        chmodSync(path, 0o600)
       }
-      atomicWrite(path, JSON.stringify(data, null, 2))
-      chmodSync(path, 0o600)
+      this.terminalSnapshots.set(account.id, data)
     } catch (error) {
       this.terminals.delete(account.id)
-      rmSync(path, { force: true })
+      this.terminalSnapshots.delete(account.id)
+      this.releaseLease(account.id)
+      if (!shared) rmSync(path, { force: true })
       throw error
     }
   }
 
+  /**
+   * Ends a terminal's use of the auth.json. Each terminal saves what its Pi changed since it began (a
+   * refreshed or new sign-in, or a provider it signed out of), even while another process still uses the
+   * file, so no refresh is lost when the other terminal ends first. A credential saved to the store after
+   * the terminal began is in neither the file nor the snapshot, so it stays. The last terminal of the
+   * account to end, in every process, removes the file.
+   */
   async terminalEnd(account: Account): Promise<void> {
     const remaining = Math.max(0, (this.terminals.get(account.id) ?? 1) - 1)
     if (remaining > 0) {
@@ -591,21 +642,72 @@ export class Accounts {
       return
     }
     this.terminals.delete(account.id)
+    const snapshot = this.terminalSnapshots.get(account.id) ?? {}
+    this.terminalSnapshots.delete(account.id)
+    this.releaseLease(account.id)
     const path = join(env.configDir(this.dir, account), 'auth.json')
-    let data: Record<string, Credential> | null = null
+    const data = readAuth(path)
+    if (data) {
+      let changed = false
+      for (const provider of new Set([...Object.keys(snapshot), ...Object.keys(data)])) {
+        if (provider in data) {
+          if (sameCredential(data[provider], snapshot[provider])) continue
+          await this.writeCredential(account.id, provider, data[provider]).catch(() => undefined)
+          changed = true
+        } else if (provider in snapshot) {
+          await this.writeCredential(account.id, provider, null).catch(() => undefined)
+          changed = true
+        }
+      }
+      if (changed) {
+        this.invalidate(account.id)
+        store.audit(this.dir, account.id, 'credentials.synced', 'Pi terminal sign-in saved to the Keychain.')
+      }
+    }
+    if (!this.otherTerminalProcesses(account.id)) rmSync(path, { force: true })
+  }
+
+  /** The account's stored credentials, with `existing` kept as it is for every provider it already has. */
+  private async storedCredentials(accountId: string, existing: Record<string, Credential>): Promise<Record<string, Credential>> {
+    const data = { ...existing }
+    for (const provider of store.loadState(this.dir, accountId).piProviders) {
+      if (provider in data) continue
+      const credential = await this.readCredential(accountId, provider).catch(() => null)
+      if (credential) data[provider] = credential
+    }
+    return data
+  }
+
+  /**
+   * Whether another live process has a terminal on this account. Lease files of processes that have
+   * ended are removed, so a crash never leaves the account looking busy.
+   */
+  private otherTerminalProcesses(accountId: string): boolean {
+    const folder = leaseFolder(this.dir, accountId)
+    let names: string[]
     try {
-      const parsed = readJson<Record<string, Credential>>(path)
-      data = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+      names = readdirSync(folder)
     } catch {
-      data = null
+      return false
     }
-    if (data) {
-      for (const provider of store.loadState(this.dir, account.id).piProviders) if (!(provider in data)) await this.writeCredential(account.id, provider, null).catch(() => undefined)
-      for (const [provider, credential] of Object.entries(data)) await this.writeCredential(account.id, provider, credential).catch(() => undefined)
-      this.invalidate(account.id)
-      store.audit(this.dir, account.id, 'credentials.synced', 'Pi terminal sign-in saved to the Keychain.')
+    let others = false
+    for (const name of names) {
+      const pid = Number(name)
+      if (!/^\d+$/.test(name) || pid <= 0 || pid === process.pid) continue
+      if (processAlive(pid)) others = true
+      else rmSync(join(folder, name), { force: true })
     }
-    rmSync(path, { force: true })
+    return others
+  }
+
+  private claimLease(accountId: string): void {
+    const folder = leaseFolder(this.dir, accountId)
+    mkdirSync(folder, { recursive: true, mode: 0o700 })
+    atomicWrite(join(folder, String(process.pid)), JSON.stringify({ pid: process.pid, startedAt: now() }))
+  }
+
+  private releaseLease(accountId: string): void {
+    rmSync(join(leaseFolder(this.dir, accountId), String(process.pid)), { force: true })
   }
 
   // ---- Health from runs ---------------------------------------------------------------------

package/src/core/bus.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, expect, test, vi } from 'vitest'
+
+import { log, logLine, setLogSink } from './bus'
+
+afterEach(() => setLogSink(null))
+
+test('diagnostics go to the sink when one is set, and to stderr otherwise', () => {
+  const lines: string[] = []
+  setLogSink((text) => void lines.push(text))
+  log('maintenance', 'paused')
+  logLine('[index] reindex failed: boom')
+  expect(lines).toEqual(['[harness] maintenance paused', '[index] reindex failed: boom'])
+
+  setLogSink(null)
+  const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  try {
+    logLine('plain')
+    expect(write).toHaveBeenCalledWith('plain\n')
+  } finally {
+    write.mockRestore()
+  }
+})

package/src/core/bus.ts

@@ -28,7 +28,22 @@ export class Bus {
   }
 }
 
-/** Diagnostics go to stderr; stdout may be carrying a protocol. */
+let logSink: ((text: string) => void) | null = null
+
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export function setLogSink(sink: ((text: string) => void) | null): void {
+  logSink = sink
+}
+
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export function logLine(text: string): void {
+  if (logSink) logSink(text)
+  else process.stderr.write(`${text}\n`)
+}
+
 export function log(...parts: unknown[]): void {
-  process.stderr.write(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}\n`)
+  logLine(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}`)
 }