privateer-agent 0.6.4 → 0.6.7

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/hosted.ts

@@ -1,3 +1,8 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "./paths.ts";
+import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
+
 // Harbor hosted mode.
 //
 // When true, this daemon is running inside Privateer's confidential-VM fleet
@@ -11,3 +16,34 @@
 export function isHosted(): boolean {
   return process.env.HARBOR_HOSTED === "1";
 }
+
+/**
+ * Publish this daemon's relay identity key so the Harbor host can attest it.
+ *
+ * ATTESTATION CONTRACT (host side: treeview `server/services/harborOrchestrator/`):
+ * the orchestrator mints the SEV-SNP report on the CVM host — configfs-tsm is a
+ * privileged kernel interface a rootless tenant deliberately cannot reach — and binds
+ * `report_data[0:32] = sha256(DER-SPKI(terminalPub))`. To do that it needs OUR public
+ * key, so we drop it in `$PRIVATEER_HOME` (bind-mounted from host tmpfs) as the mirror
+ * of the `routines/relay-id` file the host seeds for us.
+ *
+ * It must be the key the app ACTUALLY drives over the relay — the same value we send
+ * in sendContext({ terminalPub }) — otherwise the app's fail-closed check reports a
+ * key mismatch. Base64 of the raw 32 X25519 bytes; the host wraps it in the SPKI DER
+ * prefix itself. Minting happens on first call, which is fine: this runs at boot,
+ * before the relay registers.
+ *
+ * Hosted-only and best-effort: on a user's own machine this is a no-op, and a write
+ * failure must never take the daemon down — attestation simply fail-closes host-side
+ * with HARBOR_ATTEST_NO_KEY rather than reporting a false "attested".
+ */
+export function publishRelayPub(): void {
+  if (!isHosted()) return;
+  try {
+    writeFileSync(join(globalDir(), "relay-pub"), terminalPublicKeyBase64(), { mode: 0o600 });
+  } catch (err) {
+    console.error(
+      `[harbor] could not publish relay-pub — enclave attestation will fail closed: ${String(err)}`,
+    );
+  }
+}

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

@@ -20,6 +20,7 @@ import { RelayClient, type TaskSpec } from "../remote/relayClient.ts";
 import { createLiveTaskSession, type LiveTaskHandle } from "../remote/liveTaskSession.ts";
 import { makeRoutinesControl } from "../remote/routinesControl.ts";
 import { makeChannelsControl } from "../remote/channelsControl.ts";
+import { makeMcpControl } from "../remote/mcpControl.ts";
 import { makeWorkflowsControl } from "../remote/workflowsControl.ts";
 import { runWorkflow as executeWorkflow, type RunnerDeps, type AgentRunSpec, type AgentRunResult, type ScriptRunResult } from "../workflows/runner.ts";
 import type { Workflow, Step } from "../workflows/schema.ts";
@@ -29,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,
@@ -50,7 +51,7 @@ import { deliver, type RelayPusher, type CloudPusher } from "../routines/deliver
 import { sealJson, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, type IpcRequest, type IpcResponse } from "./ipc.ts";
-import { isHosted } from "../config/hosted.ts";
+import { isHosted, publishRelayPub } from "../config/hosted.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
 // write/edit/bash, so a routine firing with nobody watching can't mutate the
@@ -190,6 +191,13 @@ export class Daemon {
     runningPlatforms: () => readRunningPlatforms(),
   });
 
+  // App-facing MCP connector management (list/save/set_enabled/remove) over the
+  // daemon's relay — the daemon is the Node HOST that actually runs the adapter (a
+  // phone/web client can't). Edits the SHARED agent/mcp-desktop.json + mcp.json, so a
+  // machine has one MCP config whether it was set from the desktop (IPC) or the phone
+  // (relay). Tokens ride in a SEALED box (applyMcpSave) — the relay never sees them.
+  private readonly mcp = makeMcpControl();
+
   // App-facing workflow management (list/get/save/remove/run) over the daemon's relay.
   // Run-now is injected here since only the daemon owns the runner + its seams. A
   // workflow can carry a `script` step (RCE if forged), so every mutation is
