privateer-agent 0.3.5 → 0.4.0

package/README.md

@@ -63,6 +63,7 @@ What Privateer adds is a *moat* of Pi extensions layered on top:
 | Extension | What it adds |
 |---|---|
 | `privateer-gate` | safe-by-default permission gate + destructive-command danger filter |
+| `privateer-context` | loads `PRIVATEER.md` project context (like `AGENTS.md`/`CLAUDE.md`) + the `/init` command |
 | `privateer-privacy` | `pi-privacy` — TEE attestation, ZDR routing, on-device PII gate — bound to the account tier resolver |
 | `privateer-account` | `/signin` billed inference against a Privateer account (device flow) |
 | `privateer-posture`, `privateer-tools` | live attestation shield + Privateer tool pack |
@@ -168,6 +169,24 @@ vLLM, llama.cpp) works as a custom provider — just give it a base URL.
 
 Override the config location with `PRIVATEER_HOME`.
 
+## Context files — `PRIVATEER.md`
+
+Give the agent standing knowledge about your project — conventions, common commands,
+domain notes — by dropping a **`PRIVATEER.md`** in the directory. Privateer loads it
+automatically at the start of every turn and prepends it to the model's system prompt,
+exactly the way Pi loads `AGENTS.md` / `CLAUDE.md` (all three are recognized, and all
+matching files are concatenated).
+
+Run **`/init`** to scaffold a starter `PRIVATEER.md` in the current directory, then edit
+it. The startup banner shows a **⚓** line with the loaded file's path (and a `+N` count
+when ancestor files also apply), or a `/init` hint when none is found.
+
+Discovery mirrors Pi's context-file lookup: the global agent dir
+(`~/.privateer/agent/PRIVATEER.md`) first, then every directory from the filesystem root
+down to the current one — so a repo-root `PRIVATEER.md` applies to every subdirectory, and
+a deeper file can refine it. `AGENTS.md` and `CLAUDE.md` continue to work unchanged; use
+`--no-context-files` (`-nc`) to disable context-file loading entirely.
+
 ## Private & verifiable inference
 
 **NEAR AI Cloud** and **Tinfoil** run every model inside a **Trusted Execution Environment** —

package/bin/privateer-daemon.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Launcher for the resident Privateer daemon (routines + app-driven headless task
+// spawns). Mirrors bin/privateer.mjs: load dev keys from the repo .env WITHOUT
+// changing cwd, register tsx so TS resolves regardless of the invocation cwd, then
+// hand off to the daemon CLI dispatcher (which imports ./boot.ts before any Pi code).
+//
+// Invoked two ways: interactively via the bash launcher (`privateer daemon …`), and
+// by the installed launchd/systemd service (`node privateer-daemon.mjs run`).
+import { register } from "tsx/esm/api";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "..");
+
+try {
+  process.loadEnvFile(resolve(repo, ".env"));
+} catch {
+  /* no .env — rely on the ambient environment / ~/.privateer */
+}
+
+// The daemon loads the moat as in-code factories, so its subagent children (routines /
+// task sessions) can't inherit it and `pi` isn't on PATH. Point pi-subagents at our
+// moat-injecting wrapper so those children spawn gated + private with no double-load.
+// Process-global is safe here: the wrapper is stateless (unlike a per-parent channel).
+process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
+
+register();
+const { runDaemonCli } = await import(resolve(repo, "src/cli/daemonCli.ts"));
+await runDaemonCli(process.argv.slice(2));

