privateer-agent 0.6.6 → 0.6.7

package/README.md

@@ -23,7 +23,8 @@
 </p>
 
 ```bash
-curl -fsSL https://privateer.pro/install.sh | sh    # installs the `privateer` command
+curl -fsSL https://privateer.pro/install.sh | sh    # macOS / Linux — installs the `privateer` command
+irm https://privateer.pro/install.ps1 | iex         # Windows (PowerShell)
 npx privateer-agent                                 # or run it instantly, nothing installed
 ```
 
@@ -33,9 +34,13 @@ Point it at a frontier model today and a local Ollama model tomorrow — **OpenR
 inference), **Venice** / **Fireworks** (no-retention inference), and any **custom
 OpenAI-compatible endpoint** (LM Studio, vLLM, llama.cpp…) are interchangeable at
 `/model` time, including mid-session. No model lock-in, no separate code paths. MCP
-servers, sub-agents, scheduled routines, and one-tap approval from your phone are
-included — and every one of the agent's actions runs through a **safe-by-default
-permission gate**.
+servers, sub-agents, scheduled routines, multi-step workflows, chat-app bridges, and
+one-tap approval from your phone are included — and every one of the agent's actions runs
+through a **safe-by-default permission gate**.
+
+Privateer runs in three places, over one account and one config: the **terminal**, a
+**background daemon** for unattended work, and the **Privateer app** on
+[phone, web](https://privateer.pro), and [desktop](#the-privateer-app).
 
 ## Why Privateer?
 
@@ -95,12 +100,21 @@ silently. The moat is swappable; the floor under it holds.
 - **Honest privacy posture, graded.** A verified TEE and a "we promise not to retain"
   policy are **never rendered the same** — the badge tells you exactly how strong the
   guarantee is (cryptographically verified → observable → policy → none).
-- **Approve it from your phone.** Link the terminal to the Privateer app with
-  `/remote-access` (off by default) and Allow/Deny every action remotely while execution
-  stays on your machine — supervise long agent runs from anywhere.
+- **Drive it from your phone.** Link the terminal with `/remote-access` (off by default) and
+  the Privateer app can send prompts, stream output, and Allow/Deny every action — while
+  execution stays on your machine. Sub-agent actions surface for approval the same way.
+- **Manage it from the app.** Extensions, skills, routines, workflows, MCP connectors, and
+  chat-app channels are all configurable from your phone or the web app, against any linked
+  terminal. See [The Privateer app](#the-privateer-app).
+- **A desktop app.** The same agent hosted inside a local Electron shell — no relay hop, works
+  offline, multi-window with per-window MCP connectors. Shares your CLI login and config.
 - **Scheduled routines.** A background daemon runs approved tasks unattended — cron or
   one-off — and the agent can schedule its own follow-up work. Results deliver to a file,
   the next session, your phone, email, or a webhook.
+- **Declarative workflows.** Multi-step agent pipelines as YAML — typed steps, conditional
+  routing between them, and `human_gate` steps that pause for your approval and resume.
+- **Chat-app channels.** Bridge the agent into Telegram, Slack, Discord, or WhatsApp with
+  role-based approval — admins can approve actions, members are read-only.
 - **MCP servers, sub-agents & skills.** Connect Model Context Protocol servers (local stdio
   or remote HTTP with OAuth), delegate work to bounded parallel sub-agents, and drop in
   skills — all gated like everything else.
@@ -124,14 +138,27 @@ No install at all: `npx privateer-agent`.
 ## Install
 
 ```bash
-npm install -g privateer-agent          # installs the `privateer` command
-# or run it without installing:
-npx privateer-agent
-# or the one-liner installer (verifies Node, then installs globally):
-curl -fsSL https://privateer.pro/install.sh | sh
+# the one-liner installer — downloads a self-contained bundle, no Node needed:
+curl -fsSL https://privateer.pro/install.sh | sh    # macOS / Linux
+irm https://privateer.pro/install.ps1 | iex        # Windows (PowerShell)
+
+# or via npm, if you'd rather manage it yourself (needs Node ≥ 22.19):
+npm install -g privateer-agent
+npx privateer-agent                                 # run without installing
 ```
 
-**Requirements:** macOS or Linux, Node.js ≥ 22.19.0.
+**Requirements:** macOS (arm64/x64), Linux (x64), or Windows (x64). The installers ship a
+**pinned Node runtime inside the bundle**, so you don't need Node or npm on your machine at
+all — Node ≥ 22.19.0 is only required for the `npm` / `npx` path.
+
+Update in place with **`privateer update`** (bundle-aware: it re-runs the right installer
+for how you installed) or check your version with `privateer --version`.
+
+> **Windows:** the agent's command tool needs a bash, which Windows doesn't ship. Install
+> Git for Windows (or WSL) and Privateer will find it; the launcher checks at startup and
+> tells you how to fix it if not. Override the choice with `shellPath` in
+> `~/.privateer/agent/settings.json`. Linux arm64 and Windows arm64 bundles aren't built
+> yet — arm64 Windows runs the x64 bundle under emulation.
 
 ### Verifying what you're about to run
 
@@ -248,13 +275,106 @@ with `/signout`; manage linked terminals from the app.
 > to spend on your account. If someone sends you a code and asks you to approve it, don't —
 > that hands *them* a billed session on *your* account.
 
-## Approve from your phone
+## The Privateer app
+
+The same account drives Privateer from **iOS, Android, [the web app](https://privateer.pro),
+and a desktop app**. The terminal stays where the work happens — the app is a remote control
+and a management surface for it.
+
+### Linking a terminal
+
+1. Run **`privateer`** and **`/signin`**. It prints a short device code.
+2. Open the app → **Link a terminal**, enter the code (or tap the deep link). No password or
+   wallet key ever touches the terminal, and the app pins the terminal's public key on first
+   link.
+3. In the terminal, turn on **`/remote-access`** (off by default). The terminal now shows
+   **Online** in the app.
+
+> **Only approve a code you generated yourself.** Approving someone else's code hands *them*
+> a billed session on *your* account.
+
+### What you can do from the app
+
+| | |
+|---|---|
+| **Drive a session** | Send prompts, watch streamed output, and **Allow/Deny** each proposed action — including actions from sub-agents the session spawned |
+| **Spawn an agent** | Start a one-shot task on the daemon: *background* (headless, read-only toolset, result sealed to your outbox) or *live* (a fresh drivable session) |
+| **Routines** | Create, edit, pause, run, and delete scheduled unattended tasks |
+| **Workflows** | List, run, and monitor multi-step workflows; answer `human_gate` steps to resume a paused run |
+| **MCP connectors** | Add, edit, and enable MCP servers; credentials are sealed to the terminal and write-only |
+| **Channels** | Configure the Telegram / Slack / Discord / WhatsApp bridges — admins, members, posture, tool ceiling, model |
+| **Extensions & skills** | Install Pi extensions from the catalog; create, edit, and run `SKILL.md` skills |
+
+Config changes that carry secrets or executable content (MCP credentials, channel bot
+tokens, workflows with `script` steps) are **sealed to the terminal's pinned key and signed
+by your account** — the relay forwards them blind and can neither read nor forge them.
+
+The relay itself is live-only (nothing is archived), carries no API keys, and output is
+size-truncated and run through a best-effort secret redactor before it leaves your machine.
+
+### Desktop app
+
+The desktop app hosts the agent **in-process** and talks to it over loopback IPC — no relay,
+no network hop, and it works offline. It reads the same `~/.privateer` home, so it shares
+your CLI login, model config, and MCP catalog. Multi-window, with a per-window subset of
+your MCP connectors and a native folder picker.
+
+Download for [macOS](https://privateer.pro/download/mac) (Apple silicon),
+[macOS Intel](https://privateer.pro/download/mac-intel), or
+[Windows](https://privateer.pro/download/windows).
+
+It's an early release and **not yet code-signed or notarized** — macOS will warn on first
+open. Routines and channels deliberately aren't hosted here: those belong to the always-on
+daemon, so background work still wants `privateer daemon install`.
 
-Turn on **`/remote-access`** (off by default) to link this terminal to the Privateer app. The
-app can then drive the terminal — prompts come down, and each proposed action goes up for
-**Allow/Deny** — while execution stays on your machine. The relay is live-only (nothing is
-archived), carries no keys, and output is size-truncated and run through a best-effort secret
-redactor before it leaves.
+## Run it unattended — the daemon
+
+A resident background daemon runs scheduled routines, executes workflows, and accepts task
+spawns from the app — with no terminal open.
+
+```bash
+privateer daemon install      # install as a login service (auto-starts, reachable from the app)
+privateer daemon status       # service installed? daemon answering?
+privateer daemon run          # or just run it in the foreground
+privateer daemon uninstall
+```
+
+Installs as a **launchd user agent** on macOS or a **`systemd --user` unit** on Linux — no
+root, no sudo. (There's no Windows service path yet; use `privateer daemon run`.)
+
+Everything the daemon does still runs through the permission gate. Actions needing approval
+surface in the app; routines you approved once run on their own schedule.
+
+## Workflows
+
+A workflow is a **YAML file describing a multi-step agent pipeline** — a flat graph of typed
+steps (`agent`, `script`, `human_gate`) with conditional routes between them and `{{ }}`
+templating to pass values along. A `human_gate` step pauses the run for your approval and
+resumes when you answer it, including from your phone.
+
+The engine ships in the standalone
+[`privateer-workflow`](https://www.npmjs.com/package/privateer-workflow) package. Today the
+user-facing surface is the **app** (save, run, monitor, share) and the **daemon** that
+executes them — there's no `/workflow` command in the terminal yet. Schedule one by pointing
+a routine at it.
+
+Because a workflow can carry `script` steps, saving one from the app requires your **account
+signature** — the server can't inject a workflow onto your daemon.
+
+## Chat-app channels
+
+Bridge the agent into **Telegram, Slack, Discord, or WhatsApp** so you can hand it work from
+a group chat. Each channel has:
+
+- **Roles** — `admins` can approve actions; `members` are always read-only, no exceptions.
+- **A posture** — `readonly`, `approve` (default), or `auto`.
+- **A hard tool ceiling** — a per-channel allowlist the agent can't exceed even in `auto`.
+
+Configure a channel from the app, or by hand in the `channels` block of
+`~/.privateer/config.json`. Changes take effect on restart, by design. Bot tokens set from
+the app are write-only — the app can name them but never read them back. Note that tokens
+live in plaintext in `config.json` on your machine, and every channel action is appended to
+`~/.privateer/channels-audit.log`.
 
 ## Permission modes
 
@@ -289,14 +409,35 @@ Everything below is a **Pi extension** loaded by discovery (see [Built on Pi](#b
 drop your own into `~/.privateer/agent/extensions/` and it loads the same way, gated like the rest.
 
 - **MCP servers** (`pi-mcp-adapter`) — declare them and their tools become first-class, gated
-  like the rest (local stdio, or remote HTTP with interactive OAuth).
-- **Sub-agents** (`pi-subagents`) — delegate investigations to bounded parallel agents that run
-  under the same permission gate.
+  like the rest (local stdio, or remote HTTP with interactive OAuth). One catalog at
+  `~/.privateer/agent/mcp-desktop.json` is shared by the CLI, the daemon, and the desktop
+  app, so a machine has one coherent connector config.
+- **Sub-agents** (`pi-subagents`) — delegate investigations to bounded parallel agents. Children
+  run as headless child processes that **inherit the moat**, so their actions hit the same
+  permission gate and their approvals surface on your phone.
 - **Routines** — saved tasks the daemon runs unattended; ask the agent to schedule work and
   approve it once.
+- **Workflows** — declarative multi-step pipelines the daemon executes; see
+  [Workflows](#workflows).
 - **Web tools** (`rpiv-web-tools`) — private-by-default web search/fetch with pluggable backends
   (self-hosted SearXNG for fully private search).
 
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `/model` · `/models` | switch model; `/models` is a searchable picker with TEE/ZDR privacy shields |
+| `/mode` | switch permission mode |
+| `/verify` | fetch and check the TEE attestation for the current model |
+| `/signin` · `/signout` | sign in to a Privateer account (device flow) / sign out |
+| `/remote-access` | link this terminal to the app and allow it to drive (off by default) |
+| `/extensions` | list loaded Pi extensions |
+| `/init` | scaffold a starter `PRIVATEER.md` in this directory |
+| `/update` · `/privateer` | update to the latest release / Privateer status and posture |
+
+Shell subcommands: `privateer` (interactive), `privateer update`, `privateer daemon …`,
+`privateer --no-quarter`, `privateer --version`.
+
 ## Develop
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",

package/src/auth/accountSessions.ts

@@ -0,0 +1,154 @@
+// Which account-provider inference sessions this machine has spawned, and which
+// terminal owns each one.
+//
+// The problem this solves: every launch used to spawn a NEW server-side session, and
+// only a CLEAN exit revoked it (session_shutdown → revokeLocalSessions). A terminal
+// that dies without running its shutdown hook — SIGKILL, a closed window, a crash,
+// `kill` — leaves its session row alive server-side for the rest of its ~24h TTL. Do
+// that a few times and the next spawn is refused with
+// `429 CHILD_SESSION_CAP: Too many active terminals for this device`, which takes the
+// whole account channel down until the rows age out.
+//
+// The fix is to reclaim an orphan instead of stacking another row on top of it. That
+// needs one bit the credential itself can't tell us: is the terminal that owns it
+// still RUNNING? A live terminal's session must never be touched — adopting it rotates
+// its refresh token out from under it and kills a working session (they rotate in
+// isolation, one per terminal, by design). So each entry records the owning pid, and
+// a session counts as orphaned only once that pid is gone.
+//
+// pid liveness is signal-0. The failure mode is asymmetric and we lean on that: a
+// RECYCLED pid makes a dead owner look alive, so we skip a reclaimable session and
+// spawn a fresh one — the old behaviour, no harm. The dangerous direction (a live
+// process reported dead) can't happen: a running pid never reports ESRCH.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { accountSessionsPath, globalDir } from "../config/paths.ts";
+
+// One spawned session, keyed in the file by the pid of its owning terminal. `refresh`
+// is what lets a later launch adopt or revoke it; `expires` is its access token's exp
+// (see jwtExpMs), used only to prune entries that are dead server-side anyway.
+export interface OwnedSession {
+  pid: number;
+  refresh: string;
+  expires: number;
+}
+
+type Registry = Record<string, { refresh?: unknown; expires?: unknown }>;
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* best effort — a restrictive umask or an odd filesystem */
+  }
+}
+
+function readRegistry(): Registry {
+  const path = accountSessionsPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Registry) : {};
+  } catch {
+    return {}; // corrupt/truncated — start clean rather than wedging every launch
+  }
+}
+
+// Write via temp + rename so a concurrent reader never sees a half-written file. Two
+// terminals racing can still lose one entry (last writer wins); the cost is one
+// unreclaimable orphan, not a broken launch, so a lock file isn't worth it here.
+function writeRegistry(reg: Registry): void {
+  const path = accountSessionsPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    tryChmod(globalDir(), 0o700);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(reg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    tryChmod(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch {
+    /* best effort — losing the registry costs reclamation, never correctness */
+  }
+}
+
+// Is a pid still running? EPERM means it exists but belongs to another user, which is
+// still "alive" — and alive is the safe answer (we skip reclamation rather than risk
+// hijacking a live terminal's session).
+function isAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function parseEntry(pid: string, raw: { refresh?: unknown; expires?: unknown }): OwnedSession | null {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || typeof raw?.refresh !== "string" || !raw.refresh) return null;
+  return { pid: n, refresh: raw.refresh, expires: typeof raw.expires === "number" ? raw.expires : 0 };
+}
+
+// Claim (or re-claim) a session for THIS process. Called wherever the account
+// credential is minted or rotated — spawnAccountCredentials and
+// refreshAccountCredentials — so the registry always holds the token that would
+// actually work, including the rotations Pi drives on its own.
+export function recordOwnedSession(cred: { refresh: string; expires: number }): void {
+  const reg = readRegistry();
+  reg[String(process.pid)] = { refresh: cred.refresh, expires: cred.expires };
+  writeRegistry(reg);
+}
+
+// Drop this process's entry — the session is being revoked (clean exit, /signout), so
+// it is about to stop existing server-side. Leaving it behind would advertise a dead
+// session as a reclaimable orphan to the next launch.
+export function forgetOwnedSession(): void {
+  const reg = readRegistry();
+  if (!(String(process.pid) in reg)) return;
+  delete reg[String(process.pid)];
+  writeRegistry(reg);
+}
+
+// Sessions whose owning terminal is gone: candidates to adopt or revoke. Prunes
+// entries that are unusable anyway (malformed, or past their expiry) as a side
+// effect, so the file can't grow without bound. Our own pid is never a candidate.
+export function orphanedSessions(now = Date.now()): OwnedSession[] {
+  const reg = readRegistry();
+  const orphans: OwnedSession[] = [];
+  let pruned = false;
+
+  for (const [pid, raw] of Object.entries(reg)) {
+    const entry = parseEntry(pid, raw);
+    if (!entry || (entry.expires > 0 && entry.expires <= now)) {
+      delete reg[pid]; // malformed, or dead server-side — nothing to reclaim
+      pruned = true;
+      continue;
+    }
+    if (entry.pid === process.pid || isAlive(entry.pid)) continue; // ours, or a live terminal's
+    orphans.push(entry);
+  }
+
+  if (pruned) writeRegistry(reg);
+  return orphans;
+}
+
+// Forget one orphan, once it has been definitively handled (adopted, or confirmed dead
+// server-side). A entry whose refresh merely FAILED TO REACH the server is deliberately
+// kept: dropping it on a network blip would leak that row until its TTL.
+export function dropOwnedSession(pid: number): void {
+  const reg = readRegistry();
+  if (!(String(pid) in reg)) return;
+  delete reg[String(pid)];
+  writeRegistry(reg);
+}
+
+// Test seam: wipe the registry file.
+export function clearOwnedSessions(): void {
+  try {
+    rmSync(accountSessionsPath(), { force: true });
+  } catch {
+    /* nothing to remove */
+  }
+}

package/src/auth/privateer.ts

@@ -15,6 +15,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
 import { hostname, userInfo } from "node:os";
 import { globalDir, credentialsPath } from "../config/paths.ts";
+import {
+  type OwnedSession,
+  recordOwnedSession,
+  forgetOwnedSession,
+  orphanedSessions,
+  dropOwnedSession,
+} from "./accountSessions.ts";
 import { isAccountCapCode } from "../engine/errors.ts";
 import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
 import { pinAccountSignKey, clearAccountSignKey } from "../crypto/accountTrust.ts";
@@ -117,6 +124,15 @@ let _refreshInFlight: Promise<ChildSession> | null = null;
 // right after revokeLocalSessions() so the next launch spawns a fresh session instead
 // of reusing the revoked one. Doing both is safe; doing only one is not. See
 // revokeLocalSessions and its callers (cli/chat.ts, daemon/index.ts).
+//
+// That pairing only covers a CLEAN exit, though. A terminal killed without running its
+// shutdown hook leaves its row alive server-side for the full TTL, and the next launch
+// used to spawn another on top of it — enough repeats and the spawn is refused with
+// `429 CHILD_SESSION_CAP`. So every session is also recorded in a pid-keyed registry
+// (auth/accountSessions.ts) and acquireAccountCredential reclaims one whose owning
+// terminal is gone instead of spawning. Keep the registry in step with reality:
+// recordOwnedSession wherever a credential is minted or rotated, forgetOwnedSession
+// wherever one is revoked.
 let _account: { accessToken: string } | null = null;
 
 export function loadCredentials(): Credentials | null {
@@ -375,6 +391,29 @@ export async function runDeviceLogin(opts: {
  * isolation, so two terminals never fight over one rotating token (which would
  * trip the server's reuse-detection and revoke every session).
  */
+// Turn a failed /auth/session/spawn into an accurate error.
+//
+// A 401 means the parent refresh token is gone — the machine login itself is dead, so
+// clear it and announce (the UI flips to signed-out). EVERY OTHER status used to be
+// reported as an expiry too, which actively misled: the common one is 429
+// `CHILD_SESSION_CAP` ("Too many active terminals for this device. Sign one out and
+// try again"), where /login is not the fix and the credentials are perfectly valid.
+// Pass the server's own message through so the user learns what to actually do.
+async function spawnFailure(res: Response): Promise<Error> {
+  if (res.status === 401) {
+    clearCredentials();
+    notifySessionExpired();
+    return new Error("Your Privateer session expired. Run /login to sign in again.");
+  }
+  let message: string | undefined;
+  try {
+    message = ((await res.json()) as { message?: string }).message;
+  } catch {
+    /* non-JSON body — fall back to the status line below */
+  }
+  return new Error(message?.trim() || `Couldn't start a Privateer session (HTTP ${res.status}).`);
+}
+
 async function spawnChildSession(): Promise<ChildSession> {
   const parent = loadCredentials();
   if (!parent) throw new Error("Not logged in to Privateer. Run /login.");
@@ -389,14 +428,7 @@ async function spawnChildSession(): Promise<ChildSession> {
   }, {
     headers: { Authorization: `Bearer ${parent.accessToken}` },
   });
-  if (!res.ok) {
-    // Parent refresh token invalid/expired → the machine login is gone.
-    if (res.status === 401) {
-      clearCredentials();
-      notifySessionExpired();
-    }
-    throw new Error("Your Privateer session expired. Run /login to sign in again.");
-  }
+  if (!res.ok) throw await spawnFailure(res);
   const { accessToken, refreshToken } = (await res.json()) as ChildSession;
   _child = { accessToken, refreshToken };
   return _child;
@@ -543,6 +575,10 @@ export async function revokeAccountSession(timeoutMs = 1500): Promise<void> {
   const account = _account;
   if (!account) return;
   _account = null;
+  // Stop advertising this session as reclaimable BEFORE killing it: an entry left
+  // behind would offer the next launch a dead row to adopt (it would fail over to a
+  // spawn, but only after a wasted round trip).
+  forgetOwnedSession();
   await deleteSession(account.accessToken, timeoutMs);
 }
 
@@ -615,26 +651,102 @@ export async function spawnAccountCredentials(): Promise<AccountCredential> {
     { refreshToken: parent.refreshToken, deviceLabel: defaultDeviceLabel() },
     { headers: { Authorization: `Bearer ${parent.accessToken}` } },
   );
+  if (!res.ok) throw await spawnFailure(res);
+  const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
+  _account = { accessToken }; // track for explicit sign-out revoke (revokeAccountSession)
+  const cred = { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
+  recordOwnedSession(cred); // claim the row, so a crash leaves it reclaimable
+  return cred;
+}
+
+// An /auth/refresh the server actively REFUSED, as opposed to one that never got an
+// answer. Only the former proves the session is gone; a network failure says nothing,
+// and treating it as death would leak the row (see dropOwnedSession).
+export interface RefreshRejection extends Error {
+  status: number;
+}
+
+export function isRefreshRejection(e: unknown): e is RefreshRejection {
+  return e instanceof Error && typeof (e as RefreshRejection).status === "number";
+}
+
+// Rotate a session's refresh token, with NO ownership side effects. Split out from
+// refreshAccountCredentials so orphan cleanup can rotate a session purely to obtain a
+// token it can revoke with, without claiming that session as this terminal's own.
+async function rotateSession(refresh: string): Promise<AccountCredential> {
+  const res = await postJson(serverBaseUrl(), "/auth/refresh", { refreshToken: refresh });
   if (!res.ok) {
-    if (res.status === 401) {
-      clearCredentials();
-      notifySessionExpired();
-    }
-    throw new Error("Your Privateer session expired. Run /login to sign in again.");
+    const err = new Error(`account refresh failed (${res.status})`) as RefreshRejection;
+    err.status = res.status;
+    throw err;
   }
   const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
-  _account = { accessToken }; // track for explicit sign-out revoke (revokeAccountSession)
   return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
 }
 
 // Rotate this account credential's own refresh token; caller falls back to a fresh
 // spawn if this throws (expired/reused child token).
 export async function refreshAccountCredentials(refresh: string): Promise<AccountCredential> {
-  const res = await postJson(serverBaseUrl(), "/auth/refresh", { refreshToken: refresh });
-  if (!res.ok) throw new Error(`account refresh failed (${res.status})`);
-  const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
-  _account = { accessToken }; // the rotated session is the one an explicit sign-out revokes
-  return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
+  const cred = await rotateSession(refresh);
+  _account = { accessToken: cred.access }; // the rotated session is the one an explicit sign-out revokes
+  // Re-claim on every rotation — including the ones Pi drives on expiry — so the
+  // registry always holds a token that would actually work if we crashed right now.
+  recordOwnedSession(cred);
+  return cred;
+}
+
+// Get an account credential for THIS terminal, reusing a session orphaned by a
+// terminal that died without revoking rather than stacking another row on top of it.
+//
+// Reclaiming is what keeps a crash from costing a permanent session slot: each orphan
+// otherwise sits on the server for its full TTL, and enough of them earn a
+// `429 CHILD_SESSION_CAP` on the next spawn. A successful /auth/refresh doubles as the
+// liveness probe — it proves the row is real and hands back a usable access token —
+// so an orphan that turns out to be dead just falls through to the next candidate.
+//
+// Orphans we don't adopt are revoked in the background: their terminal is gone, so the
+// row is pure waste, and freeing it is what actually unwinds an account already at the
+// cap. Never touches a session whose owner is still running (see accountSessions.ts).
+export async function acquireAccountCredential(): Promise<AccountCredential> {
+  const orphans = orphanedSessions();
+  let adopted: AccountCredential | null = null;
+  let attempted = 0;
+
+  while (attempted < orphans.length && !adopted) {
+    const orphan = orphans[attempted++];
+    try {
+      adopted = await refreshAccountCredentials(orphan.refresh);
+      dropOwnedSession(orphan.pid); // the rotation above re-recorded it under OUR pid
+    } catch (e) {
+      // Refused → the session is gone; stop tracking it. Unreachable → keep it, so a
+      // network blip doesn't strand a live row we could have reclaimed next launch.
+      if (isRefreshRejection(e)) dropOwnedSession(orphan.pid);
+    }
+  }
+
+  // Best-effort cleanup of the ones we didn't need. Detached: freeing slots must never
+  // delay startup, and a failure here costs nothing the next launch can't retry.
+  const leftovers = orphans.slice(attempted);
+  if (leftovers.length) void revokeOrphanedSessions(leftovers);
+
+  return adopted ?? (await spawnAccountCredentials());
+}
+
+// Revoke sessions whose terminal is gone. Revoking needs a LIVE access token
+// (DELETE /auth/session/current is Bearer-authenticated) and an orphan's stored one is
+// usually stale, so rotate first — via rotateSession, which deliberately does NOT claim
+// ownership: these sessions are being destroyed, not adopted, and recording them would
+// overwrite the entry for the credential this terminal is actually using.
+async function revokeOrphanedSessions(orphans: OwnedSession[], timeoutMs = 1500): Promise<void> {
+  for (const orphan of orphans) {
+    try {
+      const cred = await rotateSession(orphan.refresh);
+      await deleteSession(cred.access, timeoutMs);
+      dropOwnedSession(orphan.pid);
+    } catch (e) {
+      if (isRefreshRejection(e)) dropOwnedSession(orphan.pid);
+    }
+  }
 }
 
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {

package/src/cli/chat.ts

@@ -341,7 +341,7 @@ async function main() {
   // resolves it; Pi then manages refresh on expiry via the registered oauth provider.
   if (provider === "privateer") {
     try {
-      const creds = await priv.spawnAccountCredentials();
+      const creds = await priv.acquireAccountCredential();
       (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
     } catch (e) {
       console.log(`${RED}Account channel unavailable: ${(e as Error).message}${RESET}`);

package/src/config/paths.ts

@@ -39,3 +39,12 @@ export function credentialsPath(): string {
 export function configPath(): string {
   return join(globalDir(), "config.json");
 }
+
+// Account-provider inference sessions this MACHINE has spawned, keyed by the pid of
+// the terminal that owns each one (see auth/accountSessions.ts). Lets a launch tell a
+// session belonging to a STILL-RUNNING terminal from one orphaned by a crash, so it
+// can reclaim the orphan instead of spawning another and walking into the server's
+// per-device terminal cap. Holds refresh tokens — written 0600, like credentials.json.
+export function accountSessionsPath(): string {
+  return join(globalDir(), "account-sessions.json");
+}

package/src/daemon/index.ts

@@ -30,7 +30,7 @@ import { openJsonFromApp } from "../crypto/terminalUnseal.ts";
 import { verifyChannelSave, verifyOutboxKey } from "../crypto/accountVerify.ts";
 import { loadAccountSignKey, loadLastControlTs, saveLastControlTs } from "../crypto/accountTrust.ts";
 import { authorizeControl } from "../remote/controlAuth.ts";
-import { hasCredentials, revokeLocalSessions, revokeAccountSession, apiRequest, spawnAccountCredentials, handleServerRevoke } from "../auth/privateer.ts";
+import { hasCredentials, revokeLocalSessions, revokeAccountSession, apiRequest, acquireAccountCredential, handleServerRevoke } from "../auth/privateer.ts";
 import {
   loadRoutines,
   upsertRoutine,
@@ -735,7 +735,7 @@ export class Daemon {
       const { provider, modelId } = parseSpec(spec.model);
       if (provider === "privateer") {
         try {
-          const creds = await spawnAccountCredentials();
+          const creds = await acquireAccountCredential();
           (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
           spawnedAccount = true;
         } catch (e) {

package/src/providers/account.ts

@@ -15,7 +15,7 @@ import {
   hasCredentials,
   runDeviceLogin,
   authedFetch,
-  spawnAccountCredentials,
+  acquireAccountCredential,
   refreshAccountCredentials,
   notifySignedIn,
 } from "../auth/privateer.ts";
@@ -169,7 +169,7 @@ export const privateerOAuthProvider = {
       }
     }
     if (cb.signal?.aborted) throw new Error("Login cancelled");
-    const creds = await spawnAccountCredentials();
+    const creds = await acquireAccountCredential();
     // Seed Pi's saved model default to the account channel, so the next launch resolves
     // to a billable subscription model instead of falling through to a keyless built-in
     // (the "No API key found for openrouter" trap). No-op if the user already has a
@@ -184,8 +184,10 @@ export const privateerOAuthProvider = {
     try {
       return await refreshAccountCredentials(creds.refresh);
     } catch {
-      // child token expired/reused → spawn a fresh one from the parent login.
-      return spawnAccountCredentials();
+      // Child token expired/reused → get another. acquire (not spawn) so a terminal
+      // that already holds the device's last session slot can reclaim an orphan
+      // instead of being refused a fresh one mid-session.
+      return acquireAccountCredential();
     }
   },
   getApiKey(creds: { access: string }): string {
@@ -256,6 +258,7 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
 export function makeAccountProvider() {
   return (pi: {
     registerProvider?: (name: string, config: unknown) => void;
+    on?: (event: string, handler: (e: unknown, ctx: unknown) => void) => void;
   }): void => {
     if (typeof pi.registerProvider !== "function") return;
     const register = (ids: string[]): void =>
@@ -274,5 +277,57 @@ export function makeAccountProvider() {
       .catch(() => {
         /* keep the fallback model */
       });
+
+    // Seed the account channel's credential at launch. Nothing else does this in the
+    // TUI: Pi only obtains an OAuth credential by running /login, and our shutdown
+    // hook deliberately REVOKES the account session and deletes its persisted
+    // auth.json entry (see the LIFECYCLE HAZARD note in src/auth/privateer.ts). So a
+    // signed-in user who quits and relaunches lands on privateer/* with no key at
+    // all, and the first prompt dead-ends on "No API key found for privateer." — even
+    // though the banner says "connected". The REPL (cli/chat.ts) and the daemon
+    // already spawn one at startup; this gives the TUI the same seed.
+    pi.on?.("session_start", (_e, ctx) => void ensureAccountCredential(ctx));
   };
 }
+
+// One spawn per PROCESS. session_start also fires for new/resume/fork/reload — all of
+// which keep this process (and its account session) alive — so re-spawning there would
+// leak a device row per event. A fresh process always spawns: a run that crashed
+// without its shutdown hook can leave a REVOKED credential persisted in auth.json with
+// a still-valid-looking `expires`, which Pi would happily reuse and 401 on.
+//
+// The flag lives on globalThis, not in module scope, because jiti gives each extension
+// that imports this file its OWN module instance (see the note in auth/privateer.ts):
+// privateer-account and privateer-brand — which hot-registers the provider on /signin —
+// would otherwise hold separate flags and each spawn a session.
+const SEEDED = Symbol.for("privateer.accountCredentialSeeded");
+type SeedFlag = { [SEEDED]?: boolean };
+
+// `ctx` is Pi's ExtensionContext; the auth store hangs off its model registry (the same
+// path privateer-brand uses to DROP the credential on sign-out).
+type SeedContext = {
+  modelRegistry?: { authStorage?: { set?: (provider: string, cred: unknown) => void } };
+  hasUI?: boolean;
+  ui?: { notify?: (message: string, level: string) => void };
+};
+
+async function ensureAccountCredential(ctx: unknown): Promise<void> {
+  const flag = globalThis as SeedFlag;
+  if (flag[SEEDED] || !hasCredentials()) return;
+  flag[SEEDED] = true;
+  const store = (ctx as SeedContext)?.modelRegistry?.authStorage;
+  if (typeof store?.set !== "function") return;
+  try {
+    const creds = await acquireAccountCredential();
+    store.set("privateer", { type: "oauth", ...creds });
+  } catch (e) {
+    // The account channel is NOT armed: a dead machine login (401 → credentials cleared
+    // + onSessionExpired), the terminal cap (429), or a network blip. Say so now — the
+    // banner still reads "connected" (it only knows about the local credentials file),
+    // so staying silent leaves the user to discover it as a bare "No API key found for
+    // privateer" on their first prompt. Cleared so a later attempt can retry.
+    flag[SEEDED] = false;
+    const c = ctx as SeedContext;
+    if (c?.hasUI) c.ui?.notify?.(`Privateer account channel unavailable — ${(e as Error).message}`, "error");
+  }
+}