@@ -219,6 +227,9 @@ export class Daemon {
   };
 
   start(): void {
+    // Hosted only: publish our relay pubkey for the host to bind into the SEV-SNP
+    // report. Before syncRelay() so the key exists by the time we're reachable.
+    publishRelayPub();
     this.primeSchedule();
     this.timer = setInterval(() => void this.tick(), TICK_MS);
     this.server = startIpcServer((req) => this.handleIpc(req));
@@ -287,6 +298,14 @@ export class Daemon {
         onChannelsList: () => this.pushChannels(),
         onChannelsSave: (draft, sealedSecrets, sig, ts) => this.pushChannels(this.applyChannelSave(draft, sealedSecrets, sig, ts)),
         onChannelsRemove: (platform, sig, ts) => this.pushChannels(this.guardControl("channels_remove", { platform }, sig, ts, () => this.channels.remove(platform as any).message)),
+        // MCP connector management from the app. `save` has its own signed verify (it
+        // carries a sealed env box — applyMcpSave); `set_enabled`/`remove` are
+        // account-signed here (H2 — a forged toggle arms/disarms a tool surface; a
+        // forged removal is a DoS). Then mcpControl writes the shared config + re-pushes.
+        onMcpList: () => this.pushMcp(),
+        onMcpSave: (draft, sealedSecrets, sig, ts) => this.pushMcp(this.applyMcpSave(draft, sealedSecrets, sig, ts)),
+        onMcpSetEnabled: (name, enabled, sig, ts) => this.pushMcp(this.guardControl("mcp_set_enabled", { name, enabled }, sig, ts, () => this.mcp.setEnabled(name, enabled).message)),
+        onMcpRemove: (name, sig, ts) => this.pushMcp(this.guardControl("mcp_remove", { name }, sig, ts, () => this.mcp.remove(name).message)),
         // Workflow management from the app. Each MUTATION is account-signed (H2) — a forged
         // workflows_save plants a `script` step that bypasses the permission gate (RCE),
         // and workflows_run executes the graph — so all three are verified (guardControl,
@@ -340,6 +359,42 @@ export class Daemon {
     this.relay?.sendChannels({ items: this.channels.list(), message });
   }
 
+  private pushMcp(message?: string): void {
+    this.relay?.sendMcp({ items: this.mcp.list(), message });
+  }
+
+  // Verify an account-signed MCP save (H2) that also carries a SEALED env box, then
+  // apply it. Same shape as applyChannelSave but routed through the generic signed
+  // envelope (action "mcp_save", args {draft, sealedSecrets}) — the action tag stops a
+  // signature made for any other frame from being replayed as an MCP save. Fail-closed:
+  // an unsigned/forged/stale frame returns the refusal message and NOTHING is written.
+  // The sealed box opens to { termId, env } — a token the relay never sees in the clear.
+  private applyMcpSave(draft: Record<string, unknown>, sealedSecrets?: string, sig?: string, ts?: number): string | undefined {
+    const auth = authorizeControl(
+      routineRelayId(),
+      "mcp_save",
+      { draft, sealedSecrets: sealedSecrets ?? null },
+      sig,
+      ts,
+    );
+    if (!auth.ok) return auth.message;
+
+    let withEnv = draft;
+    if (sealedSecrets) {
+      let opened: { termId?: string; env?: Record<string, string> };
+      try {
+        opened = openJsonFromApp(sealedSecrets);
+      } catch {
+        return "Couldn't decrypt the connector credentials — they may have been sealed to a different terminal.";
+      }
+      if (opened.termId !== routineRelayId()) {
+        return "These credentials were addressed to a different terminal.";
+      }
+      withEnv = { ...draft, env: opened.env ?? {} };
+    }
+    return this.mcp.save(withEnv as any).message;
+  }
+
   // Push the current workflow summaries to an attached controller (its workflows
   // manager). `message` is a one-line result from the last mutation, if any.
   private pushWorkflows(message?: string): void {
@@ -600,9 +655,14 @@ export class Daemon {
     const config = loadDaemonConfig();
     const modelSpec = routine.model ?? config.defaultModel;
     const split = splitRoutineTools(routine.tools);
-    const allowedTools = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
-    if (split.mcp.length > 0 || routine.delivery.includes("email")) {
-      log("  note: MCP tools + email delivery are not wired yet (Phase 5) — skipping those");
+    // MCP tools (server__tool) join the allow-list: the mcpAdapter loaded in runSession
+    // registers them from the shared mcp.json, and the routine's SIGNED tool list is the
+    // authorization boundary under the bypass gate (same as builtin tools). An http/OAuth
+    // connector that never completed its browser flow simply errors at call time.
+    const builtinAllow = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const allowedTools = [...builtinAllow, ...split.mcp];
+    if (routine.delivery.includes("email")) {
+      log("  note: email delivery is not wired yet (Phase 5) — skipping it");
     }
 
     const { out, status, error } = await this.runSession({
@@ -655,11 +715,19 @@ export class Daemon {
           return "deny";
         },
       };
+      // MCP adapter (Phase 5): registers the tools from the shared agent/mcp.json — the
+      // same projection the app's MCP manager (mcpControl) writes over the relay. No
+      // servers configured → a no-op. Dynamically imported so it loads only when a
+      // session actually runs (Pi is already booted by here). The specifier is a
+      // variable so tsc treats it as Promise<any> and doesn't pull the third-party
+      // adapter's own .ts into our typecheck — same intent as the desktop's agentImport.
+      const mcpAdapterSpec = "pi-mcp-adapter";
+      const { default: mcpAdapter } = await import(mcpAdapterSpec);
       const services = await createAgentSessionServices({
         cwd: spec.cwd,
         agentDir: agentDir(),
         resourceLoaderOptions: {
-          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider(), mcpAdapter] as any,
         },
       });
       servicesRef = services as any;
@@ -667,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) {
@@ -724,7 +792,7 @@ export class Daemon {
     const cwd = spec.cwd && spec.cwd.trim() ? spec.cwd : process.cwd();
     const modelSpec = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
-    const allowedTools = split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const allowedTools = [...(split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS), ...(split?.mcp ?? [])];
     const title = deriveTaskTitle(spec);
     const key = `task:${title}`;
     if (this.running.has(key)) {
@@ -904,7 +972,7 @@ export class Daemon {
     const config = loadDaemonConfig();
     const model = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
-    const tools = split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const tools = [...(split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS), ...(split?.mcp ?? [])];
     const { out, status, error } = await this.runSession({ prompt: spec.prompt, cwd: spec.cwd, model, tools });
     let output: Record<string, unknown> = {};
     try { const p = JSON.parse(out.trim()); if (p && typeof p === "object" && !Array.isArray(p)) output = p as Record<string, unknown>; } catch { /* non-JSON → raw text only */ }