package/bin/privateer-subagent.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// The binary pi-subagents spawns for each subagent child (via PI_SUBAGENT_PI_BINARY)
+// when the PARENT loaded privateer's moat as IN-CODE extension factories (the lean
+// REPL, the daemon, live task sessions) rather than agent-dir discovery.
+//
+// Why a wrapper here (vs the plain cli.js the TUI uses): a subagent child is a fresh
+// `pi` subprocess that can't inherit the parent's in-code factories. It CAN auto-
+// discover agent-dir extensions — but if the parent ALSO loaded those same shims as
+// factories, Pi loads both (resource-loader merges discovered + inline) and the moat
+// double-loads (two gates, two provider registrations). So instead of relying on
+// discovery, this wrapper injects the moat EXPLICITLY as `-e` extensions and passes
+// `--no-extensions` to turn agent-dir discovery OFF. The child then loads exactly:
+//   • pi-subagents' own runtime extensions (already present in the argv it built), and
+//   • privateer's gate + privacy + account (the three `-e` below),
+// with no discovery, hence no double-load — while pi-subagents' explicit `--extension`
+// args still load (‑‑no‑extensions only disables DISCOVERY, not explicit `-e`).
+//
+// Exported helpers are pure and unit-tested (tests/subagentWrapper.test.ts); the
+// spawn only runs when this file is invoked as a binary.
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // bin/
+const REPO = resolve(HERE, ".."); // repo root
+
+// Absolute paths to privateer's moat extension entry files (the same modules the TUI
+// installs as discovery shims). gate = the permission moat (fail-closed / forwards
+// child approvals to the parent); privacy = ZDR/TEE posture + attestation dispatcher;
+// account = the privateer/* provider so a child can run account models.
+export function moatExtensionPaths(repoRoot = REPO) {
+  return [
+    join(repoRoot, "extensions", "privateer-gate.ts"),
+    join(repoRoot, "extensions", "privateer-privacy.ts"),
+    join(repoRoot, "extensions", "privateer-account.ts"),
+  ];
+}
+
+// The bundled Pi CLI the child actually runs (executable, `#!/usr/bin/env node`).
+export function piCliPath(repoRoot = REPO) {
+  return join(repoRoot, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
+}
+
+// Given the args pi-subagents built for the child, return the args to run the bundled
+// cli.js with: `--no-extensions` + one `-e <path>` per moat extension, THEN the
+// original args (so the injected flags precede the positional `Task:` prompt).
+export function buildChildArgs(originalArgs, repoRoot = REPO) {
+  const inject = ["--no-extensions"];
+  for (const p of moatExtensionPaths(repoRoot)) inject.push("-e", p);
+  return [...inject, ...originalArgs];
+}
+
+// Run only when invoked directly (not when imported by the test).
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = buildChildArgs(process.argv.slice(2));
+  const child = spawn(process.execPath, [piCliPath(), ...args], { stdio: "inherit", env: process.env });
+  // Propagate the child's exit faithfully so pi-subagents' parent reads the real
+  // outcome (a signal re-raises; otherwise exit with the same code).
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+  child.on("error", (e) => {
+    console.error(`privateer-subagent: failed to spawn pi — ${e.message}`);
+    process.exit(1);
+  });
+}

package/bin/privateer-tui

@@ -38,6 +38,18 @@ pick_node() {
   echo "node"
 }
 
+# `privateer daemon [run|install|uninstall|status]` — the resident background daemon
+# (routines + app-driven headless task spawns). Handled HERE, before the Pi TUI exec
+# and before the moat-shim install (the daemon doesn't need the interactive extension
+# set), so it boots straight into src/daemon via bin/privateer-daemon.mjs.
+if [ "${1:-}" = "daemon" ]; then
+  shift
+  DAEMON_NODE="$(pick_node)"
+  DAEMON_ENV_ARGS=""
+  [ -f "$REPO/.env" ] && DAEMON_ENV_ARGS="--env-file=$REPO/.env"
+  exec "$DAEMON_NODE" ${DAEMON_ENV_ARGS:+"$DAEMON_ENV_ARGS"} "$REPO/bin/privateer-daemon.mjs" "$@"
+fi
+
 AGENT_DIR="${PRIVATEER_HOME:-$HOME/.privateer}/agent"
 EXT_DIR="$AGENT_DIR/extensions"
 mkdir -p "$EXT_DIR"
@@ -46,11 +58,13 @@ mkdir -p "$EXT_DIR"
 # ABSOLUTE path so the target's own relative imports resolve from the repo (a plain
 # symlink would resolve them relative to the shim's location and break). We remove
 # any shim we previously managed first, so a dropped package can't linger and reload.
-MANAGED="privateer-brand privateer-gate privateer-account privateer-posture privateer-tools privateer-privacy pi-privacy pi-web-access rpiv-web-tools pi-mcp-adapter pi-hypa pi-subagents"
+MANAGED="privateer-brand privateer-context privateer-gate privateer-account privateer-posture privateer-tools privateer-privacy pi-privacy pi-web-access rpiv-web-tools pi-mcp-adapter pi-hypa pi-subagents"
 for name in $MANAGED; do rm -f "$EXT_DIR/$name.ts"; done
 shim() { printf 'export { default } from "%s";\n' "$2" > "$EXT_DIR/$1.ts"; }
 # Branding + the account sign-in surface (banner, ⚓ badge, /signin /signout).
 shim privateer-brand   "$REPO/extensions/privateer-brand.ts"
