privateer-agent 0.6.6 → 0.6.8

package/extensions/privateer-brand.ts

@@ -5,25 +5,30 @@
 //   1. A branded startup header — the anchor mark + "✻ PRIVATEER" wordmark + the
 //      "Chart your own course privately." tagline (ported from tree-cli's Banner).
 //   2. A live status-bar badge (⚓ account) showing the sign-in state at a glance.
-//   3. Sign-in UX — /signin, /signout, and a /privateer hub — which drive the
+//   3. Auth UX — /login, /logout, and a /privateer hub — which drive the
 //      device-code flow the account channel needs.
 //
-// Pi already owns /login and /logout for PROVIDER auth (and /whoami), so we do NOT
-// shadow them. The account provider now registers unconditionally (see
-// makeAccountProvider), so Privateer appears under Pi's /login "Use a subscription"
-// list and a first-time user CAN sign in through provider auth. /signin remains as a
-// friendlier, dedicated shortcut that drives the same account device-code flow
-// directly — one obvious command instead of /login → pick a provider.
+// ONE vocabulary, deliberately: log in / log out. This file used to avoid shadowing
+// Pi's built-in /login and /logout and shipped /signin and /signout alongside them,
+// which left the user with two auth vocabularies and — worse — a /logout that did
+// not log you out. Pi's /logout only clears Pi's own authStorage; the Privateer
+// machine login lives in ~/.privateer/credentials.json and survived it, so /logout
+// on a signed-in machine reported "No stored credentials to remove" and changed
+// nothing. We now own both verbs: /logout here is canonical and Pi's built-in is
+// redirected to it (patches/, same mechanism as the /model → /models redirect).
+// /signin and /signout stay as undocumented aliases for muscle memory.
 //
-// On a successful /signin we hot-register the account provider so privateer/* models
-// appear immediately (the account catalog refreshes to the live listing without a
-// restart).
+// The account provider also registers unconditionally (see makeAccountProvider), so
+// Privateer appears under Pi's "Use a subscription" list and a first-time user can
+// log in that way too. On a successful login we hot-register the account provider so
+// privateer/* models appear immediately (the account catalog refreshes to the live
+// listing without a restart).
 
 import { readFileSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import * as priv from "../src/auth/privateer.ts";
-import { makeAccountProvider } from "../src/providers/account.ts";
+import { armAccountCredential, makeAccountProvider } from "../src/providers/account.ts";
 import { resolveSignedInModel } from "../src/providers/defaultModel.ts";
 import { discoverContextFiles, onContextChanged } from "../src/context.ts";
 import { type Palette, paletteFor } from "../src/ui/palette.ts";
@@ -345,11 +350,18 @@ export default function privateerBrand(pi: any): void {
     }
   }
 
+  // /login. Signing in must leave the terminal ABLE TO PROMPT, not merely "connected" —
+  // so this runs the device flow, hot-registers the account provider, then hands off to
+  // activateSignedInModel to arm the channel and select the model. Every step reports.
   async function doSignIn(ctx: any): Promise<void> {
     if (priv.hasCredentials()) {
       const u = priv.currentUser();
+      // Already linked: still make sure THIS session can use the account (a terminal
+      // launched before the login, or one whose channel never armed, otherwise sits
+      // "signed in" and unusable), then point at the two things they might have meant.
+      await activateSignedInModel(ctx, { switchModel: false });
       return ctx?.ui?.notify?.(
-        `Already signed in as ${u?.email ?? u?.id}. Run /signout to switch accounts.`,
+        `Signed in as ${u?.email ?? u?.id}. Run /logout to switch accounts, or /login keys to add a provider API key.`,
         "info",
       );
     }
@@ -367,7 +379,7 @@ export default function privateerBrand(pi: any): void {
               `${p.DIM}Approve this terminal in the Privateer app:${p.RESET}`,
               `   code   ${p.BOLD}${p.ACCENT}${userCode}${p.RESET}`,
               uri ? `${p.DIM}   or open ${p.RESET}${p.INK}${uri}${p.RESET}` : "",
-              `${p.DIM}   waiting for approval…${p.RESET}`,
+              `${p.DIM}   waiting for approval… ${p.RESET}${p.DIM}(esc to cancel · ${p.RESET}${p.INK}/login keys${p.DIM} to use your own API key instead)${p.RESET}`,
             ].filter(Boolean),
             { placement: "aboveEditor" },
           );
@@ -381,20 +393,31 @@ export default function privateerBrand(pi: any): void {
         /* provider list fetch failed — models appear on next launch */
       }
       refresh(ctx);
