privateer-agent 0.6.4 → 0.6.6

package/README.md

@@ -133,6 +133,26 @@ curl -fsSL https://privateer.pro/install.sh | sh
 
 **Requirements:** macOS or Linux, Node.js ≥ 22.19.0.
 
+### Verifying what you're about to run
+
+Privateer is a coding agent — it runs shell commands and edits files, so "should I trust
+this package?" is the right question to ask before `npx`. Two things are checkable
+without taking anyone's word for it:
+
+```bash
+npm view privateer-agent dist.attestations   # published from CI with npm provenance:
+                                             # a signed link from this tarball to the
+                                             # exact commit and build that produced it
+npm audit signatures                         # verify registry signatures + provenance
+```
+
+The package also declares **no install scripts** — no `postinstall`, nothing. Installing
+it writes files and executes nothing; `npm install -g privateer-agent --ignore-scripts`
+gives an identical result. Code runs only when you run `privateer`.
+
+See [SECURITY.md](SECURITY.md) for the threat model, the permission gate, and how to
+report a vulnerability.
+
 **From source:**
 
 ```bash

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security
+
+## Reporting a vulnerability
+
+Report privately via [GitHub Security Advisories](https://github.com/privateer-agent/privateer-agent/security/advisories/new),
+or email **support@privateer.pro**. Please don't open a public issue for anything
+exploitable. Expect an initial response within 72 hours.
+
+## What you're running
+
+Privateer is a terminal coding agent: it reads and writes files, runs shell commands and
+talks to model providers on your behalf. That is the point of it, and it is also the
+threat model. Two things are worth verifying rather than taking on faith.
+
+**The package runs no install scripts.** There is no `preinstall`, `install`,
+`postinstall` or `prepare` hook. `npm install -g privateer-agent` writes files and
+executes nothing; installing with `--ignore-scripts` produces an identical result. Code
+runs only when you run `privateer`. (Dependency patching happens at first launch — see
+`bin/apply-patches.mjs` and `docs/shipping.md`.)
+
+**Releases carry npm provenance.** Published from `.github/workflows/release.yml` with
+`npm publish --provenance`, so npm holds a signed Sigstore attestation binding the
+tarball to this repository, the exact commit and the workflow run that built it. The npm
+package page shows a verified *"Built and signed on GitHub Actions"* badge linking to
+the build. To check it yourself:
+
+```bash
+npm view privateer-agent dist.attestations   # attestation metadata exists
+npm audit signatures                          # verifies registry signatures + provenance
+```
+
+If a version lacks provenance, it did not come from this workflow. Treat that as
+suspicious and report it.
+
+## The permission gate
+
+By default every shell command, file write outside the working directory, and
+destructive tool call stops for explicit approval. This is the moat, and it is the main
+thing standing between a prompt-injected model and your filesystem.
+
+`--no-quarter` disables it entirely — every action runs unprompted. It exists for
+trusted, disposable environments (throwaway containers, CI). Do not use it on a machine
+whose contents you care about, and do not use it on a repository or task involving
+untrusted content: a coding agent reading an attacker-controlled file is a realistic
+injection path.
+
+## Keys and credentials
+
+Provider API keys and account credentials live under `~/.privateer/` on your machine and
+are sent only to the provider you selected. Bot tokens for messaging channels are sealed
+to a terminal keypair before they reach our relay, and channel configuration is verified
+against a link-pinned account key — the relay can neither read those tokens nor forge
+configuration. Architecture and residual risks are documented in
+`docs/daemon-channels-and-app.md`.

package/bin/apply-patches.d.mts

@@ -0,0 +1,18 @@
+// Types for the launcher's patch/resolve helpers. The implementation is plain .mjs
+// because bin/ must run under a bare `node` with no transpiler (the launcher is the
+// very first thing to execute, before tsx/jiti are in play).
+
+/** Directory CONTAINING the node_modules that holds `name`, or null if not installed. */
+export function findDepRoot(from: string, name: string): string | null;
+
+/** Absolute path to a file inside an installed dependency, or null if absent. */
+export function resolveDep(from: string, name: string, ...rest: string[]): string | null;
+
+/**
+ * Apply `patches/` into whichever node_modules the targets landed in. Idempotent and
+ * best-effort; see the implementation for why this runs at launch, not on install.
+ */
+export function applyPatchesIfNeeded(
+  repo: string,
+  nodeBin?: string,
+): "current" | "applied" | "skipped" | "failed";

package/bin/apply-patches.mjs

@@ -0,0 +1,143 @@
+// Apply the patches/ directory into node_modules — at LAUNCH, not at install.
+//
+// Why not a `postinstall` script (the obvious place)? Because `npm install` /
+// `npx privateer-agent` would then execute our code on the user's machine BEFORE
+// they ever decided to run Privateer. That is exactly the install-time-execution
+// risk a careful reviewer — human or agent — flags on an unfamiliar package, and
+// it is the one npm-side signal we can remove outright. With no install scripts,
+// `npm install -g privateer-agent --ignore-scripts` is completely inert: it writes
+// files and runs nothing. Patching moves to the first actual launch, which the
+// user explicitly asked for.
+//
+// Contract: idempotent, cheap on the hot path (a stamp file short-circuits every
+// launch after the first), and BEST-EFFORT — every patch here is a UX/robustness
+// improvement, never a correctness prerequisite, so a failure to apply degrades to
+// stock Pi behaviour rather than blocking launch. That matters for the common
+// `sudo npm install -g` case, where node_modules is root-owned and an unprivileged
+// launch simply cannot write to it.
+
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Bump when the applier's own semantics change, to force a re-apply on upgrade.
+const STAMP_VERSION = 1;
+
+/**
+ * Where do our patch targets actually live?
+ *
+ * NOT necessarily `<repo>/node_modules`. When Privateer is installed as a dependency
+ * (`npm i privateer-agent`, `npx privateer-agent`), npm HOISTS pi-coding-agent to the
+ * parent project's node_modules and leaves us with no node_modules of our own — so
+ * assuming a local one means the patches silently never apply. Resolve the real target
+ * from our own package instead, and return the directory that CONTAINS the node_modules
+ * it landed in: that is the cwd patch-package needs, in every layout (hoisted, nested,
+ * global, bundled).
+ */
+/**
+ * Find the directory CONTAINING the node_modules that holds `name`, starting at
+ * `from` and walking up. Returns null if the dependency isn't installed anywhere.
+ *
+ * This is the one resolution primitive both the launcher and the patcher need,
+ * because `<repo>/node_modules` is NOT where dependencies reliably live:
+ *   - `npm i -g privateer-agent`  -> nested:  <repo>/node_modules/<name>
+ *   - `npx privateer-agent`       -> hoisted: <repo>/../node_modules/<name>
+ *   - `npm i privateer-agent`     -> hoisted into the host project
+ * Hardcoding the nested case silently breaks every hoisted install.
+ *
+ * We walk directories rather than using require.resolve because modern packages
+ * (pi-coding-agent among them) declare an `exports` map with no "./package.json"
+ * entry, so require.resolve throws ERR_PACKAGE_PATH_NOT_EXPORTED even when the
+ * package is sitting right there. Directory lookup sees through `exports`.
+ */
+export function findDepRoot(from, name) {
+  const segs = name.split("/");
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "node_modules", ...segs, "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null; // hit the filesystem root
+  }
+}
+
+/** Absolute path to an installed dependency's file, or null if the dep isn't present. */
+export function resolveDep(from, name, ...rest) {
+  const root = findDepRoot(from, name);
+  return root ? path.join(root, "node_modules", ...name.split("/"), ...rest) : null;
+}
+
+function resolvePatchRoots(repo, patchFiles) {
+  const roots = new Set();
+  for (const file of patchFiles) {
+    // "@earendil-works+pi-coding-agent+0.80.3.patch" -> "@earendil-works/pi-coding-agent"
+    const parts = path.basename(file, ".patch").split("+");
+    const name = parts[0].startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
+    const root = findDepRoot(repo, name);
+    if (root) roots.add(root);
+  }
+  return [...roots];
+}
+
+/** sha256 over every patch file's name + contents — the identity of "what should be applied". */
+function patchSetHash(patchDir, files) {
+  const h = crypto.createHash("sha256").update(String(STAMP_VERSION));
+  for (const f of files) {
+    h.update(f);
+    h.update(fs.readFileSync(path.join(patchDir, f)));
+  }
+  return h.digest("hex");
+}
+
+/**
+ * Ensure patches/ is applied to repo/node_modules. Returns one of:
+ *   "current"   — already applied (stamp matches); nothing done
+ *   "applied"   — patches were just applied successfully
+ *   "skipped"   — nothing to do (no patches / no node_modules / patch-package absent)
+ *   "failed"    — apply was attempted and did not succeed (caller may warn)
+ */
+export function applyPatchesIfNeeded(repo, nodeBin = process.execPath) {
+  try {
+    repo = path.resolve(repo); // roots come back absolute; a relative repo would break path.relative
+    const patchDir = path.join(repo, "patches");
+    if (!fs.existsSync(patchDir)) return "skipped";
+    const patchFiles = fs.readdirSync(patchDir).filter((f) => f.endsWith(".patch")).sort();
+    if (patchFiles.length === 0) return "skipped";
+
+    const want = patchSetHash(patchDir, patchFiles);
+    const roots = resolvePatchRoots(repo, patchFiles);
+    if (roots.length === 0) return "skipped"; // targets not installed
+
+    // patch-package is a runtime dependency precisely so this works post-install.
+    const pp = resolveDep(repo, "patch-package", "index.js");
+    if (!pp || !fs.existsSync(pp)) return "skipped";
+
+    let did = false;
+    for (const root of roots) {
+      const stampFile = path.join(root, "node_modules", ".privateer-patches.json");
+      try {
+        if (JSON.parse(fs.readFileSync(stampFile, "utf8")).hash === want) continue; // current
+      } catch { /* missing or unreadable stamp — (re)apply */ }
+
+      // --patch-dir points at OUR patches even though cwd is wherever the deps landed.
+      // It MUST be relative: patch-package resolves it against cwd, so an absolute path
+      // is silently mangled into a non-existent one and every patch "fails" to apply.
+      const relPatchDir = path.relative(root, patchDir);
+      const r = spawnSync(nodeBin, [pp, "--error-on-fail", "--patch-dir", relPatchDir], {
+        cwd: root,
+        stdio: ["ignore", "ignore", "pipe"],
+        timeout: 60_000,
+        windowsHide: true,
+      });
+      if (r.status !== 0) return "failed";
+      did = true;
+
+      // Only stamp after a clean apply, so a partial/failed run retries next launch.
+      try {
+        fs.writeFileSync(stampFile, JSON.stringify({ hash: want, at: new Date().toISOString() }) + "\n");
+      } catch { /* unwritable node_modules — applied fine, we just re-check next launch */ }
+    }
+    return did ? "applied" : "current";
+  } catch {
+    return "failed";
+  }
+}

package/bin/privateer-launch.mjs

@@ -17,6 +17,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // bin/
 const REPO = path.resolve(HERE, "..");
@@ -72,7 +73,8 @@ const sub = args[0];
 if (sub === "--version" || sub === "-V") {
   const ver = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf8")).version; } catch { return null; } };
   const pv = ver(path.join(REPO, "package.json")) || "unknown";
-  const pi = ver(path.join(REPO, "node_modules", "@earendil-works", "pi-coding-agent", "package.json"));
+  const piPkg = resolveDep(REPO, "@earendil-works/pi-coding-agent", "package.json");
+  const pi = piPkg ? ver(piPkg) : null;
   console.log(`privateer ${pv}${pi ? ` (pi ${pi})` : ""}`);
   process.exit(0);
 }
@@ -126,6 +128,13 @@ else {
   // time the agent tries to run a command. Unix always has a shell, so this is a no-op.
   ensureShellOrExit();
 
+  // Apply our pi-coding-agent patches. This happens HERE, on a launch the user asked
+  // for, rather than in a postinstall — so installing the package runs no code at all.
+  // Stamped, so it's a single file read on every launch after the first. Best-effort:
+  // both patches are UX fixes, so a root-owned node_modules (sudo npm i -g) just means
+  // stock Pi behaviour, not a broken boot. Bundles ship pre-patched and no-op here.
+  ensurePatches();
+
   const AGENT_DIR = path.join(PRIVATEER_HOME, "agent");
   const EXT_DIR = path.join(AGENT_DIR, "extensions");
   fs.mkdirSync(EXT_DIR, { recursive: true });
@@ -142,9 +151,17 @@ else {
   for (const name of MANAGED) fs.rmSync(path.join(EXT_DIR, `${name}.ts`), { force: true });
 
   const ext = (...p) => path.join(REPO, "extensions", ...p);
-  const dep = (...p) => path.join(REPO, "node_modules", ...p);
-  const shim = (name, target) =>
+  // Resolve dependencies by walking the node_modules chain, NOT as REPO/node_modules.
+  // npm only nests deps under us for a global install; `npx privateer-agent` and
+  // `npm i privateer-agent` HOIST them to a sibling/parent node_modules, where the
+  // hardcoded path resolves to nothing and every shim below points at a missing file.
+  const dep = (name, ...rest) => resolveDep(REPO, name, ...rest);
+  // A missing target means that optional tool pack isn't installed — skip its shim
+  // rather than writing one that points at nothing (which fails at extension load).
+  const shim = (name, target) => {
+    if (!target || !fs.existsSync(target)) return;
     fs.writeFileSync(path.join(EXT_DIR, `${name}.ts`), `export { default } from ${JSON.stringify(pathToFileURL(target).href)};\n`);
+  };
 
   shim("privateer-brand", ext("privateer-brand.ts"));       // banner, ⚓ badge, /signin /signout
   shim("privateer-context", ext("privateer-context.ts"));   // PRIVATEER.md context + /init
@@ -154,12 +171,21 @@ else {
   shim("privateer-posture", ext("privateer-posture.ts"));
   shim("privateer-tools", ext("privateer-tools.ts"));
   shim("privateer-privacy", ext("privateer-privacy.ts"));   // pi-privacy + account tier resolver
-  shim("rpiv-web-tools", dep("@juicesharp", "rpiv-web-tools", "index.ts")); // private web tools
+  shim("rpiv-web-tools", dep("@juicesharp/rpiv-web-tools", "index.ts")); // private web tools
   shim("pi-mcp-adapter", dep("pi-mcp-adapter", "index.ts"));
-  shim("pi-hypa", dep("@hypabolic", "pi-hypa", "extensions", "index.ts"));
+  shim("pi-hypa", dep("@hypabolic/pi-hypa", "extensions", "index.ts"));
   shim("pi-subagents", dep("pi-subagents", "src", "extension", "index.ts"));
 
-  const CLI = dep("@earendil-works", "pi-coding-agent", "dist", "cli.js");
+  // Unlike the tool packs above, Pi's CLI is not optional — it IS the agent. If it
+  // didn't resolve, the install is broken; say so instead of spawning `undefined`.
+  const CLI = dep("@earendil-works/pi-coding-agent", "dist", "cli.js");
+  if (!CLI || !fs.existsSync(CLI)) {
+    console.error(
+      "privateer: couldn't find pi-coding-agent — the install looks incomplete.\n" +
+        "  Try reinstalling: npm install -g privateer-agent@latest",
+    );
+    process.exit(1);
+  }
   process.env.PI_CODING_AGENT_DIR = AGENT_DIR;
   // The binary pi-subagents spawns for each child. Point it at OUR cli.js so the child
   // reads this same PI_CODING_AGENT_DIR and DISCOVERS the moat shims (gated + private,
@@ -286,6 +312,23 @@ function findWindowsBash() {
   return null;
 }
 
+// Run the patch applier and, on the one interesting outcome (we tried and couldn't),
+// tell the user why in a way they can act on. "current"/"applied"/"skipped" are silent.
+function ensurePatches() {
+  if (applyPatchesIfNeeded(REPO, NODE_BIN) !== "failed") return;
+  process.stderr.write(
+    [
+      "",
+      "  ⚓ Couldn't apply Privateer's bundled patches to node_modules — continuing without them.",
+      "     Two upstream fixes (retry-loop guard, /model → /models redirect) stay off.",
+      `     Usually a permissions issue: ${path.join(REPO, "node_modules")} isn't writable`,
+      "     by this user (a `sudo npm install -g` install). Re-run once with sudo, or",
+      "     install without sudo (nvm, or an npm prefix you own) to fix it for good.",
+      "",
+    ].join("\n") + "\n",
+  );
+}
+
 function haveTinfoilKey() {
   return haveKey("TINFOIL_API_KEY");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,10 @@
     "type": "git",
     "url": "git+https://github.com/privateer-agent/privateer-agent.git"
   },