+# PRIVATEER.md project-context loading (like AGENTS.md/CLAUDE.md) + the /init command.
+shim privateer-context "$REPO/extensions/privateer-context.ts"
 shim privateer-gate    "$REPO/extensions/privateer-gate.ts"
 shim privateer-account "$REPO/extensions/privateer-account.ts"
 shim privateer-posture "$REPO/extensions/privateer-posture.ts"
@@ -68,6 +82,13 @@ shim pi-subagents      "$REPO/node_modules/pi-subagents/src/extension/index.ts"
 
 CLI="$REPO/node_modules/@earendil-works/pi-coding-agent/dist/cli.js"
 export PI_CODING_AGENT_DIR="$AGENT_DIR"
+# The binary pi-subagents spawns for each subagent child. Without this it falls back
+# to `pi` on PATH (getPiSpawnCommand) — which a Privateer install does NOT provide, so
+# every subagent spawn would fail with ENOENT. Point it at OUR bundled cli.js (it's
+# executable, `#!/usr/bin/env node`): the child then reads this same PI_CODING_AGENT_DIR
+# and DISCOVERS the moat shims above — so subagents run gated + private, no -e injection
+# (hence no double-load). Set only when unset so a power user can override it.
+export PI_SUBAGENT_PI_BINARY="${PI_SUBAGENT_PI_BINARY:-$CLI}"
 # Suppress Pi's upstream "Update Available — run `pi update`" banner. It's noise on a
 # Privateer install (our banner is the startup surface), it leaks the "pi" name, and
 # `pi update` would fight our npm-managed install. PI_SKIP_VERSION_CHECK disables ONLY
@@ -108,13 +129,22 @@ if [ -z "$(find "$UPDATE_CACHE" -mtime -1 2>/dev/null)" ]; then
   ) </dev/null >/dev/null 2>&1 &
 fi
 
-# Default model: when signed in to a Privateer account, default to GLM 5.1 on the
-# account's NEAR confidential-compute (TEE) channel — attestable, strongest privacy
-# tier. Otherwise (BYO key, no account) fall back to a cheap OpenRouter model. An
-# explicit PRIVATEER_MODEL always wins.
+# Default model. An explicit PRIVATEER_MODEL always wins. Otherwise prefer Tinfoil's
+# GLM 5.2 when a Tinfoil key is available: verifiable TEE inference with CLIENT-side
+# attestation (the live TLS key is bound to the enclave's quote), the strongest privacy
+# tier we offer — stronger than the account's server-proxied NEAR channel. Failing that,
+# use the signed-in Privateer account's NEAR confidential-compute channel; with neither,
+# fall back to a cheap OpenRouter model. The Tinfoil key may sit in the ambient env or in
+# the dev .env the launcher loads below, so check both.
 CRED="${PRIVATEER_HOME:-$HOME/.privateer}/credentials.json"
+have_tinfoil_key() {
+  [ -n "${TINFOIL_API_KEY:-}" ] && return 0
+  [ -f "$REPO/.env" ] && grep -qE '^TINFOIL_API_KEY=.+' "$REPO/.env"
+}
 if [ -n "${PRIVATEER_MODEL:-}" ]; then
   MODEL="$PRIVATEER_MODEL"
+elif have_tinfoil_key; then
+  MODEL="tinfoil/glm-5-2"
 elif [ -f "$CRED" ]; then
   MODEL="privateer/near/zai-org/GLM-5.1-FP8"
 else

package/extensions/privateer-brand.ts

@@ -19,11 +19,12 @@
 // appear immediately (the account catalog refreshes to the live listing without a
 // restart).
 
