privateer-agent 0.12.58 → 0.14.0

package/src/harbor/accountLease.ts

@@ -0,0 +1,76 @@
+// One account inference session for the whole harbor, shared by every run in flight.
+//
+// The account credential is a single slot per process — `_account` in auth/privateer.ts,
+// one row per pid in accountSessions.ts, one `privateer` entry in auth.json — but the
+// harbor runs several sessions at once: overlapping ticks, a submitted task, a workflow
+// step and a live spawn can all be mid-turn together. Each used to mint its own session
+// on start and revoke "the" session on finish, so the first run to finish revoked
+// whichever session was minted LAST (another run's, mid-turn → 401) and its own leaked
+// server-side until the TTL, with its registry row overwritten so no later launch could
+// reclaim it.
+//
+// A lease fits what the slot can actually hold: the first run to need the account mints
+// it, later runs share it, and the last one out revokes it. Pure — the mint and revoke
+// are injected — so the ordering is testable without a server.
+
+export interface AccountLeaseDeps {
+  /** Mint the account session and arm it (persist + remember). Throws on failure. */
+  mint: () => Promise<void>;
+  /** Revoke the session and drop its persisted copy. Best-effort; must not throw. */
+  revoke: () => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+export interface AccountLease {
+  /** Take a reference. Resolves true when the account session is armed. ALWAYS pair with release(). */
+  acquire(): Promise<boolean>;
+  /** Drop a reference; the last one out revokes the session. */
+  release(): Promise<void>;
+  /** References held right now (tests, status). */
+  readonly refs: number;
+}
+
+export function createAccountLease(deps: AccountLeaseDeps): AccountLease {
+  let refs = 0;
+  // The session the current holders share: resolves true once armed, false if the mint
+  // failed. Undefined when nobody holds one.
+  let current: Promise<boolean> | undefined;
+  // The previous session's revoke. A mint waits on it, so a run that starts as the last
+  // one ends never has its fresh credential dropped by the old one's teardown.
+  let teardown: Promise<void> = Promise.resolve();
+
+  return {
+    get refs() {
+      return refs;
+    },
+    async acquire() {
+      refs++;
+      if (!current) {
+        current = teardown.then(deps.mint).then(
+          () => true,
+          (e) => {
+            deps.log?.(`  account channel unavailable: ${e instanceof Error ? e.message : String(e)}`);
+            return false;
+          },
+        );
+      }
+      const mine = current;
+      const ok = await mine;
+      // A failed mint is not cached: the next run should try again rather than inherit it.
+      if (!ok && current === mine) current = undefined;
+      return ok;
+    },
+    async release() {
+      if (refs === 0) return;
+      refs--;
+      if (refs > 0) return;
+      const held = current;
+      current = undefined;
+      if (!held) return;
+      teardown = teardown.then(async () => {
+        if (await held) await deps.revoke().catch(() => {});
+      });
+      await teardown;
+    },
+  };
+}

package/src/harbor/closeSession.ts

@@ -0,0 +1,20 @@
+// Tear a headless session all the way down. dispose() alone stops the agent but never
+// emits session_shutdown — that is AgentSessionRuntime's job, and we build sessions
+// without one — so every extension that cleans up on it (pi-mcp-adapter's connections,
+// OAuth runtime and lifecycle state among them) leaked once per run, for the life of a
+// resident process. Reason "new", not "quit": to our own extensions "quit" means the
+// PROCESS is exiting (privateer-brand revokes the machine's sessions on it), and the
+// harbor process lives on. Best-effort: teardown must never fail a finished run.
+export async function closeSession(session: any): Promise<void> {
+  try {
+    const runner = session?.extensionRunner;
+    if (runner?.hasHandlers?.("session_shutdown")) await runner.emit({ type: "session_shutdown", reason: "new" });
+  } catch {
+    /* a handler threw — dispose anyway */
+  }
+  try {
+    session?.dispose?.();
+  } catch {
+    /* already disposed */
+  }
+}

package/src/harbor/index.ts

@@ -64,6 +64,8 @@ import { postOutbox as sealToOutbox, type OutboxSource } from "../outbox/cloudOu
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
 import { serializeBuild } from "./buildLock.ts";
+import { createAccountLease } from "./accountLease.ts";
+import { closeSession } from "./closeSession.ts";
 import { isHosted, publishRelayPub, webEnabled, mediaEnabled } from "../config/hosted.ts";
 import { relayExposureAllowed } from "../config/relayExposure.ts";
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
@@ -134,6 +136,11 @@ const GATE_TIMEOUT_MS = 5 * 60_000;
 // endpoint or an expired OAuth token from stalling a scheduled run.
 const WARM_TIMEOUT_MS = Number(process.env.PRIVATEER_MCP_WARM_MS) || 30_000;
 const WARM_POLL_MS = 250;
+// Hard ceiling on one unattended run (a routine, a submitted task, a workflow agent
+// step). Nothing else bounds a provider stream that stops sending without closing, and a
+// run stuck there holds its routine's `running` slot until the harbor restarts — the
+// routine silently never fires again. Live spawns have their own cap (liveTaskSession).
+const RUN_TIMEOUT_MS = Number(process.env.PRIVATEER_RUN_TIMEOUT_MS) || 30 * 60_000;
 
 // Distinguishes concurrent runs in the child-spend registry. A counter rather than a
 // timestamp: two runs starting in the same millisecond would share a key, and the second
@@ -177,6 +184,12 @@ function log(msg: string): void {
   process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
 }
 
+// Identity of a queued outbox item, for removing the ones a flush delivered from a
+// queue that may have grown while it was posting.
+function pendingKey(p: PendingCloud): string {
+  return JSON.stringify([p.routine, p.at, p.kind ?? "routine", p.status, p.content]);
+}
+
 // Connector notes are things the RUN could not do — a selected connector that isn't
 // configured, or one that wouldn't hand over a tool list. They ride the result
 // because the alternative is the failure mode RoutineIssues exists to prevent: an
@@ -271,6 +284,25 @@ export class Harbor {
   // Live, app-drivable sessions spawned on demand (task_spawn). Each has its OWN relay
   // terminal (task-<uuid>); the harbor just keeps handles so it can reap them on shutdown.
   private readonly liveTasks = new Map<string, LiveTaskHandle>();
+  // The one account inference session every concurrent run shares — see accountLease.ts.
+  private readonly account = createAccountLease({
+    mint: async () => {
+      const creds = await acquireAccountCredential();
+      await persistAccountCredential(creds);
+      rememberAccountCredential(creds); // claim it, so the teardown drops OUR entry only
+    },
+    revoke: async () => {
+      try { await revokeAccountSession(); } catch { /* best effort — server TTL is the fallback */ }
+      // Ownership-checked: an interactive terminal on this machine shares auth.json,
+      // and its entry must survive a harbor run's teardown (see providers/account.ts).
+      try { await dropPersistedAccountCredential(); } catch { /* nothing persisted */ }
+    },
+    log,
+  });
+  // The cloud-outbox flush in progress, if any. Every tick starts one; without this two
+  // could post the same items (duplicates in the Inbox) and the slower one's save would
+  // overwrite what the faster one left.
+  private flushing?: Promise<void>;
 
   // App-facing routine management (list/save/delete/pause/run) over the harbor's
   // relay. Run-now is injected here since only the harbor can actually fire one;
@@ -633,22 +665,33 @@ export class Harbor {
     return sealToOutbox(name, at, status, content, kind, media, source);
   }
 
-  private async flushPendingCloud(): Promise<void> {
+  private flushPendingCloud(): Promise<void> {
+    this.flushing ??= this.doFlushPendingCloud()
+      .catch((e) => log(`outbox flush failed: ${e instanceof Error ? e.message : String(e)}`))
+      .finally(() => {
+        this.flushing = undefined;
+      });
+    return this.flushing;
+  }
+
+  private async doFlushPendingCloud(): Promise<void> {
     if (!hasCredentials()) return;
     const queue = loadPendingCloud();
     if (queue.length === 0) return;
-    const remaining: PendingCloud[] = [];
+    const sent = new Set<string>();
     for (const p of queue) {
-      if (
-        remaining.length === 0 &&
-        (await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? [], p.source))
-      ) continue;
-      remaining.push(p);
-    }
-    if (remaining.length !== queue.length) {
-      savePendingCloud(remaining);
-      log(`flushed ${queue.length - remaining.length} pending cloud outbox item(s); ${remaining.length} remaining`);
+      // Stop at the first failure: order is preserved, and whatever broke this one
+      // (offline, no outbox key yet) will break the rest too.
+      if (!(await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? [], p.source))) break;
+      sent.add(pendingKey(p));
     }
+    if (sent.size === 0) return;
+    // Re-read rather than save what we loaded: a run that finished while we were
+    // posting queued its result in the meantime, and overwriting with our snapshot
+    // would delete it.
+    const remaining = loadPendingCloud().filter((p) => !sent.has(pendingKey(p)));
+    savePendingCloud(remaining);
+    log(`flushed ${sent.size} pending cloud outbox item(s); ${remaining.length} remaining`);
   }
 
   private primeSchedule(): void {
@@ -778,32 +821,56 @@ export class Harbor {
     const toInbox = routine.delivery.includes("cloud");
     const media = toInbox ? new ResultMedia() : undefined;
 
-    const { out, status, error, notes } = await this.runSession({
-      prompt: withBrief(routine.prompt, { inbox: toInbox, canAttach: !!media }),
-      cwd: routine.cwd,
-      model: modelSpec,
-      tools: routine.tools ?? [],
-      media,
-    });
-
-    const content = formatResult(routine, out, status, error, notes);
-    const report = await deliver(routine, content, status, {
-      media: media?.list() ?? [],
-      pushRelay: this.pushRelay,
-      pushCloud: this.pushCloud,
-      webhooks: config.webhooks,
-      redact: (text) => redactText(text, collectSecrets(config.providers)),
-    });
-    log(`  "${routine.name}" ${status}; delivered via ${report.delivered.join(", ") || "(none)"}`);
+    let status: "ok" | "error" = "error";
+    let error: string | undefined;
+    let delivered: string[] = [];
+    try {
+      const run = await this.runSession({
+        prompt: withBrief(routine.prompt, { inbox: toInbox, canAttach: !!media }),
+        cwd: routine.cwd,
+        model: modelSpec,
+        tools: routine.tools ?? [],
+        media,
+      });
+      ({ status, error } = run);
 
-    this.persistRun(routine.id, {
-      lastRun: new Date().toISOString(),
-      lastStatus: status,
-      lastError: error,
-      ...advanceAfterRun(routine),
-    });
-    this.running.delete(routine.id);
-    return { ok: status === "ok", message: report.delivered.join(", ") || undefined };
+      const content = formatResult(routine, run.out, status, error, run.notes);
+      try {
+        const report = await deliver(routine, content, status, {
+          media: media?.list() ?? [],
+          pushRelay: this.pushRelay,
+          pushCloud: this.pushCloud,
+          webhooks: config.webhooks,
+          redact: (text) => redactText(text, collectSecrets(config.providers)),
+        });
+        delivered = report.delivered;
+      } catch (e) {
+        // A full disk, an unwritable output dir. The run happened and was paid for; say
+        // so in the log and on the routine rather than throwing past the schedule
+        // advance below — that throw is what used to re-fire (and re-bill) the routine
+        // on every restart.
+        error = `delivery failed: ${e instanceof Error ? e.message : String(e)}`;
+        status = "error";
+      }
+      log(`  "${routine.name}" ${status}; delivered via ${delivered.join(", ") || "(none)"}${error && delivered.length === 0 ? ` (${error})` : ""}`);
+    } finally {
+      // Always advance the schedule and free the slot, whatever threw above. Without the
+      // finally, one exception left the routine marked running forever (it never fired
+      // again) — or, as an unhandled rejection, crashed the harbor before nextRun moved,
+      // so the restart fired it again straight away.
+      try {
+        this.persistRun(routine.id, {
+          lastRun: new Date().toISOString(),
+          lastStatus: status,
+          lastError: error,
+          ...advanceAfterRun(routine),
+        });
+      } catch (e) {
+        log(`  couldn't record the run of "${routine.name}": ${e instanceof Error ? e.message : String(e)}`);
+      }
+      this.running.delete(routine.id);
+    }
+    return { ok: status === "ok", message: delivered.join(", ") || undefined };
   }
 
   // Build the Pi services for one unattended run: the auto-approve gate, the account
@@ -831,6 +898,11 @@ export class Harbor {
         allowedOutsideRoots: [],
         cwd,
         confineToCwd: true,
+        // Bypass mode lets anything through that the allow-list registered — including
+        // reads outside cwd and of protected files, which bypass allows outright. A run
+        // nobody is watching, that may well have fetched a hostile web page, must not
+        // read ~/.ssh or our own auth.json and put it in the next URL: refuse both.
+        hardConfine: true,
         async localAsk() {
           return "deny";
         },
@@ -954,7 +1026,7 @@ export class Harbor {
           await new Promise((r) => setTimeout(r, WARM_POLL_MS));
         }
       } finally {
-        session.dispose?.();
+        await closeSession(session);
       }
     } catch (e) {
       log(`  connector warm-up failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -977,7 +1049,8 @@ export class Harbor {
     let out = "";
     let status: "ok" | "error" = "ok";
     let error: string | undefined;
-    let spawnedAccount = false;
+    let leasedAccount = false;
+    let session: any;
     const resolved = await this.resolveRunTools(spec.tools, spec.cwd, spec.model);
     // attach_to_result rides with the staging area rather than the allow-list: it is
     // how the answer is DELIVERED, not a capability the run gains. A routine that
@@ -997,14 +1070,10 @@ export class Harbor {
 
       const { provider, modelId } = parseSpec(spec.model);
       if (provider === "privateer") {
-        try {
-          const creds = await acquireAccountCredential();
-          await persistAccountCredential(creds);
-          rememberAccountCredential(creds); // claim it, so the teardown drops OUR entry only
-          spawnedAccount = true;
-        } catch (e) {
-          log(`  account channel unavailable: ${(e as Error).message}`);
-        }
+        // Shared with every other run in flight — see accountLease.ts. A failed mint is
+        // logged by the lease; the run goes ahead and fails on auth with that context.
+        leasedAccount = true;
+        await this.account.acquire();
       }
 
       const model = (modelRegistryOf(services) as any).find(provider, modelId);
@@ -1012,12 +1081,12 @@ export class Harbor {
         status = "error";
         error = `model ${provider}/${modelId} not found`;
       } else {
-        const { session } = await createAgentSessionFromServices({
+        ({ session } = await createAgentSessionFromServices({
           services,
           sessionManager: SessionManager.inMemory(spec.cwd),
           model,
           tools: allowedTools,
-        } as any);
+        } as any));
         const adapter = createEngineEventAdapter();
         session.subscribe((ev: any) => {
           for (const ee of adapter.toEngineEvents(ev)) {
@@ -1028,21 +1097,30 @@ export class Harbor {
             }
           }
         });
-        await session.prompt(spec.prompt);
+        let timedOut = false;
+        const deadline = setTimeout(() => {
+          timedOut = true;
+          void Promise.resolve(session.abort?.()).catch(() => {});
+        }, RUN_TIMEOUT_MS);
+        try {
+          await session.prompt(spec.prompt);
+        } finally {
+          clearTimeout(deadline);
+        }
+        if (timedOut) {
+          status = "error";
+          error = `run stopped after ${Math.round(RUN_TIMEOUT_MS / 60_000)} minutes (PRIVATEER_RUN_TIMEOUT_MS)`;
+        }
       }
     } catch (err) {
       status = "error";
       error = err instanceof Error ? err.message : String(err);
     } finally {
-      // Revoke ONLY this run's account inference session (the harbor's own child API
-      // session — relay/outbox — stays alive until shutdown). Drop Pi's persisted copy
-      // too so a later run's fallback never reuses a revoked token. Best-effort.
-      if (spawnedAccount) {
-        try { await revokeAccountSession(); } catch { /* best effort — server TTL is the fallback */ }
-        // Ownership-checked: an interactive terminal on this machine shares auth.json,
-        // and its entry must survive a harbor run's teardown (see providers/account.ts).
-        try { await dropPersistedAccountCredential(); } catch { /* nothing persisted */ }
-      }
+      if (session) await closeSession(session);
+      // Drop this run's reference to the shared account session; the last run out
+      // revokes it (and its persisted copy). The harbor's own child API session —
+      // relay/outbox — is separate and stays alive until shutdown.
+      if (leasedAccount) await this.account.release();
       // Drop this run's child grant. Unconditional and last: a grant left behind would
       // authorize the NEXT run's subagents for tools that run never named.
       releaseChildSpend();
@@ -1108,6 +1186,7 @@ export class Harbor {
           defaultModel: loadHarborConfig().defaultModel,
           parseSpec,
           log,
+          account: this.account,
           onClosed: (id) => this.liveTasks.delete(id),
           // A live spawn's feed lives only in the attached app; when the session ends
           // (closed, reaped, or timed out) its answer would otherwise be gone. Seal the
@@ -1401,6 +1480,12 @@ export function runHarbor(): void {
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
+  // A resident service: one stray rejection from a fire-and-forget promise (a relay
+  // callback, a run started from IPC) must not take every routine down with it — and,
+  // under launchd/systemd, restart into the same state and do it again. Log it instead.
+  process.on("unhandledRejection", (reason) => {
+    log(`unhandled rejection: ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`);
+  });
   harbor.start().catch(async (err) => {
     if (err instanceof HarborAlreadyRunningError) {
       // A resident harbor already owns this machine — leave it in charge. Exit 0 so a

package/src/permissions/classify.ts

@@ -2,7 +2,7 @@ import { resolve, isAbsolute, relative, dirname, join, basename } from "node:pat
 import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { isProtectedPath } from "./protected.ts";
+import { isProtectedPath, isCredentialStorePath } from "./protected.ts";
 import type { PermissionRequest } from "./gate.ts";
 
 // NEW glue for the Pi rewrite. In 0.2 each tool built its own PermissionRequest
@@ -19,6 +19,11 @@ export interface ScopeOptions {
   cwd: string;
   confineToCwd?: boolean; // default true
   allowedOutsideRoots?: string[];
+  // Gate a READ of a protected file or credential store (isCredentialStorePath) even
+  // inside cwd, flagged `protected`. Off by default — an interactive session reading
+  // its own project's .env is normal. The harbor's unattended runs turn it on and pair
+  // it with GateController.hardConfine, which refuses anything flagged.
+  guardSecretReads?: boolean;
 }
 
 // Resolve symlinks so an in-cwd symlink can't smuggle a path outside scope past the
@@ -619,13 +624,16 @@ export function classifyToolCall(
     const p = firstPath(obj);
     if (!p) return null; // e.g. grep with no explicit path → in-cwd, no gate
     const abs = resolveInCwd(scope.cwd, p);
-    if (!isOutsideScope(scope, abs)) return null;
+    const outside = isOutsideScope(scope, abs);
+    const secret = scope.guardSecretReads === true && (isProtectedPath(abs) || isCredentialStorePath(abs));
+    if (!outside && !secret) return null;
     return {
       tool: toolName,
       kind: "read",
-      title: "Read outside working directory",
+      title: secret ? "Read a protected file" : "Read outside working directory",
       detail: abs,
-      outside: true,
+      outside,
+      ...(secret ? { protected: true } : {}),
       path: abs,
     };
   }
@@ -648,6 +656,28 @@ export function classifyToolCall(
     };
   }
 
+  // terminal (src/tools/terminal.ts) — named windows the user watches. Opening one
+  // with a command RUNS that command, so it is bash-kind with the command as the
+  // detail: the same danger list, allowlist and plan-mode refusal as typing it into
+  // bash. A bare shell is bash-kind too (it puts a new window on the user's screen),
+  // and so is close, which ends whatever runs in the window. Focus and list only move
+  // a window to the front or read names: no gate, in any mode.
+  if (name === "terminal") {
+    const action = str(obj.action) || "list";
+    if (action === "focus" || action === "list") return null;
+    const label = str(obj.name);
+    if (action === "close") {
+      return { tool: toolName, kind: "bash", title: `Close terminal "${label}"`, detail: `close terminal ${label}` };
+    }
+    const command = str(obj.command).trim();
+    return {
+      tool: toolName,
+      kind: "bash",
+      title: command ? `Open terminal "${label}" running a command` : `Open terminal "${label}"`,
+      detail: command || `open a shell${obj.cwd ? ` in ${str(obj.cwd)}` : ""}`,
+    };
+  }
+
   // Network reads (web fetch / search / http).
   if (name.includes("fetch") || name.includes("web") || name.includes("http") || name.includes("url")) {
     return {

package/src/permissions/danger.ts

@@ -37,6 +37,15 @@ export function looksLikeSecretExfil(command: string): boolean {
   return SECRET_FILE.test(command) && NETWORK_SINK.test(command);
 }
 
+// Does this command look like it can move bytes off the machine? Private mode refuses
+// these outright (permissions/privateMode.ts). Same heuristic as the exfil check, plus
+// the git and package-manager verbs that upload: a regex over the raw text, not a shell
+// parser, so it is a net, not a proof.
+const UPLOAD_VERB = /\bgit\s+push\b|\b(npm|pnpm|yarn)\s+publish\b/i;
+export function reachesNetwork(command: string): boolean {
+  return NETWORK_SINK.test(command) || UPLOAD_VERB.test(command);
+}
+
 export function matchesDenylist(command: string, patterns: string[]): boolean {
   return patterns.some((src) => {
     if (!src.trim()) return false;

package/src/permissions/modeGate.ts

@@ -69,6 +69,12 @@ export interface ModeGateDeps {
   // budget RECORDS what it allows — asking it about a call the mode would refuse anyway
   // would spend budget on nothing.
   isSpendPreauthorized?: (req: PermissionRequest) => boolean | Promise<boolean>;
+  // Refuse every request that leaves cwd or touches a protected file, whatever the mode.
+  // For the harbor's unattended runs, which run in `bypass` (their safety is the tool
+  // allow-list) — and bypass allows outside/protected outright (mode.ts), which left
+  // their `confineToCwd` meaning nothing. Sits below no-quarter only: an operator who
+  // launched with --no-quarter asked for no gate at all.
+  hardConfine?: boolean;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -85,6 +91,8 @@ export class ModeGate implements PermissionGate {
     // first check so nothing below can force an "ask" back on.
     if (this.deps.getSkipAllPermissions?.()) return "allow";
 
+    if (this.deps.hardConfine && (req.outside || req.protected)) return "deny";
+
     const denylist = this.deps.denylist ?? [];
     const auto = decideAuto(req, this.deps.getMode(), this.deps.allowlist, denylist);
 

package/src/permissions/privateMode.ts

@@ -0,0 +1,136 @@
+// Private mode — the contract another agent relies on when it hands Privateer data it
+// must not see itself.
+//
+// The handoff: an agent running on a model that is NOT private (a hosted frontier model,
+// say) has a task that touches sensitive files. It keeps them out of its own context by
+// asking Privateer to do the reading: `privateer -p --private "…"`, or an ACP session
+// with `acp.private`. That only works if Privateer refuses to put those files in front of
+// a model that isn't private either. A config that quietly fell back to a BYO-key model,
+// a sealed shim that never came up, an attestation that came back yellow: each would
+// send the very data the caller was keeping out of its own provider to someone else's.
+//
+// So private mode is enforced where the data enters the model: at the TOOL CALL. Before
+// any tool runs, the session's current model must resolve to a verified-private tier —
+// `tee-verified` (an enclave quote we checked) or `local` (on this machine). Anything
+// else, including a check that throws, blocks the tool. The caller's own prompt still
+// reaches the model, by design: it is the caller's text, and the caller already holds it.
+// What never reaches an unverified model is anything Privateer READ on the caller's
+// behalf.
+//
+// The second half is egress. A private model does not make a tool call private: a
+// web_fetch carrying a file's contents leaves the machine no matter where inference ran.
+// Private mode therefore runs on an ALLOWLIST of tools that stay on this machine, and
+// refuses shell commands that reach the network, before any mode or approval is
+// consulted — so no-quarter, `acp.posture: "auto"` and an approval cannot lift it.
+//
+// Turned on by `--private` (the launcher sets PRIVATEER_PRIVATE=1) or `acp.private`.
+// The env var is honoured from the ambient environment on purpose: unlike the spend
+// grants it can only ever make a run STRICTER, so an orchestrator may export it once
+// for every Privateer it spawns. Subagent children inherit it with the rest of the env.
+//
+// IMPORT-SAFETY: the gate imports this module statically, and the gate must stay
+// import-order-safe, so the Pi-touching posture code is imported dynamically below.
+
+import type { PrivacyTier } from "pi-privacy";
+import { reachesNetwork } from "./danger.ts";
+
+export const PRIVATE_ENV = "PRIVATEER_PRIVATE";
+
+/** True when the environment asks for private mode. */
+export function privateModeFromEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const v = (env[PRIVATE_ENV] ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/** The tiers a sensitive file may be shown to. Nothing weaker, and nothing asserted. */
+export const PRIVATE_TIERS: ReadonlySet<PrivacyTier> = new Set<PrivacyTier>(["tee-verified", "local"]);
+
+/**
+ * Tools that keep their effects on this machine. Everything else (web, crypto lookups,
+ * media generation, MCP, app/library uploads, routines, screen control) is refused in
+ * private mode, because each one can carry what was read to a third party. `bash` and
+ * `terminal` are here but also pass through reachesNetwork().
+ */
+export const PRIVATE_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "write",
+  "edit",
+  "bash",
+  "terminal",
+  // Children inherit PRIVATEER_PRIVATE and run this same check against their own model.
+  "subagent",
+  "contact_supervisor",
+  "intercom",
+]);
+
+export interface ModelRef {
+  provider?: string;
+  id?: string;
+  baseUrl?: string;
+}
+
+const TTL_MS = 60_000;
+const tierCache = new Map<string, { tier: PrivacyTier; at: number }>();
+
+/** Test seam: swap how a model's tier is resolved. */
+let resolveTierImpl: (m: Required<Pick<ModelRef, "provider" | "id">> & ModelRef) => Promise<PrivacyTier> = defaultResolveTier;
+export function setTierResolverForTests(fn: typeof resolveTierImpl | undefined): void {
+  resolveTierImpl = fn ?? defaultResolveTier;
+  tierCache.clear();
+}
+
+async function defaultResolveTier(m: Required<Pick<ModelRef, "provider" | "id">> & ModelRef): Promise<PrivacyTier> {
+  // The account channel's verdict is ours to give (see config/privacyPolicy.ts
+  // resolveTier); every other provider is pi-privacy's, which attests TEE providers live
+  // and never returns tee-verified from a static claim.
+  if (m.provider === "privateer") {
+    const { accountPosture } = await import("../providers/account.ts");
+    return (await accountPosture(m.id)).tier;
+  }
+  const { verifyModelPosture } = await import("pi-privacy");
+  const apiKey = m.provider === "nearai" ? process.env.NEARAI_API_KEY : undefined;
+  return (await verifyModelPosture(m.provider, m.id, { baseUrl: m.baseUrl, apiKey })).tier;
+}
+
+/** The model's privacy tier, from a short cache. A failure is not a tier — it throws. */
+export async function modelTier(model: ModelRef): Promise<PrivacyTier> {
+  if (!model.provider || !model.id) throw new Error("no model selected");
+  const key = `${model.provider}/${model.id}@${model.baseUrl ?? ""}`;
+  const hit = tierCache.get(key);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit.tier;
+  const tier = await resolveTierImpl({ ...model, provider: model.provider, id: model.id });
+  tierCache.set(key, { tier, at: Date.now() });
+  return tier;
+}
+
+const label = (m: ModelRef | undefined) => (m?.provider && m?.id ? `${m.provider}/${m.id}` : "no model");
+
+/**
+ * Why this tool call may not run in private mode, or undefined when it may. Never
+ * throws: any failure to establish privacy is itself the refusal.
+ */
+export async function privateRefusal(toolName: string, input: unknown, model: ModelRef | undefined): Promise<string | undefined> {
+  if (!PRIVATE_TOOLS.has(toolName)) {
+    return `${toolName} is unavailable in private mode: it can carry what this session has read off this machine. Work with local files only.`;
+  }
+  if (toolName === "bash" || toolName === "terminal") {
+    const obj = (input ?? {}) as Record<string, unknown>;
+    const command = String(obj.command ?? obj.cmd ?? obj.script ?? "");
+    if (reachesNetwork(command)) {
+      return `This command reaches the network, which private mode refuses: it could carry what this session has read off this machine. Use local commands only.`;
+    }
+  }
+  let tier: PrivacyTier;
+  try {
+    tier = await modelTier(model ?? {});
+  } catch (e) {
+    return `Private mode could not verify ${label(model)} (${e instanceof Error ? e.message : String(e)}), so no tool may run: its output would reach a model that isn't proven private. Stop and report this; do not retry.`;
+  }
+  if (!PRIVATE_TIERS.has(tier)) {
+    return `Private mode: ${label(model)} is "${tier}", not a verified-private model, so no tool may run: its output would reach a model that isn't proven private. Stop and report this; do not retry.`;
+  }
+  return undefined;
+}