+  "homepage": "https://privateer.pro",
+  "bugs": {
+    "url": "https://github.com/privateer-agent/privateer-agent/issues"
+  },
   "keywords": [
     "ai",
     "coding-agent",
@@ -39,6 +43,7 @@
     "extensions",
     "skills",
     "patches",
+    "SECURITY.md",
     "README.md",
     "LICENSE"
   ],
@@ -48,8 +53,7 @@
     "channels": "node --env-file=.env --import tsx src/channels/run.ts",
     "dev": "tsx watch src/main.ts",
     "typecheck": "tsc --noEmit",
-    "test": "for f in tests/*.test.ts; do node --import tsx --test \"$f\" || exit 1; done",
-    "postinstall": "patch-package --error-on-fail"
+    "test": "for f in tests/*.test.ts; do node --import tsx --test \"$f\" || exit 1; done"
   },
   "engines": {
     "node": ">=22.19.0"

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/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";
@@ -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;
@@ -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 */ }

package/src/remote/mcpControl.ts

@@ -0,0 +1,268 @@
+/**
+ * MCP connector management for the app — the sibling of channelsControl.ts, but for
+ * MCP server config rather than messaging channels. It is what lets the phone/web
+ * client add, toggle, and remove MCP connectors on a Node HOST it drives over the
+ * relay (the daemon today; an interactive terminal by the same shape).
+ *
+ * The client itself can NEVER run MCP — a browser tab / RN runtime can't spawn a
+ * stdio child or hold the adapter. So "serving MCP to phone/web" means MANAGING the
+ * config here, on a host that executes it. This control owns that config.
+ *
+ * SAME FILE MODEL AS THE DESKTOP (treeview/desktop/src/main/mcpService.ts): the
+ * source of truth is `${agentDir}/mcp-desktop.json` — every server with an `enabled`
+ * flag — and from it we PROJECT the standard `${agentDir}/mcp.json` (enabled servers
+ * only, `{mcpServers:{}}` shape) that pi-mcp-adapter reads. Sharing those two files
+ * means a machine has ONE coherent MCP config whether it was edited from the desktop
+ * over IPC or from the phone over the relay.
+ *
+ * SECRETS: MCP env values are credentials (GITHUB_PERSONAL_ACCESS_TOKEN, …). Over the
+ * untrusted relay they are WRITE-ONLY, exactly like channel bot tokens: list() NEVER
+ * returns an env VALUE — only which env keys exist (`envKeys`) and which are non-empty
+ * (`secretsSet`), by name. save() persists whatever env VALUES it is handed in
+ * `draft.env`; the seal/open of those values in transit is the caller's job (the
+ * daemon opens a sealed-box addressed to its terminal, mirroring applyChannelSave), so
+ * this module only ever deals in the plaintext files it already owns.
+ *
+ * Framework-agnostic: nothing here imports React or the relay. The caller owns the
+ * frame plumbing and the sealed-secret open.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { agentDir } from "../config/paths.ts";
+
+export type McpTransport = "stdio" | "http";
+
+// One server as stored in the source file (mcp-desktop.json). Mirrors the desktop's
+// SourceEntry: the standard fields the adapter needs plus our `enabled` flag.
+interface SourceEntry {
+  transport?: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  oauth?: boolean;
+  enabled?: boolean;
+}
+interface SourceFile {
+  servers: Record<string, SourceEntry>;
+}
+
+// Non-secret projection of one server, sent to the app. No env VALUES, ever — only
+// which env keys exist and which are set (`secretsSet`). `host` is surfaced for the
+// app's privacy badge ("Sends data to <host>" for http; stdio runs locally).
+export interface RemoteMcpServer {
+  name: string;
+  transport: McpTransport;
+  enabled: boolean;
+  command?: string; // stdio: the launch binary (not a secret — e.g. "npx")
+  argsPreview?: string; // stdio: args joined, for a one-line summary
+  url?: string; // http: the endpoint (not a secret; the vendor host)
+  host?: string; // http: parsed host for the privacy badge
+  oauth: boolean; // http servers negotiate OAuth; stdio never does
+  envKeys: string[]; // env var NAMES only (e.g. ["GITHUB_PERSONAL_ACCESS_TOKEN"])
+  secretsSet: string[]; // subset of envKeys whose value is non-empty — names only
+}
+
+// An app-submitted edit. Non-secret fields REPLACE when present; `env` maps a var
+// name → its (already-opened) value, and only present, non-empty values overwrite —
+// an omitted key keeps the existing value (so a re-save without re-typing the token
+// preserves it, matching the channels-manager rule).
+export interface McpDraft {
+  name: string;
+  transport?: McpTransport;
+  command?: string;
+  args?: string[];
+  url?: string;
+  oauth?: boolean;
+  env?: Record<string, string>;
+}
+
+export interface McpControl {
+  // Every managed server, non-secret projection. Enabled or not — the app shows
+  // disabled connectors so they can be toggled back on.
+  list(): RemoteMcpServer[];
+  // Create or edit a server. Validates transport ⟷ required field (stdio→command,
+  // http→url). Returns a one-line result. Re-projects mcp.json on success.
+  save(draft: McpDraft): { ok: boolean; message?: string };
+  // Enable/disable a server (re-projects). ok:false when the name is unknown.
+  setEnabled(name: string, enabled: boolean): { ok: boolean; message?: string };
+  // Delete a server entirely (re-projects). ok:false when nothing was configured.
+  remove(name: string): { ok: boolean; message?: string };
+}
+
+const TRANSPORTS: readonly McpTransport[] = ["stdio", "http"];
+function isTransport(v: unknown): v is McpTransport {
+  return typeof v === "string" && TRANSPORTS.includes(v as McpTransport);
+}
+
+function hostOf(url: string): string | undefined {
+  try {
+    return new URL(url).host || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function cleanArgs(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  return v.map((x) => String(x ?? "")).filter((s) => s.length > 0);
+}
+
+export function makeMcpControl(opts?: {
+  // Override the source/projection dir (tests). Defaults to the shared agent dir, so
+  // this control and the desktop's mcpService edit the SAME two files.
+  dir?: () => string;
+}): McpControl {
+  const dir = opts?.dir ?? agentDir;
+  const sourcePath = () => join(dir(), "mcp-desktop.json");
+  const projectionPath = () => join(dir(), "mcp.json");
+
+  function readSource(): SourceFile {
+    // Seed from an existing standard mcp.json on first run (a machine that already
+    // had connectors before this control existed), so nothing is silently dropped.
+    try {
+      const raw = JSON.parse(readFileSync(sourcePath(), "utf8"));
+      if (raw && typeof raw === "object" && raw.servers) return { servers: raw.servers };
+    } catch {
+      /* fall through to seed */
+    }
+    const servers: Record<string, SourceEntry> = {};
+    try {
+      const proj = JSON.parse(readFileSync(projectionPath(), "utf8"));
+      for (const [name, entry] of Object.entries(proj?.mcpServers ?? {})) {
+        servers[name] = { ...(entry as SourceEntry), enabled: true };
+      }
+    } catch {
+      /* no prior config */
+    }
+    return { servers };
+  }
+
+  function writeSource(src: SourceFile): void {
+    mkdirSync(dirname(sourcePath()), { recursive: true });
+    writeFileSync(sourcePath(), JSON.stringify(src, null, 2) + "\n");
+    project(src);
+  }
+
+  // Project the enabled servers into the standard mcp.json the adapter reads. An
+  // entry with no explicit transport is treated as stdio if it has a command, http
+  // if it has a url — matching the adapter's own inference.
+  function project(src: SourceFile): void {
+    const mcpServers: Record<string, unknown> = {};
+    for (const [name, e] of Object.entries(src.servers)) {
+      if (e.enabled === false) continue;
+      const { enabled, ...std } = e;
+      mcpServers[name] = std;
+    }
+    mkdirSync(dirname(projectionPath()), { recursive: true });
+    writeFileSync(projectionPath(), JSON.stringify({ mcpServers }, null, 2) + "\n");
+  }
+
+  function toRemote(name: string, e: SourceEntry): RemoteMcpServer {
+    const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
+    const env = e.env ?? {};
+    const envKeys = Object.keys(env);
+    return {
+      name,
+      transport,
+      enabled: e.enabled !== false,
+      command: transport === "stdio" ? e.command : undefined,
+      argsPreview: transport === "stdio" && e.args?.length ? e.args.join(" ") : undefined,
+      url: transport === "http" ? e.url : undefined,
+      host: transport === "http" && e.url ? hostOf(e.url) : undefined,
+      // http servers negotiate OAuth; stdio never does (matches mcpService.list()).
+      oauth: transport === "http",
+      envKeys,
+      secretsSet: envKeys.filter((k) => String(env[k] ?? "").length > 0),
+    };
+  }
+
+  return {
+    list(): RemoteMcpServer[] {
+      const src = readSource();
+      return Object.entries(src.servers).map(([name, e]) => toRemote(name, e));
+    },
+
+    save(draft: McpDraft): { ok: boolean; message?: string } {
+      const name = String(draft?.name ?? "").trim();
+      if (!name) return { ok: false, message: "A connector needs a name." };
+      if (draft.transport !== undefined && !isTransport(draft.transport))
+        return { ok: false, message: "Unknown transport." };
+
+      const src = readSource();
+      const prev: SourceEntry = src.servers[name] ?? {};
+      const entry: SourceEntry = { ...prev };
+
+      const transport: McpTransport =
+        (draft.transport as McpTransport) ?? prev.transport ?? (draft.url || prev.url ? "http" : "stdio");
+      entry.transport = transport;
+
+      if (transport === "stdio") {
+        if (draft.command !== undefined) entry.command = String(draft.command).trim();
+        const args = cleanArgs(draft.args);
+        if (args !== undefined) entry.args = args;
+        // A stdio server can't reach a url and never does OAuth — clear stale fields.
+        delete entry.url;
+        delete entry.oauth;
+        if (!entry.command) return { ok: false, message: "A local (stdio) connector needs a command." };
+      } else {
+        if (draft.url !== undefined) entry.url = String(draft.url).trim();
+        if (draft.oauth !== undefined) entry.oauth = !!draft.oauth;
+        delete entry.command;
+        delete entry.args;
+        if (!entry.url) return { ok: false, message: "A remote (http) connector needs a URL." };
+      }
+
+      // Env/secrets: a present, non-empty value overwrites; an omitted key keeps the
+      // existing value (re-save without re-typing the token preserves it). An explicit
+      // empty string clears that key.
+      if (draft.env !== undefined) {
+        const merged: Record<string, string> = { ...(prev.env ?? {}) };
+        for (const [k, v] of Object.entries(draft.env)) {
+          const key = String(k).trim();
+          if (!key) continue;
+          const val = String(v ?? "");
+          if (val.length > 0) merged[key] = val;
+          else delete merged[key];
+        }
+        if (Object.keys(merged).length > 0) entry.env = merged;
+        else delete entry.env;
+      }
+
+      // A brand-new server comes up enabled; an edit preserves the prior flag.
+      entry.enabled = prev.enabled ?? true;
+
+      src.servers[name] = entry;
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Saved "${name}".` };
+    },
+
+    setEnabled(name: string, enabled: boolean): { ok: boolean; message?: string } {
+      const src = readSource();
+      if (!src.servers[name]) return { ok: false, message: "No such connector." };
+      src.servers[name].enabled = !!enabled;
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `${enabled ? "Enabled" : "Disabled"} "${name}".` };
+    },
+
+    remove(name: string): { ok: boolean; message?: string } {
+      const src = readSource();
+      if (!src.servers[name]) return { ok: false, message: "Not configured." };
+      delete src.servers[name];
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Removed "${name}".` };
+    },
+  };
+}