-import { readFileSync } from "node:fs";
+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 { discoverContextFiles, onContextChanged } from "../src/context.ts";
 
 const VERSION: string = (() => {
   try {
@@ -33,35 +34,75 @@ const VERSION: string = (() => {
   }
 })();
 
-// ── palette (Privateer "Open Water" ocean-blue brand) ────────────────────────
+// ── palette (Privateer brand) ────────────────────────────────────────────────
 // 256-color (8-bit), NOT 24-bit truecolor: macOS Terminal.app doesn't support
 // truecolor and mangles it (the old indigo/cyan came out green). These indices are
-// universally supported. Navy (the logo mark) is too dark to read on a dark terminal,
-// so we use the app's ocean blues — the same "Open Water" gradient as the brand.
+// universally supported. Navy (the logo mark) is too dark to read on a dark terminal, so
+// the whole banner — silhouette, wordmark, frame, and accents — is painted white: a clean
+// single-color mark, like the logo but legible on dark.
 const ESC = "\x1b[";
 const RESET = `${ESC}0m`;
 const BOLD = `${ESC}1m`;
 const c = (n: number): string => `${ESC}38;5;${n}m`;
-const OCEAN = c(39); // ≈ #00afff — primary ocean blue (anchor, wordmark "P")
-const OCEAN_LIGHT = c(81); // ≈ #5fd7ff — light sky accent (wordmark, version, path)
-const BORDER = c(32); // ≈ #0087d7 — deeper ocean, the frame
+const OCEAN = c(231); // white (#ffffff) — anchor / wordmark "P"
+const OCEAN_LIGHT = c(231); // white (#ffffff) — wordmark, version, path
+const BORDER = c(231); // white (#ffffff) — the frame
 const DIM = `${ESC}90m`;
 const GREEN = `${ESC}32m`;
 const YELLOW = `${ESC}33m`;
 
-// The Privateer mark in ASCII: a padlock (with keyhole) atop an anchor — "bring your
-// own model" meets lock-and-key privacy, echoing the app's anchor+padlock logo. Every
-// line is the same visible width (11) so the text column beside it stays aligned.
-const ANCHOR = [
-  "    .-.    ", // shackle arch
-  "   |   |   ", // shackle legs
-  "  .-----.  ", // lock body top (the shackle's base)
-  "  |  o  |  ", // lock body + keyhole
-  "  '--+--'  ", // lock body base, shank exits
-  " /\\  |  /\\  ", // stock — arms flare from the shank (each \\ is one backslash)
-  "  \\  |  /  ", // arms
-  "   \\_|_/   ", // flukes
+// The Privateer mark: our symbol — a padlock (with a keyhole) fused into an anchor,
+// "bring your own model" meets lock-and-key privacy — drawn from the app's logo. It's
+// rendered with terminal HALF-BLOCKS, so each text row packs TWO pixel rows: a "▀"
+// whose FOREGROUND paints the top pixel and BACKGROUND the bottom (one pixel → "▀"/"▄"
+// on the default bg; none → a plain space). 256-color indices only, same reason as the
+// palette above. Every built line is MARK_W visible cells wide (SGR escapes don't
+// count), so the text column beside it stays aligned. To redraw: edit PIXELS (each char
+// is a PX palette key), keeping every row MARK_W long and the row COUNT even — the
+// builder derives the escapes from that.
+const MARK_W = 12;
+const PX: Record<string, number | null> = {
+  ".": null, // transparent — the frame (and the knocked-out keyhole) shows through
+  O: 231, // white (#ffffff, top of the 256-color cube) — the silhouette, a clean single-color mark
+};
+// 12 wide; an EVEN number of rows so they pair cleanly into half-block cells. Two blank
+// leading rows give the lock a little headroom without dropping the whole mark too low.
+// A small padlock rides on top as the anchor's ring: a narrow rounded shackle over an
+// 8-wide body that OVERHANGS the shackle on both sides (matching the logo's proportions,
+// where the body is clearly wider than the shackle), with a small centered 2×2 keyhole
+// knocked out of it — reads clearly as a lock without dominating the anchor. Then a short
+// shank → hooked fluke barbs (a 2-tall blade tip that turns up-and-out) → crown → bill.
+const PIXELS = [
+  "............", "............",
+  "....OOOO....", "...OO..OO...", "...OO..OO...",
+  "..OOOOOOOO..", "..OOOOOOOO..",
+  "..OOO..OOO..", "..OOO..OOO..",
+  "..OOOOOOOO..", "..OOOOOOOO..",
+  ".....OO.....", ".....OO.....",
+  "O....OO....O", "OO...OO...OO", "OO...OO...OO",
+  ".OO..OO..OO.", "..OO.OO.OO..",
+  "..OOOOOOOO..", "...OOOOOO...", "....OOOO....", ".....OO.....",
 ];
+// Build the mark once at load. Each cell resets SGR so a background color can never
+// bleed into the row padding the framer adds after it.
+const MARK: string[] = (() => {
+  const rows: string[] = [];
+  for (let r = 0; r < PIXELS.length; r += 2) {
+    const top = PIXELS[r];
+    const bot = PIXELS[r + 1] ?? ".".repeat(MARK_W);
+    let line = "";
+    for (let x = 0; x < MARK_W; x++) {
+      const t = PX[top[x]];
+      const bcol = PX[bot[x]];
+      if (t == null && bcol == null) line += " ";
+      else if (t != null && bcol != null) line += `${ESC}38;5;${t}m${ESC}48;5;${bcol}m▀${RESET}`;
+      else if (t != null) line += `${ESC}38;5;${t}m▀${RESET}`;
+      else line += `${ESC}38;5;${bcol}m▄${RESET}`;
+    }
+    rows.push(line);
+  }
+  return rows;
+})();
 
 // Visible width = characters after stripping SGR escapes. Everything we render inside
 // the box is ASCII or a BMP width-1 symbol, so a plain length is exact here.
@@ -82,11 +123,16 @@ function clean(s: unknown): string {
   return String(s ?? "").replace(CONTROL_RE, "");
 }
 
-function shortCwd(): string {
-  const cwd = process.cwd();
+// Collapse $HOME to ~ in an absolute path, and strip control bytes (paths come off the
+// filesystem). Shared by the cwd line and the PRIVATEER.md line.
+function shortPath(p: string): string {
   const home = homedir();
-  const path = cwd === home || cwd.startsWith(home + "/") ? "~" + cwd.slice(home.length) : cwd;
-  return clean(path);
+  const short = p === home || p.startsWith(home + "/") ? "~" + p.slice(home.length) : p;
+  return clean(short);
+}
+
+function shortCwd(): string {
+  return shortPath(process.cwd());
 }
 
 // The account line under the tagline — three states, ported from tree-cli's Banner:
@@ -134,25 +180,74 @@ function updateNotice(): string {
   return "";
 }
 
-// Compose the framed banner: anchor column + text column, inside a rounded accent box.
+// The PRIVATEER.md line under the block: green anchor when a project-context file is
+// loaded (so the moat's "the agent knows this project" state is visible), otherwise a
+// quiet tease that /init scaffolds one. Reads the filesystem at render time, so it
+// reflects the current cwd and updates after /init (via onContextChanged → refresh).
+function contextLine(): string {
+  const files = discoverContextFiles();
+  if (files.length === 0) {
+    return `${DIM}no PRIVATEER.md · ${OCEAN_LIGHT}/init${DIM} to add project context${RESET}`;
+  }
+  // Show the nearest (deepest, wins-last) file's path; note any additional ancestors
+  // with a "+N" so the header stays one line but the count isn't hidden.
+  const nearest = shortPath(files[files.length - 1].path);
+  const more = files.length > 1 ? `${DIM} +${files.length - 1}${RESET}` : "";
+  return `${GREEN}⚓${DIM} ${RESET}${OCEAN_LIGHT}${nearest}${RESET}${more}`;
+}
+
+// ── "What's New" — a tiny in-banner changelog ────────────────────────────────
+// A hand-curated highlights list (newest first). Not the full changelog — just the two
+// or three things a returning user should notice. `cmd`, when present, is rendered in the
+// accent color so the actionable bit stands out from the prose. Trim this as it ages.
+const WHATS_NEW: Array<{ text: string; cmd?: string }> = [
+  { text: "Privateer agent CLI is live —", cmd: "npm i -g privateer-agent" },
+  { text: "PRIVATEER.md project context —", cmd: "/init" },
+  { text: "Self-update built in —", cmd: "privateer update" },
+];
+
+function whatsNewRows(): string[] {
+  const head = `${BOLD}${OCEAN_LIGHT}✦ What's new${RESET}`;
+  const items = WHATS_NEW.map(
+    ({ text, cmd }) =>
+      `${OCEAN}·${RESET} ${DIM}${text}${RESET}${cmd ? ` ${OCEAN_LIGHT}${cmd}${RESET}` : ""}`,
+  );
+  return [head, ...items];
+}
+
+// Compose the framed banner: the mark on the left, an independent text column on the
+// right. The two columns have DIFFERENT heights (the text runs longer than the 6-line
+// mark), so we zip by row index and pad the short side — every text-only row lands in
+// the same column as the rows beside the mark. One place owns the left gutter, so
+// spacing can't drift between the mark rows and the trailing rows.
 function renderBanner(width: number, modelProvider?: string): string[] {
-  // Leading blanks drop the text block so the wordmark sits beside the lock body and
-  // the shackle rises above it (one entry per anchor line — 8 total).
-  const right = [
+  // Right column, top to bottom. The two leading blanks drop the wordmark down so it
+  // sits beside the lock body (not the shackle); the rest follows in reading order.
+  const text: string[] = [
     "",
-    "",
-    `${BOLD}${OCEAN_LIGHT}✻ ${OCEAN}P${OCEAN_LIGHT}RIVATEER${RESET}`,
+    `${BOLD}${OCEAN_LIGHT}✻ ${OCEAN}P${OCEAN_LIGHT}RIVATEER${RESET}${DIM}   privateer-agent ${OCEAN_LIGHT}v${VERSION}${RESET}`,
     `${DIM}Chart your own course privately.${RESET}`,
     "",
     accountLine(modelProvider),
-    `${DIM}privateer-agent ${OCEAN_LIGHT}v${VERSION}${RESET}`,
     `${OCEAN_LIGHT}${shortCwd()}${RESET}`,
+    contextLine(),
   ];
-  // Build the body rows (anchor + gutter + text). A pending-update notice, if any, gets
-  // its own row under the block, indented to sit beneath the text column.
-  const rows = ANCHOR.map((a, i) => `${OCEAN}${a}${RESET}  ${right[i] ?? ""}`);
   const notice = updateNotice();
-  if (notice) rows.push(`      ${notice}`);
+  if (notice) text.push(notice);
+  // A blank spacer, then the What's New block — set off below the identity lines.
+  text.push("", ...whatsNewRows());
+
+  // Zip the mark and the text column by row. Rows past the mark's height get a blank
+  // gutter of the mark's width, so the text stays in one column throughout.
+  const gap = "  ";
+  const height = Math.max(MARK.length, text.length);
+  const rows: string[] = [];
+  for (let i = 0; i < height; i++) {
+    // The mark lines already carry their own per-pixel colors, so we don't wrap them.
+    const left = i < MARK.length ? MARK[i] : " ".repeat(MARK_W);
+    rows.push(`${left}${gap}${text[i] ?? ""}`.trimEnd());
+  }
+
   const cap = Math.max(20, width - 4); // 2 border cells + 2 padding
   const inner = Math.min(cap, Math.max(...rows.map(vlen)));
   const bar = "─".repeat(inner + 2);
@@ -186,15 +281,45 @@ export default function privateerBrand(pi: any): void {
   let currentModelProvider: string | undefined;
   let ctxRef: any = null;
 
+  // TEMP debug trace (PRIVATEER_DEBUG=1): append a line to ~/.privateer/brand-debug.log
+  // so we can see, from a real sign-in, whether the refresh path fires and with what state.
+  const dbg = (msg: string): void => {
+    if (!process.env.PRIVATEER_DEBUG) return;
+    try {
+      const home = process.env.PRIVATEER_HOME || join(homedir(), ".privateer");
+      appendFileSync(join(home, "brand-debug.log"), `${new Date().toISOString()} ${msg}\n`);
+    } catch {
+      /* best effort */
+    }
+  };
+
   const setHeader = (ctx: any) =>
     ctx?.ui?.setHeader?.(() => headerComponent(currentModelProvider));
 
   const refresh = (ctx: any) => {
+    dbg(`refresh: hasUI=${!!ctx?.hasUI} hasSetHeader=${typeof ctx?.ui?.setHeader} user=${priv.currentUser()?.email ?? null}`);
     if (!ctx?.hasUI) return;
     setHeader(ctx);
     ctx?.ui?.setStatus?.("account", accountBadge());
   };
 
+  // Drop Pi's PERSISTED account credential (the "privateer" entry in auth.json).
+  // Pi reuses this credential on the next launch and refreshes it only when it
+  // EXPIRES — never reactively on a 401 (see the LIFECYCLE HAZARD note in
+  // src/auth/privateer.ts). So whenever the machine login goes away — an explicit
+  // /signout, or a revocation/expiry we detect server-side — we MUST also drop this
+  // persisted copy, or the next run reuses a token that's already dead server-side
+  // and dead-ends on the first inference. Removing it makes the next /signin spawn a
+  // fresh session. Reached via the model registry (constructed with the auth
+  // storage; see session.ts). Best-effort: nothing persisted → nothing to do.
+  const dropPersistedAccount = (ctx: any): void => {
+    try {
+      ctx?.modelRegistry?.authStorage?.remove?.("privateer");
+    } catch {
+      /* no persisted credential / older Pi without this shape — nothing to do */
+    }
+  };
+
   // /update — run the global npm install in a child process and report the outcome via
   // notify (the TUI keeps running the OLD code; npm swaps the global bin's inode in
   // place, so replacing it under us is safe and the new version loads on next launch).
@@ -266,6 +391,7 @@ export default function privateerBrand(pi: any): void {
     if (!priv.hasCredentials()) return ctx?.ui?.notify?.("Not signed in.", "info");
     const u = priv.currentUser();
     await priv.logout();
+    dropPersistedAccount(ctx);
     refresh(ctx);
     ctx?.ui?.notify?.(`Signed out${u?.email ? ` (${u.email})` : ""}. Drop anchor for now.`, "info");
   }
@@ -280,9 +406,26 @@ export default function privateerBrand(pi: any): void {
     );
   }
 
+  dbg("extension loaded, onSignedIn listener registering");
+
   pi.on("session_start", (_e: any, ctx: any) => {
+    dbg("session_start");
     ctxRef = ctx;
     currentModelProvider = ctx?.model?.provider ?? currentModelProvider;
+
+    // Validate the machine login against the server at launch. The banner/badge
+    // otherwise reflect ONLY local credentials.json, so a terminal that was signed
+    // out from the app (or whose login expired) keeps showing "connected as …"
+    // indefinitely — nothing else spawns a session at startup (Pi reuses its
+    // persisted account credential and refreshes it only on expiry, not on a 401).
+    // warmSession spawns this terminal's child session from the parent refresh
+    // token; if that token was revoked/expired the server 401s, which clears the
+    // local credentials and fires onSessionExpired — flipping the banner to "not
+    // signed in" right here at launch instead of dead-ending on the first prompt.
+    // Fire-and-forget: warmSession swallows transient errors, and the
+    // onSessionExpired handler below owns the UI update.
+    void priv.warmSession();
+
     if (!ctx?.hasUI) return; // headless (print/json): no banner or prompts
     ctx?.ui?.setTitle?.("Privateer");
     refresh(ctx);
@@ -301,9 +444,45 @@ export default function privateerBrand(pi: any): void {
     }
   });
 
+  // A machine login was newly established. This fires for BOTH sign-in paths — our
+  // /signin command AND Pi's /login → "Use a subscription" OAuth flow. doSignIn
+  // already refreshes itself, but a /login sign-in has no other hook back to us, so
+  // without this the header/badge would keep showing "not signed in" until relaunch.
+  priv.onSignedIn(() => {
+    dbg(`onSignedIn fired; ctxRef=${ctxRef ? "set" : "null"}`);
+    refresh(ctxRef);
+  });
+
+  // /init (in privateer-context) just created or changed a PRIVATEER.md — re-render the
+  // banner so its context line flips from the "/init" hint to "PRIVATEER.md loaded".
+  onContextChanged(() => refresh(ctxRef));
+
+  // The terminal is quitting (Ctrl+C, Ctrl+D, /quit, SIGTERM …). Pi awaits this
+  // handler inside runtimeHost.dispose() BEFORE process.exit, so it's our one
+  // reliable window to revoke the server-side sessions this run created — the
+  // account channel Pi drives AND any child session — so the terminal drops off the
+  // app's Linked Devices list immediately instead of lingering until the rows expire.
+  // Only on "quit": the other reasons (new/resume/fork/reload) keep this process
+  // alive and reuse the same account credential, so revoking would kill a live session.
+  // Best-effort and time-bounded (see revokeLocalSessions); exit must never hang.
+  pi.on("session_shutdown", async (e: any) => {
+    if (e?.reason && e.reason !== "quit") return;
+    await priv.revokeLocalSessions();
+    // Pair the revoke with dropping Pi's persisted account credential (the contract
+    // in src/auth/privateer.ts): revokeLocalSessions kills the account session
+    // server-side, so leaving the persisted copy behind would make the NEXT launch
+    // reuse a token that's already dead and dead-end on its first prompt (Pi doesn't
+    // refresh on a 401). Mirrors the daemon's shutdown (daemon/index.ts).
+    dropPersistedAccount(ctxRef);
+  });
+
   // The machine login was invalidated server-side (TTL lapsed or revoked in the app):
   // announce it and reflect it in the badge/header immediately.
   priv.onSessionExpired(() => {
+    // clearCredentials() has already wiped the local machine login; also drop Pi's
+    // persisted account credential so the next prompt/launch doesn't reuse a token
+    // 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");
   });

package/extensions/privateer-context.ts

@@ -0,0 +1,59 @@
+// PRIVATEER.md context loading + the /init command.
+//
+// Pi natively loads AGENTS.md / CLAUDE.md but its candidate list is hardcoded upstream,
+// so PRIVATEER.md would otherwise be ignored. This extension makes PRIVATEER.md a
+// first-class context file without patching node_modules:
+//
+//   1. before_agent_start — discover PRIVATEER.md (global agent dir + cwd ancestors) and
+//      append its contents to the turn's system prompt, framed exactly like Pi frames
+//      AGENTS.md, so the model treats them identically.
+//   2. /init — write a starter PRIVATEER.md into the current directory.
+//
+// The banner (privateer-brand) shows whether a PRIVATEER.md is loaded and, when none is,
+// advertises /init. After /init we emit the shared context-changed signal so that line
+// refreshes at once. See src/context.ts for the discovery/formatting details.
+
+import { contextBlock, writeTemplate, emitContextChanged, CONTEXT_BLOCK_MARKER } from "../src/context.ts";
+
+// Honor Pi's own "disable context files" switch, so --no-context-files / -nc silences
+// PRIVATEER.md too (not just AGENTS.md/CLAUDE.md) — otherwise the flag would half-work.
+const CONTEXT_FILES_DISABLED =
+  process.argv.includes("--no-context-files") || process.argv.includes("-nc");
+
+export default function privateerContext(pi: any): void {
+  // Inject PRIVATEER.md into every turn's system prompt. The prompt is rebuilt per turn
+  // and chained across before_agent_start handlers, so appending here is idempotent for
+  // the turn; the marker guard makes it a no-op if an earlier handler already added it.
+  pi.on("before_agent_start", (event: any) => {
+    if (CONTEXT_FILES_DISABLED) return;
+    const cwd = event?.systemPromptOptions?.cwd ?? process.cwd();
+    const base: string = event?.systemPrompt ?? "";
+    if (base.includes(CONTEXT_BLOCK_MARKER)) return; // already injected this chain
+    const block = contextBlock(cwd);
+    if (!block) return; // no PRIVATEER.md anywhere — leave the prompt untouched
+    return { systemPrompt: base + block };
+  });
+
+  // /init — scaffold a PRIVATEER.md in the working directory. Never clobbers an existing
+  // one; on success we signal the banner so its "PRIVATEER.md loaded" line updates now
+  // (the file is picked up automatically on the next turn — no reload needed).
+  pi.registerCommand?.("init", {
+    description: "Create a starter PRIVATEER.md project-context file in this directory",
+    handler: (_args: string, ctx: any) => {
+      try {
+        const { path, created } = writeTemplate(process.cwd());
+        if (!created) {
+          ctx?.ui?.notify?.(`PRIVATEER.md already exists at ${path} — left untouched.`, "info");
+          return;
+        }
+        emitContextChanged();
+        ctx?.ui?.notify?.(
+          `Created ${path}. Edit it with your project's context — it loads automatically each turn.`,
+          "info",
+        );
+      } catch (e) {
+        ctx?.ui?.notify?.(`Could not create PRIVATEER.md: ${(e as Error).message || e}`, "error");
+      }
+    },
+  });
+}