-      ctx?.ui?.notify?.(`Signed in as ${user.email ?? user.id}. Your Privateer models are ready.`, "info");
+      ctx?.ui?.notify?.(`Signed in as ${user.email ?? user.id}.`, "info");
+      // Arm the account channel and select the model, IN THIS SESSION. runDeviceLogin
+      // fires onSignedIn too, which does the same work — this await is what makes the
+      // outcome (and any failure) land before we hand the prompt back to the user.
+      await activateSignedInModel(ctx);
     } catch (e) {
       ctx?.ui?.setWidget?.("privateer-signin", undefined);
       ctx?.ui?.notify?.((e as Error).message || "Sign-in failed.", "error");
     }
   }
 
+  // Log out of this MACHINE — the login and every terminal spawned from it (see
+  // priv.logout). Unlike the old terminal-scoped sign-out this makes a blocking
+  // network call, so say what's happening before the round trip rather than after.
   async function doSignOut(ctx: any): Promise<void> {
     if (!priv.hasCredentials()) return ctx?.ui?.notify?.("Not signed in.", "info");
     const u = priv.currentUser();
-    await priv.logout();
+    ctx?.ui?.notify?.("Signing out of Privateer…", "info");
+    await priv.logout(); // never throws: local state is wiped whatever the network did
     dropPersistedAccount(ctx);
     refresh(ctx);
-    ctx?.ui?.notify?.(`Signed out${u?.email ? ` (${u.email})` : ""}. Drop anchor for now.`, "info");
+    ctx?.ui?.notify?.(
+      `Signed out${u?.email ? ` (${u.email})` : ""} — this machine and its terminals. Drop anchor for now.`,
+      "info",
+    );
   }
 
   function showStatus(ctx: any): void {
@@ -402,50 +425,103 @@ export default function privateerBrand(pi: any): void {
     ctx?.ui?.notify?.(
       u
         ? `Signed in to Privateer as ${u.email ?? u.id}.`
-        : "Not signed in. Run /signin to connect your Privateer account.",
+        : "Not logged in. Run /login to connect your Privateer account.",
       "info",
     );
   }
 
-  // Move the LIVE session onto a confidential model the instant the user signs in. A
-  // terminal launched with no credentials is pinned by `--model` to the keyless
-  // OpenRouter fallback; without this switch it stays there and the first prompt after
-  // sign-in dead-ends on "No API key found for openrouter". resolveSignedInModel picks
-  // Tinfoil GLM 5.2 (client-attested TEE) when a key is present, else the account's NEAR
-  // channel — private inference that works out of the box. We only override an auto-picked
-  // launch model, never a deliberate PRIVATEER_MODEL, and never re-switch if we're already
-  // on the target. The account (NEAR) credential is spawned moments AFTER sign-in fires,
-  // so setModel can briefly return false ("no key yet"); retry a few times so the switch
-  // lands as soon as the credential is ready (Tinfoil, key already in env, succeeds first
-  // try). Best-effort throughout — a failure just leaves the launch model in place.
-  async function activateSignedInModel(ctx: any): Promise<void> {
-    if (process.env.PRIVATEER_MODEL?.trim()) return; // deliberate override — respect it
-    const reg = ctx?.modelRegistry;
-    if (!reg?.find || typeof pi.setModel !== "function") return;
-    const spec = resolveSignedInModel();
-    const slash = spec.indexOf("/");
-    if (slash <= 0) return;
-    const provider = spec.slice(0, slash), id = spec.slice(slash + 1);
-    const currentSpec = ctx?.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
-    if (currentSpec === spec) return; // already there — nothing to do
-    const model = reg.find(provider, id);
-    if (!model) { dbg(`activateSignedInModel: ${spec} not in registry`); return; }
-    for (let attempt = 0; attempt < 4; attempt++) {
-      try {
-        const ok = await pi.setModel(model);
-        if (ok !== false) {
-          currentModelProvider = provider;
-          refresh(ctx);
-          ctx?.ui?.notify?.(`Now using ${spec} for private inference.`, "info");
-          dbg(`activateSignedInModel: switched to ${spec}`);
+  // Make the terminal USABLE the instant the user signs in — the whole point of
+  // logging in, and the step that used to be missing. Two halves, in this order:
+  //
+  //   1. ARM the account channel. Pi stores an OAuth credential only for a login it
+  //      drove itself, so after our own device-code /login the `privateer` provider has
+  //      no key at all. Arming first also matters for the now-common case where the
+  //      launch model ALREADY is the account model (a signed-out terminal boots on it,
+  //      see providers/defaultModel.ts): there's no switch to make, only a key to fetch,
+  //      and the old early-return skipped it and left the next prompt to fail.
+  //   2. SWITCH the live model, if we aren't already on it. A terminal that launched on
+  //      a BYO key stays on that key otherwise, so signing in appears to do nothing.
+  //
+  // resolveSignedInModel picks Tinfoil GLM 5.2 — direct (client-attested) when a Tinfoil
+  // key is present, over the subscription otherwise. A deliberate PRIVATEER_MODEL is
+  // never overridden. Idempotent: sign-in fires this twice by design (once when
+  // credentials land, once when the channel is ready), and a second run is a no-op.
+  // Best-effort — but a failure is now REPORTED, because silently leaving the user on an
+  // unusable model is exactly the bug this replaces.
+  let activating = false;
+  async function activateSignedInModel(ctx: any, opts: { switchModel?: boolean } = {}): Promise<void> {
+    if (activating || process.env.PRIVATEER_MODEL?.trim()) return; // in-flight, or a deliberate override
+    activating = true;
+    try {
+      const spec = resolveSignedInModel();
+      const slash = spec.indexOf("/");
+      if (slash <= 0) return;
+      const provider = spec.slice(0, slash), id = spec.slice(slash + 1);
+
+      // The account channel needs a live session token before any privateer/* model can
+      // run. Retry briefly: this can be racing the credential the login itself minted.
+      if (provider === "privateer") {
+        let armed = false;
+        for (let attempt = 0; attempt < 3 && !armed; attempt++) {
+          armed = await armAccountCredential(ctx, { notify: false });
+          if (!armed) await new Promise((r) => setTimeout(r, 500));
+        }
+        if (!armed) {
+          dbg("activateSignedInModel: account channel not armed");
+          ctx?.ui?.notify?.(
+            "Signed in, but this terminal couldn't open an account session. Check your connection and run /login again, or sign a terminal out in the app if you're at the device limit.",
+            "error",
+          );
           return;
         }
-      } catch (e) {
-        dbg(`activateSignedInModel: setModel threw ${(e as Error).message}`);
       }
-      await new Promise((r) => setTimeout(r, 400)); // credential still spawning — retry
+
+      // Re-running /login while already signed in arms the channel but must NOT move the
+      // user off a model they picked with /models. Only a genuine sign-in switches.
+      if (opts.switchModel === false) return;
+
+      // Already on the target — the common case now that a signed-out terminal launches
+      // on the account model. Nothing to switch, but SAY so: the channel just went live
+      // under them, and silence after a login is what made the old flow feel broken.
+      const currentSpec = ctx?.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
+      if (currentSpec === spec) {
+        dbg(`activateSignedInModel: already on ${spec}`);
+        refresh(ctx);
+        ctx?.ui?.notify?.(`${spec} is ready — private inference on your Privateer account.`, "info");
+        return;
+      }
+
+      const reg = ctx?.modelRegistry;
+      if (!reg?.find || typeof pi.setModel !== "function") return;
+      const model = reg.find(provider, id);
+      if (!model) {
+        // The provider's live catalog may still be loading (or this is the first sign-in
+        // of the run, before the account provider was registered). Say something useful
+        // rather than stranding them on a model their account can't bill.
+        dbg(`activateSignedInModel: ${spec} not in registry`);
+        ctx?.ui?.notify?.(`Signed in. Run /models to pick a model — ${spec} isn't loaded yet.`, "warning");
+        return;
+      }
+      for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+          const ok = await pi.setModel(model);
+          if (ok !== false) {
+            currentModelProvider = provider;
+            refresh(ctx);
+            ctx?.ui?.notify?.(`Now using ${spec} — private inference on your Privateer account.`, "info");
+            dbg(`activateSignedInModel: switched to ${spec}`);
+            return;
+          }
+        } catch (e) {
+          dbg(`activateSignedInModel: setModel threw ${(e as Error).message}`);
+        }
+        await new Promise((r) => setTimeout(r, 400)); // registry still settling — retry
+      }
+      dbg(`activateSignedInModel: gave up switching to ${spec}`);
+      ctx?.ui?.notify?.(`Signed in, but couldn't switch to ${spec}. Run /models to pick one.`, "warning");
+    } finally {
+      activating = false;
     }
-    dbg(`activateSignedInModel: gave up switching to ${spec}`);
   }
 
   dbg("extension loaded, onSignedIn listener registering");
@@ -529,27 +605,38 @@ export default function privateerBrand(pi: any): void {
     // that's now dead server-side (see dropPersistedAccount).
     dropPersistedAccount(ctxRef);
     refresh(ctxRef);
-    ctxRef?.ui?.notify?.("Your Privateer session expired. Run /signin to sign back in.", "warning");
+    ctxRef?.ui?.notify?.("Your Privateer session expired. Run /login to sign back in.", "warning");
   });
 
   pi.registerCommand?.("update", {
     description: "Update Privateer to the latest release (npm i -g privateer-agent@latest)",
     handler: (_args: string, ctx: any) => doUpdate(ctx),
   });
-  pi.registerCommand?.("signin", {
-    description: "Sign in to your Privateer account (device-code flow)",
+  // ONE vocabulary: log in / log out. Pi's own built-ins are /login and /logout, so
+  // matching them is what makes the pair feel like a single concept instead of two
+  // half-overlapping ones (Pi's /logout used to clear only Pi's authStorage while the
+  // machine login lived on, which read as "logout doesn't work"). /logout here is the
+  // canonical command; the Pi built-in is redirected to it by patches/, the same
+  // mechanism as the /model → /models redirect.
+  //
+  // signin/signout stay registered as undocumented aliases — they were the shipped
+  // names, they're in muscle memory and in older docs, and an alias costs nothing.
+  pi.registerCommand?.("login", {
+    description: "Log in to your Privateer account · /login keys for a provider API key",
     handler: (_args: string, ctx: any) => doSignIn(ctx),
   });
-  pi.registerCommand?.("signout", {
-    description: "Sign out of your Privateer account on this terminal",
+  pi.registerCommand?.("logout", {
+    description: "Log out of Privateer on this machine (revokes all its terminals)",
     handler: (_args: string, ctx: any) => doSignOut(ctx),
   });
+  pi.registerCommand?.("signin", { description: "", handler: (_a: string, ctx: any) => doSignIn(ctx) });
+  pi.registerCommand?.("signout", { description: "", handler: (_a: string, ctx: any) => doSignOut(ctx) });
   pi.registerCommand?.("privateer", {
-    description: "Privateer account: /privateer [status | signin | signout]",
+    description: "Privateer account: /privateer [status | login | logout]",
     handler: (args: string, ctx: any) => {
       const sub = String(args ?? "").trim().toLowerCase().split(/\s+/)[0];
-      if (sub === "signin" || sub === "login") return doSignIn(ctx);
-      if (sub === "signout" || sub === "logout") return doSignOut(ctx);
+      if (sub === "login" || sub === "signin") return doSignIn(ctx);
+      if (sub === "logout" || sub === "signout") return doSignOut(ctx);
       return showStatus(ctx);
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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/patches/@earendil-works+pi-coding-agent+0.80.3.patch

@@ -1,8 +1,23 @@
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-index e223ce1..2bdab10 100644
+index e223ce1..3615d74 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-@@ -711,6 +711,15 @@ export class AgentSession {
+@@ -163,6 +163,14 @@ export class AgentSession {
+         }
+         const isOAuth = this._modelRegistry.isUsingOAuth(model);
+         if (isOAuth) {
++            // Privateer patch: the account channel has no API key that could expire —
++            // the terminal is simply not signed in yet (a fresh install now boots on
++            // `privateer/*`, which is the model it will run once logged in). Stock Pi's
++            // wording describes a state that user was never in, and its "/login
++            // privateer" bypasses the branded sign-in. auth-guidance owns the words.
++            if (model.provider === "privateer") {
++                throw new Error(formatNoApiKeyFoundMessage(model.provider));
++            }
+             throw new Error(`Authentication failed for "${model.provider}". ` +
+                 `Credentials may have expired or network is unavailable. ` +
+                 `Run '/login ${model.provider}' to re-authenticate.`);
+@@ -711,6 +719,15 @@ export class AgentSession {
                  finalError: msg.errorMessage,
              });
              this._retryAttempt = 0;
@@ -18,8 +33,52 @@ index e223ce1..2bdab10 100644
          }
          if (await this._checkCompaction(msg)) {
              return true;
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
+index 197bccc..27f6429 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
+@@ -1,21 +1,33 @@
+ import { join } from "node:path";
+ import { getDocsPath } from "../config.js";
+ const UNKNOWN_PROVIDER = "unknown";
++// Privateer patch: speak Privateer, and stop printing absolute node_modules doc paths.
++//
++// Stock Pi answered every auth failure with four lines, two of them full paths into
++// node_modules/@earendil-works/pi-coding-agent/docs/. On a terminal that isn't signed
++// in, that wall repeats on every prompt and buries the one sentence that matters. It
++// also told a Privateer user to go find a provider API key when their subscription
++// already covers the model. Same information, one actionable line.
+ export function getProviderLoginHelp() {
+-    return [
+-        "Use /login to log into a provider via OAuth or API key. See:",
+-        `  ${join(getDocsPath(), "providers.md")}`,
+-        `  ${join(getDocsPath(), "models.md")}`,
+-    ].join("\n");
++    return "Run /login to connect your Privateer account, or /login keys to use your own provider API key.";
+ }
+ export function formatNoModelsAvailableMessage() {
+     return `No models available. ${getProviderLoginHelp()}`;
+ }
+ export function formatNoModelSelectedMessage() {
+-    return `No model selected.\n\n${getProviderLoginHelp()}\n\nThen use /model to select a model.`;
++    return `No model selected. ${getProviderLoginHelp()}\n\nThen use /models to select a model.`;
+ }
+ export function formatNoApiKeyFoundMessage(provider) {
++    // The account channel: there is no API key to find — you're just not signed in (or
++    // the session didn't arm). Naming the real problem is the whole fix here.
++    if (provider === "privateer") {
++        return "This terminal isn't signed in to Privateer, so it can't run your subscription models.\n\nRun /login — it takes one approval in the Privateer app, and no API key.";
++    }
+     const providerDisplay = provider === UNKNOWN_PROVIDER ? "the selected model" : provider;
+     return `No API key found for ${providerDisplay}.\n\n${getProviderLoginHelp()}`;
+ }
++// Kept so the module's imports stay meaningful for anything that still wants the docs.
++export function getProviderDocsPaths() {
++    return [join(getDocsPath(), "providers.md"), join(getDocsPath(), "models.md")];
++}
+ //# sourceMappingURL=auth-guidance.js.map
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index 5d65200..a997ad7 100644
+index 5d65200..fef6005 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 @@ -2042,7 +2042,17 @@ export class InteractiveMode {
@@ -41,3 +100,51 @@ index 5d65200..a997ad7 100644
                  return;
              }
              if (text === "/export" || text.startsWith("/export ")) {
+@@ -2105,14 +2115,44 @@ export class InteractiveMode {
+                 this.editor.setText("");
+                 return;
+             }
+-            if (text === "/login") {
+-                this.showOAuthSelector("login");
++            if (text === "/login" || text.startsWith("/login ")) {
+                 this.editor.setText("");
++                // Privateer redirect: a bare /login IS the account sign-in. Pi's built-in
++                // opens a two-step menu ("Use a subscription" → a list of 20+ providers)
++                // that buries the one option a Privateer user wants, and — because it
++                // only auto-selects a model when the current one is UNKNOWN — a
++                // successful login through it left the terminal on its launch model and
++                // the next prompt died on "No API key found". The extension's own flow
++                // signs in, arms the account channel, and selects the model.
++                // `/login <anything>` (documented as `/login keys`) still opens Pi's own
++                // selector, so BYO provider keys stay reachable; and if the extension
++                // isn't loaded we fall back to Pi's selector for both.
++                if (text === "/login" && this.isExtensionCommand("/privateer")) {
++                    await this.session.prompt("/privateer login");
++                }
++                else {
++                    this.showOAuthSelector("login");
++                }
+                 return;
+             }
+             if (text === "/logout") {
+-                this.showOAuthSelector("logout");
+                 this.editor.setText("");
++                // Privateer redirect: /logout must actually log you out. Pi's built-in
++                // only clears Pi's authStorage, which leaves the Privateer machine
++                // login in ~/.privateer/credentials.json untouched — so on a signed-in
++                // machine it reported "No stored credentials to remove" and changed
++                // nothing. Route to the account logout instead, which revokes this
++                // machine's whole token family (login + every terminal spawned from it)
++                // and wipes local state. Target is `/privateer logout` rather than the
++                // extension's own `/logout` so this can never re-enter the branch it
++                // was dispatched from. Falls back to Pi's selector when the extension
++                // isn't loaded.
++                if (this.isExtensionCommand("/privateer")) {
++                    await this.session.prompt("/privateer logout");
++                }
++                else {
++                    this.showOAuthSelector("logout");
++                }
+                 return;
+             }
+             if (text === "/new") {

package/src/auth/accountSessions.ts

@@ -0,0 +1,157 @@
+// 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);
+}
+
+// Wipe the registry. Used by logout(), where the server has just revoked this
+// machine's whole token family: every entry now names a dead session, and leaving
+// them behind would offer the next login a list of orphans to "reclaim" that can
+// only fail. Also a test seam.
+export function clearOwnedSessions(): void {
+  try {
+    rmSync(accountSessionsPath(), { force: true });
+  } catch {
+    /* nothing to remove */
+  }
+}