package/src/remote/relayClient.ts

@@ -182,6 +182,22 @@ export interface RelayCallbacks {
   // The app asked to delete a platform's channel config, by platform name. Signed
   // (H2) — a forged removal is a DoS (the bot stops until re-added).
   onChannelsRemove?: (platform: string, sig?: string, ts?: number) => void;
+  // The app opened the MCP connectors manager — reply with the current MCP config
+  // (a sendMcp frame). Owned by the daemon (the host that runs the adapter), so these
+  // only fire on its relay. Read-only, so unsigned.
+  onMcpList?: () => void;
+  // The app asked to create/edit an MCP connector. `draft` carries only NON-secret
+  // fields (name/transport/command/args/url/oauth). `sealedSecrets`, when present, is
+  // a base64 sealed-box the app sealed to THIS terminal's pinned pubkey, opening to
+  // `{ termId, env: {NAME: value} }` — the connector's credential env. `sig`+`ts`
+  // authenticate the WHOLE save with the pinned account key (same shape as
+  // channels_save), so a hostile relay can neither forge a token nor inject a command.
+  onMcpSave?: (draft: Record<string, unknown>, sealedSecrets?: string, sig?: string, ts?: number) => void;
+  // The app asked to enable/disable a connector by name. Signed (H2) — a forged toggle
+  // silently arms/disarms a tool surface. Idempotent (non-strict ts).
+  onMcpSetEnabled?: (name: string, enabled: boolean, sig?: string, ts?: number) => void;
+  // The app asked to delete a connector by name. Signed (H2) — a forged removal is a DoS.
+  onMcpRemove?: (name: string, sig?: string, ts?: number) => void;
   // The app opened the workflows manager — reply with the current workflow summaries
   // (a sendWorkflows frame). Owned by the daemon, so these only fire on its relay.
   onWorkflowsList?: () => void;
@@ -519,6 +535,27 @@ export class RelayClient {
       case "channels_remove":
         if (typeof frame.platform === "string") this.cb.onChannelsRemove?.(frame.platform, sig(frame), tsOf(frame));
         break;
+      case "mcp_list":
+        this.cb.onMcpList?.();
+        break;
+      case "mcp_save":
+        // The connector rides in `draft` (same slot as channels_save), untyped — the
+        // daemon strict-validates it via mcpControl.save after the signature check.
+        if (frame.draft && typeof frame.draft === "object") {
+          this.cb.onMcpSave?.(
+            frame.draft,
+            typeof frame.sealedSecrets === "string" ? frame.sealedSecrets : undefined,
+            sig(frame),
+            tsOf(frame),
+          );
+        }
+        break;
+      case "mcp_set_enabled":
+        if (typeof frame.name === "string") this.cb.onMcpSetEnabled?.(frame.name, frame.enabled === true, sig(frame), tsOf(frame));
+        break;
+      case "mcp_remove":
+        if (typeof frame.name === "string") this.cb.onMcpRemove?.(frame.name, sig(frame), tsOf(frame));
+        break;
       case "workflows_list":
         this.cb.onWorkflowsList?.();
         break;
@@ -875,6 +912,47 @@ export class RelayClient {
     });
   }
 
+  // Push the host's MCP connectors to the app's MCP manager. Sent on request and after
+  // each save/set_enabled/remove. Like sendChannels this is the user's OWN config echoed
+  // to their OWN app — but an env VALUE (a token) NEVER crosses this wire: only `envKeys`
+  // (names) and `secretsSet` (which of those are non-empty, by name) are sent, so a relay
+  // / server compromise can't lift a credential from this frame. List bounded like the
+  // other managers.
+  sendMcp(payload: {
+    items: {
+      name: string;
+      transport: string;
+      enabled: boolean;
+      command?: string;
+      argsPreview?: string;
+      url?: string;
+      host?: string;
+      oauth: boolean;
+      envKeys: string[];
+      secretsSet: string[];
+    }[];
+    busy?: boolean;
+    message?: string;
+  }): void {
+    this.rawSend({
+      type: "mcp",
+      items: payload.items.slice(0, 50).map((m) => ({
+        name: clip(String(m.name), 128),
+        transport: m.transport === "http" ? "http" : "stdio",
+        enabled: !!m.enabled,
+        command: m.command ? clip(m.command, 200) : undefined,
+        argsPreview: m.argsPreview ? clip(m.argsPreview, 500) : undefined,
+        url: m.url ? clip(m.url, 500) : undefined,
+        host: m.host ? clip(m.host, 200) : undefined,
+        oauth: !!m.oauth,
+        envKeys: (m.envKeys ?? []).slice(0, 30).map((k) => clip(String(k), 128)),
+        secretsSet: (m.secretsSet ?? []).slice(0, 30).map((k) => clip(String(k), 128)),
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? clip(payload.message, 500) : undefined,
+    });
+  }
+
   // Push the daemon's saved workflows to the app's workflows manager as SUMMARIES (not
   // the full graphs — the editor fetches one at a time via sendWorkflow). Sent on request
   // and after each save/remove/run. The user's OWN config echoed to their OWN app, so

package/src/remote/remoteBridge.ts

@@ -158,6 +158,13 @@ export class RemoteBridge {
     onChannelsList: () => {},
     onChannelsSave: () => {},
     onChannelsRemove: () => {},
+    // MCP connectors, like channels, are managed on the daemon (the host that runs the
+    // adapter) — the daemon's own relay handles mcp_*. These no-ops just satisfy Required;
+    // an interactive terminal manages MCP over IPC (desktop), never over this relay.
+    onMcpList: () => {},
+    onMcpSave: () => {},
+    onMcpSetEnabled: () => {},
+    onMcpRemove: () => {},
     // Workflows, like routines/channels, are daemon-owned — the daemon's own relay handles
     // workflows_*. These no-ops just satisfy Required; an interactive terminal never
     // surfaces workflows.

package/src/routines/schema.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { z } from "zod";
 
 // Where a routine's result is delivered after it runs. `file`/`relay`/`notice` stay
@@ -79,6 +80,13 @@ export const RoutineFile = z.object({
 export type RoutineFile = z.infer<typeof RoutineFile>;
 
 // A time-ordered routine id minted once at creation.
+//
+// The random suffix is load-bearing, not decoration. This was `r-${Date.now()}` alone,
+// so two routines created in the SAME MILLISECOND got the same id — and upsertRoutine
+// keys on id, so the second silently overwrote the first. Creating routines in quick
+// succession (an import, a scripted setup, a fast tap-tap in the app) could therefore
+// lose one with no error anywhere. The timestamp prefix still sorts by creation order;
+// the suffix just makes collisions vanishingly unlikely.
 export function newRoutineId(): string {
-  return `r-${Date.now()}`;
+  return `r-${Date.now()}-${randomBytes(4).toString("hex")}`;
 }