privateer-agent 0.6.10 → 0.8.0

package/src/providers/sealedShim.ts

@@ -0,0 +1,295 @@
+// Sealed-mode (EHBP) transport for the account channel.
+//
+// Background: the `privateer` provider runs inference through the server at
+// `${server}/api/agent/v1`, which reads the prompt in cleartext (it assembles/
+// forwards the body). For `tinfoil/*` models that means the badge honestly reads
+// "Trusted Execution (unconfirmed)": the enclave is real, but a quote fetched
+// through the proxy can't be bound to THIS connection (see account.ts and
+// docs/tee-privateer-tinfoil-ehbp.md).
+//
+// Sealed mode closes that. Tinfoil's EHBP (Encrypted HTTP Body Protocol) is HPKE
+// applied to the HTTP body only, independent of TLS, and the enclave's attestation
+// binds the HPKE key. The Privateer server already exposes a blind relay for it
+// (`${server}/api/sealed/:provider`, treeview/server/routes/sealed.js): it forwards
+// the ciphertext body + the `Ehbp-*` headers, injects the provider key, and meters
+// on a cleartext usage header — it never sees the prompt. The treeview app already
+// speaks this (client/services/pipeline/transport/tinfoilProvider.ts).
+//
+// Pi's `openai-completions` adapter does the HTTP itself and exposes no custom-fetch
+// hook, so we can't seal from inside the provider config. Instead we run an
+// in-process loopback HTTP server (this module): Pi POSTs a plain OpenAI request to
+// it, the shim seals the body to the attested enclave via Tinfoil's `SecureClient`,
+// forwards Pi's account bearer + the cleartext `X-Sealed-Model` billing header, and
+// streams the decrypted response back. The provider points the `tinfoil/*` models'
+// per-model `baseUrl` at this shim (account.ts).
+//
+// The one SecureClient per provider is shared by the data plane (the shim) and the
+// posture check (attestSealed), so the green shield reflects the exact client that
+// carries the tokens — the invariant: attest the key we actually seal to.
+
+import http from "node:http";
+import { Readable } from "node:stream";
+import { SecureClient } from "tinfoil";
+import { serverBaseUrl } from "../auth/privateer.ts";
+import { attestPhala, phalaSealedFetch } from "./phalaSeal.ts";
+import { iterateSSE } from "./phala/sse.ts";
+
+// Providers whose enclave supports application-layer body encryption + client-verified
+// attestation, and for which we have a Node client: Tinfoil (EHBP) and Phala (ACI
+// E2EE). NEAR does NOT — it's attested TLS only, so it stays the confidential
+// (unsealed) path, not sealed. See docs/tee-verified-tinfoil-ehbp.md §12.
+export type SealedProvider = "tinfoil" | "phala";
+
+// Sealed mode is OFF until verified end-to-end against a live relay (a real EHBP
+// round-trip needs the deployed relay + TINFOIL_API_KEY; see the live checklist in
+// docs/tee-privateer-tinfoil-ehbp.md). Off = the current plaintext path + honest
+// yellow badge, untouched. Flip with PRIVATEER_SEALED=1.
+export function sealedEnabled(): boolean {
+  const v = process.env.PRIVATEER_SEALED;
+  return v === "1" || v === "true";
+}
+
+// The sealed provider a model id routes through, or null if it isn't a sealed
+// model (or its client isn't available here). Mirrors the server's prefix routing.
+export function sealedProviderFor(modelId: string): SealedProvider | null {
+  if (modelId.startsWith("tinfoil/")) return "tinfoil";
+  if (modelId.startsWith("phala/")) return "phala";
+  return null;
+}
+
+// The blind-relay base for a provider — SecureClient fetches `${base}/attestation`
+// and we POST `${base}/v1/chat/completions`.
+export function relayBase(provider: SealedProvider): string {
+  return `${serverBaseUrl().replace(/\/+$/, "")}/api/sealed/${provider}`;
+}
+
+// ── One SecureClient per provider (shared: data plane + posture) ──────────────
+
+const clients = new Map<SealedProvider, SecureClient>();
+const readyPromises = new Map<SealedProvider, Promise<void>>();
+
+function client(provider: SealedProvider): SecureClient {
+  let c = clients.get(provider);
+  if (!c) {
+    const base = relayBase(provider);
+    // attestationBundleURL == base: the SDK appends `/attestation`, which the relay
+    // proxies to Tinfoil's ATC. transport 'ehbp' = HPKE body sealing.
+    c = new SecureClient({ baseURL: base, attestationBundleURL: base, transport: "ehbp" });
+    clients.set(provider, c);
+  }
+  return c;
+}
+
+// Attest once and cache; on failure drop the memo so a later call re-attests
+// rather than caching the error (mirrors the treeview provider).
+export function ready(provider: SealedProvider): Promise<void> {
+  let p = readyPromises.get(provider);
+  if (!p) {
+    p = client(provider)
+      .ready()
+      .catch((err) => {
+        readyPromises.delete(provider);
+        throw err as Error;
+      });
+    readyPromises.set(provider, p);
+  }
+  return p;
+}
+
+export interface SealedAttestation {
+  ok: boolean;
+  enclave?: string;
+  error?: string;
+}
+
+// Drive the provider's client-side attestation (the SAME client/keyset the shim
+// seals with). A green result is a quote we verified ourselves, bound to the key we
+// encrypt to — that earns tee-verified. Tinfoil: SecureClient.ready() (HPKE-key
+// match). Phala: verifyReportBinding + TDX quote (see phalaSeal.ts).
+export async function attestSealed(provider: SealedProvider): Promise<SealedAttestation> {
+  if (provider === "phala") return attestPhala();
+  try {
+    await ready(provider);
+    return { ok: true, enclave: client(provider).getEnclaveURL() };
+  } catch (e) {
+    return { ok: false, error: (e as Error).message };
+  }
+}
+
+// ── Pure request shaping (unit-tested without an enclave) ─────────────────────
+
+export interface ForwardPlan {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  sealedModel: string;
+}
+
+// Turn Pi's plain OpenAI request into what we seal to the relay:
+//   - strip the `${provider}/` prefix from the body model (the enclave wants the
+//     bare id; the body is encrypted so the relay can't strip it — we must),
+//   - keep the full prefixed id on the cleartext X-Sealed-Model header (the relay
+//     prices billing off it — it never reads the body),
+//   - forward Pi's account bearer verbatim (the relay authenticates the JWT; on a
+//     401 the relay's response propagates so Pi refreshes and retries).
+export function buildForward(
+  provider: SealedProvider,
+  rawBody: string,
+  authHeader: string | undefined,
+): ForwardPlan {
+  let body = rawBody;
+  let sealedModel = "unknown";
+  try {
+    const parsed = JSON.parse(rawBody);
+    if (parsed && typeof parsed.model === "string") {
+      sealedModel = parsed.model;
+      const prefix = `${provider}/`;
+      if (parsed.model.startsWith(prefix)) parsed.model = parsed.model.slice(prefix.length);
+      body = JSON.stringify(parsed);
+    }
+  } catch {
+    // Not JSON — forward unchanged (X-Sealed-Model stays "unknown"; relay logs it).
+  }
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Sealed-Model": sealedModel,
+  };
+  if (authHeader) headers.Authorization = authHeader;
+  return { url: `${relayBase(provider)}/v1/chat/completions`, headers, body, sealedModel };
+}
+
+// ── Loopback HTTP shim ────────────────────────────────────────────────────────
+
+const PATH_RE = /^\/(tinfoil|phala)\/v1\/chat\/completions$/;
+const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+
+let shimBase: string | null = null;
+let shimStarting: Promise<string> | null = null;
+
+// The shim's base URL once listening, else null. account.ts reads this to decide
+// whether a sealed model can point its baseUrl at the shim yet.
+export function sealedShimBase(): string | null {
+  return shimBase;
+}
+
+// Start the loopback shim once and return its base URL. Idempotent.
+export function ensureSealedShim(): Promise<string> {
+  if (shimBase) return Promise.resolve(shimBase);
+  if (!shimStarting) shimStarting = startShim();
+  return shimStarting;
+}
+
+function startShim(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      void handle(req, res).catch((e) => {
+        if (!res.headersSent) res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: { message: `sealed shim: ${(e as Error).message}` } }));
+      });
+    });
+    server.on("error", reject);
+    // Loopback only, ephemeral port. unref so the shim never keeps the process alive.
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        shimBase = `http://127.0.0.1:${addr.port}`;
+        resolve(shimBase);
+      } else {
+        reject(new Error("sealed shim: could not determine listen port"));
+      }
+    });
+    server.unref();
+  });
+}
+
+async function handle(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+  // Defense in depth: only serve loopback peers (the port is ephemeral + bound to
+  // 127.0.0.1 already, but reject anything else outright).
+  if (!LOOPBACK.has(req.socket.remoteAddress ?? "")) {
+    res.writeHead(403).end();
+    return;
+  }
+  const path = (req.url ?? "").split("?")[0];
+  const m = PATH_RE.exec(path);
+  if (req.method !== "POST" || !m) {
+    res.writeHead(404).end();
+    return;
+  }
+  const provider = m[1] as SealedProvider;
+  const raw = await readBody(req);
+  const authHeader = typeof req.headers["authorization"] === "string" ? req.headers["authorization"] : undefined;
+
+  if (provider === "phala") {
+    await handlePhala(raw.toString("utf8"), authHeader, res);
+    return;
+  }
+
+  // Tinfoil (EHBP): SecureClient.fetch seals/opens transparently, so we just pass the
+  // body through and pipe the decrypted response.
+  const plan = buildForward(provider, raw.toString("utf8"), authHeader);
+  await ready(provider);
+  const upstream = await client(provider).fetch(plan.url, {
+    method: "POST",
+    headers: plan.headers,
+    body: plan.body,
+  });
+
+  res.writeHead(upstream.status, {
+    "Content-Type": upstream.headers.get("content-type") ?? "application/json",
+  });
+  if (upstream.body) {
+    const nodeStream = Readable.fromWeb(upstream.body as Parameters<typeof Readable.fromWeb>[0]);
+    // If Pi hangs up mid-stream, stop pulling from the enclave.
+    res.on("close", () => nodeStream.destroy());
+    nodeStream.pipe(res);
+    nodeStream.on("error", () => {
+      if (!res.writableEnded) res.end();
+    });
+  } else {
+    res.end(await upstream.text());
+  }
+}
+
+// Phala (ACI E2EE): fields are encrypted individually, so unlike Tinfoil we must
+// decrypt the response with the per-call channel — chunk by chunk for SSE, or the
+// whole JSON when non-streaming — and re-emit cleartext OpenAI to Pi.
+async function handlePhala(
+  rawBody: string,
+  authHeader: string | undefined,
+  res: http.ServerResponse,
+): Promise<void> {
+  const ac = new AbortController();
+  res.on("close", () => ac.abort());
+  const { res: up, channel, streaming } = await phalaSealedFetch(rawBody, authHeader, ac.signal);
+
+  if (!up.ok) {
+    res.writeHead(up.status, { "Content-Type": up.headers.get("content-type") ?? "application/json" });
+    res.end(await up.text());
+    return;
+  }
+
+  if (streaming && up.body) {
+    res.writeHead(up.status, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" });
+    for await (const obj of iterateSSE(up.body as ReadableStream<Uint8Array>)) {
+      const opened = await channel.openChunk(obj as Record<string, unknown>);
+      res.write(`data: ${JSON.stringify(opened)}\n\n`);
+    }
+    res.write("data: [DONE]\n\n");
+    res.end();
+    return;
+  }
+
+  // Non-streaming: decrypt the single JSON body.
+  const opened = await channel.open((await up.json()) as Record<string, unknown>);
+  res.writeHead(up.status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(opened));
+}
+
+function readBody(req: http.IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}

package/src/remote/channelsControl.ts

@@ -3,13 +3,13 @@
  * messaging-channel config (Telegram/Slack/Discord/WhatsApp) rather than scheduled
  * routines.
  *
- * Like routines, this is owned by the ALWAYS-ON daemon relay (daemon/index.ts),
- * NOT the channels daemon (channels/run.ts) — which may be down, and which the app
+ * Like routines, this is owned by the ALWAYS-ON harbor relay (harbor/index.ts),
+ * NOT the channels harbor (channels/run.ts) — which may be down, and which the app
  * must be able to configure before it has ever run. So this control edits the
- * `channels` block of ~/.privateer/config.json; the channels daemon adopts changes
+ * `channels` block of ~/.privateer/config.json; the channels harbor adopts changes
  * on its next RESTART, matching run.ts's deliberate "no in-chat toggle, restart is
  * the fail-safe reset" posture. `running` is a best-effort read of the channels
- * daemon's heartbeat (channels/status.ts), never a dependency.
+ * harbor's heartbeat (channels/status.ts), never a dependency.
  *
  * SECRETS: bot tokens are WRITE-ONLY from the app's perspective. list() NEVER
  * returns a token value — it reports `configured`, `running`, and `secretsSet`
@@ -46,7 +46,7 @@ const SECRET_FIELDS: Record<ChannelPlatform, string[]> = {
 export interface RemoteChannel {
   platform: ChannelPlatform;
   configured: boolean; // a config block exists for this platform
-  running: boolean; // the channels daemon is currently serving it
+  running: boolean; // the channels harbor is currently serving it
   adminCount: number;
   memberCount: number;
   posture: ChannelPosture;
@@ -94,7 +94,7 @@ function cleanStrList(v: unknown): string[] | undefined {
 }
 
 export function makeChannelsControl(opts: {
-  // Which platforms the channels daemon is serving right now (heartbeat read).
+  // Which platforms the channels harbor is serving right now (heartbeat read).
   // Absent → everything reports not-running.
   runningPlatforms?: () => Set<string>;
 }): ChannelsControl {
@@ -173,7 +173,7 @@ export function makeChannelsControl(opts: {
       } catch (e) {
         return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
       }
-      return { ok: true, message: `Saved ${draft.platform}. Restart the channels daemon to apply.` };
+      return { ok: true, message: `Saved ${draft.platform}. Restart the channels harbor to apply.` };
     },
 
     remove(platform: ChannelPlatform): { ok: boolean; message?: string } {
@@ -186,7 +186,7 @@ export function makeChannelsControl(opts: {
       } catch (e) {
         return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
       }
-      return { ok: true, message: `Removed ${platform}. Restart the channels daemon to apply.` };
+      return { ok: true, message: `Removed ${platform}. Restart the channels harbor to apply.` };
     },
   };
 }

package/src/remote/controlAuth.ts

@@ -9,7 +9,7 @@
 // skill). channels_save has its own bespoke verify (it also carries sealed secrets);
 // everything else routes through here.
 //
-// Both loci call this: the daemon (routines_*/channels_remove, termId = routineRelayId)
+// Both loci call this: the harbor (routines_*/channels_remove, termId = routineRelayId)
 // and each interactive terminal (extensions_*/skills_*, termId = the relay's id).
 //
 // Fail-closed: no pinned account key, a missing signature, a bad signature, or a stale

package/src/remote/liveTaskSession.ts

@@ -1,9 +1,9 @@
-// A live, app-drivable agent session spawned on demand by the daemon (task_spawn,
-// mode:"live"). Unlike a headless task (daemon/index.ts runTask → restricted tools +
+// A live, app-drivable agent session spawned on demand by the harbor (task_spawn,
+// mode:"live"). Unlike a headless task (harbor/index.ts runTask → restricted tools +
 // bypass gate + outbox), this stands up a FULL interactive session behind its own relay
 // terminal so the app can attach and drive it in real time: stream tokens, approve each
 // tool, interrupt. It is the same wiring cli/chat.ts uses for `/remote-access`, factored
-// so the daemon can create one without a TTY.
+// so the harbor can create one without a TTY.
 //
 // SAFETY: the gate runs in "default" mode, so on a driven turn every gated tool relays to
 // the app for allow/deny (bridge.remoteAsk) and fail-closes if the controller is gone —
@@ -20,10 +20,10 @@ import { agentVersion } from "../config/version.ts";
 import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
 import { makePermissionGate, isRemoteUnsafeTool, type GateController } from "../ext/permissionGate.ts";
 import { makePiPrivacyExtension } from "pi-privacy";
-import { makeAccountProvider } from "../providers/account.ts";
+import { makeAccountProvider, privateerChannel } from "../providers/account.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
-import { spawnAccountCredentials, revokeAccountSession } from "../auth/privateer.ts";
+import { spawnAccountCredentials, revokeAccountSession, hasCredentials } from "../auth/privateer.ts";
 
 export interface LiveTaskHandle {
   termId: string;
@@ -70,7 +70,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     if (lifeTimer) clearTimeout(lifeTimer);
     try { relay?.stop(); } catch { /* already stopped */ }
     // Revoke ONLY this session's account inference session so it doesn't linger in the
-    // app's Linked Devices; the daemon's own child session stays alive. Best-effort.
+    // app's Linked Devices; the harbor's own child session stays alive. Best-effort.
     if (spawnedAccount) {
       try { await revokeAccountSession(); } catch { /* server TTL is the fallback */ }
       try { servicesRef?.authStorage?.remove?.("privateer"); } catch { /* nothing persisted */ }
@@ -138,7 +138,15 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     cwd,
     agentDir: agentDir(),
     resourceLoaderOptions: {
-      extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+      extensionFactories: [
+        makePermissionGate(gate),
+        // Per-model verified-TEE label for the /models picker (see harbor/index.ts):
+        // TEE-channel Privateer models verify on select when logged in; ZDR stays floored.
+        makePiPrivacyExtension({
+          privateerVerifiedTee: (m) => hasCredentials() && privateerChannel(m.id ?? "") === "tee",
+        }),
+        makeAccountProvider(),
+      ] as any,
     },
   });
   servicesRef = services as any;

package/src/remote/mcpControl.ts

@@ -2,7 +2,7 @@
  * 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).
+ * relay (the harbor 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
@@ -20,7 +20,7 @@
  * 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
+ * harbor 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

package/src/remote/relayClient.ts

@@ -45,7 +45,7 @@ function tsOf(frame: { ts?: unknown }): number | undefined {
 }
 
 // Parse a task_submit/task_spawn frame into a TaskSpec, keeping ONLY well-typed,
-// present fields (absent → left undefined). The daemon re-derives the canonical signed
+// present fields (absent → left undefined). The harbor re-derives the canonical signed
 // args from this (taskControlArgs, undefined → null), so it must not invent fields.
 export function parseTaskSpec(frame: {
   prompt?: string;
@@ -79,10 +79,10 @@ function safe(s: string, max: number): string {
   return clip(redactSecrets(s), max);
 }
 
-// An ad-hoc task the app asks the daemon to run headlessly (task_submit) or to spawn
+// An ad-hoc task the app asks the harbor to run headlessly (task_submit) or to spawn
 // as a live-drivable session (task_spawn). Only `prompt` is required; the rest fall back
-// to daemon defaults. The SAME field set is what the app canonical-signs into the control
-// envelope (client/services/accountSign.ts) and the daemon re-derives to verify (index.ts
+// to harbor defaults. The SAME field set is what the app canonical-signs into the control
+// envelope (client/services/accountSign.ts) and the harbor re-derives to verify (index.ts
 // taskControlArgs) — keep the two in sync, byte for byte, like the other signed frames.
 export interface TaskSpec {
   prompt: string;
@@ -99,7 +99,7 @@ export interface RelayCallbacks {
   onInterrupt: () => void;
   // The app asked to turn remote access OFF entirely (the in-app "End remote
   // access" action). The owner should disable /remote-access — i.e. stop this
-  // client and not reconnect. Optional: the routines daemon handles it too, but
+  // client and not reconnect. Optional: the routines harbor handles it too, but
   // callbacks that predate it keep compiling.
   onTerminate?: () => void;
   // The account signed this terminal out server-side (revoked from the app's
@@ -127,6 +127,10 @@ export interface RelayCallbacks {
   // The app answered a CLI-initiated text-input prompt (the id from requestInput).
   // A null value means the app dismissed the prompt without submitting.
   onInputResponse?: (id: string, value: string | null) => void;
+  // The app's composer is autocompleting an `@file` mention — reply with the cwd
+  // files/dirs matching `query` (a sendFileMatches frame, keyed by the same id).
+  // Read-only; resolution of the picked path still happens on the prompt turn.
+  onFilesSearch?: (id: string, query: string) => void;
   // The app opened the extensions manager — reply with the current installed list
   // (a sendExtensions frame). Optional so pre-extensions callbacks keep compiling.
   onExtensionsList?: () => void;
@@ -147,10 +151,10 @@ export interface RelayCallbacks {
   // The app toggled a user skill's model-invocation availability.
   onSkillSetEnabled?: (name: string, enabled: boolean, sig?: string, ts?: number) => void;
   // The app opened the routines manager — reply with the current routines list
-  // (a sendRoutines frame). Owned by the daemon, so these only fire on its relay.
+  // (a sendRoutines frame). Owned by the harbor, so these only fire on its relay.
   onRoutinesList?: () => void;
   // The app asked to create (no id) or edit (id) a routine. The raw draft object is
-  // handed through untyped; the daemon's routinesControl validates it. Signed (H2) —
+  // handed through untyped; the harbor's routinesControl validates it. Signed (H2) —
   // a forged routine runs a headless bypass-mode session (RCE), so it MUST be verified.
   onRoutinesSave?: (draft: Record<string, unknown>, sig?: string, ts?: number) => void;
   // The app asked to delete a routine by id or name.
@@ -163,14 +167,14 @@ export interface RelayCallbacks {
   // right now — a fresh restricted-tool bypass session whose result is sealed to the
   // account outbox. Signed (H2) — a forged task_submit runs an arbitrary headless
   // session (RCE), identical in blast radius to a forged routines_run, so it MUST be
-  // verified via controlAuth before it runs. Daemon-owned (fires only on its relay).
+  // verified via controlAuth before it runs. Harbor-owned (fires only on its relay).
   onTaskSubmit?: (spec: TaskSpec, sig?: string, ts?: number) => void;
   // The app asked to SPAWN a fresh interactive session it can drive live (mode:"live").
-  // The daemon stands up a new RemoteBridge terminal and replies (sendTaskSpawned) with
+  // The harbor stands up a new RemoteBridge terminal and replies (sendTaskSpawned) with
   // its termId so the app can attach. Same signed-RCE gate as task_submit.
   onTaskSpawn?: (spec: TaskSpec, sig?: string, ts?: number) => void;
   // The app opened the channels manager — reply with the current channel config
-  // (a sendChannels frame). Owned by the daemon, so these only fire on its relay.
+  // (a sendChannels frame). Owned by the harbor, so these only fire on its relay.
   onChannelsList?: () => void;
   // The app asked to create/edit a platform's channel config. `draft` carries only
   // NON-secret fields (roles/posture/tools/model). `sealedSecrets`, when present, is
@@ -183,7 +187,7 @@ export interface RelayCallbacks {
   // (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
+  // (a sendMcp frame). Owned by the harbor (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
@@ -199,12 +203,12 @@ export interface RelayCallbacks {
   // 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.
+  // (a sendWorkflows frame). Owned by the harbor, so these only fire on its relay.
   onWorkflowsList?: () => void;
   // The app opened one workflow in its editor — reply with the full graph (sendWorkflow).
   onWorkflowsGet?: (idOrName: string) => void;
   // The app asked to create (no workflow.id) or edit (id) a workflow. The raw graph is
-  // handed through untyped; the daemon's workflowsControl strict-validates it. Signed
+  // handed through untyped; the harbor's workflowsControl strict-validates it. Signed
   // (H2) — a forged save plants a `script` step that BYPASSES the permission gate (RCE),
   // exactly like a forged routine, so it MUST be verified before it persists.
   onWorkflowsSave?: (draft: Record<string, unknown>, sig?: string, ts?: number) => void;
@@ -286,7 +290,7 @@ export class RelayClient {
   private buf = "";
   private flushTimer: ReturnType<typeof setTimeout> | undefined;
   // Stable for this process so reconnects keep the same terminal identity. Callers
-  // may pass a persisted id/label (e.g. the routines daemon, so it shows up as one
+  // may pass a persisted id/label (e.g. the routines harbor, so it shows up as one
   // recognizable "Privateer Routines" terminal across restarts instead of a fresh
   // random one each time).
   private readonly termId: string;
@@ -424,6 +428,7 @@ export class RelayClient {
       title?: string;
       tools?: unknown;
       mode?: string;
+      query?: string;
       sig?: string;
       ts?: number;
     };
@@ -467,6 +472,9 @@ export class RelayClient {
       case "input_response":
         if (frame.id) this.cb.onInputResponse?.(frame.id, typeof frame.value === "string" ? frame.value : null);
         break;
+      case "files_search":
+        if (typeof frame.id === "string") this.cb.onFilesSearch?.(frame.id, typeof frame.query === "string" ? frame.query : "");
+        break;
       case "extensions_list":
         this.cb.onExtensionsList?.();
         break;
@@ -540,7 +548,7 @@ export class RelayClient {
         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.
+        // harbor strict-validates it via mcpControl.save after the signature check.
         if (frame.draft && typeof frame.draft === "object") {
           this.cb.onMcpSave?.(
             frame.draft,
@@ -563,7 +571,7 @@ export class RelayClient {
         if (typeof frame.idOrName === "string") this.cb.onWorkflowsGet?.(frame.idOrName);
         break;
       case "workflows_save":
-        // The graph rides in `draft` (same slot as channels_save), untyped — the daemon
+        // The graph rides in `draft` (same slot as channels_save), untyped — the harbor
         // strict-validates it via workflowsControl.save after the signature check.
         if (frame.draft && typeof frame.draft === "object") this.cb.onWorkflowsSave?.(frame.draft, sig(frame), tsOf(frame));
         break;
@@ -667,7 +675,7 @@ export class RelayClient {
   }
 
   // Push a workflow's live step text / final result to any attached controller as a text
-  // event, so it renders in the daemon terminal's feed. Same durable-copy caveat as
+  // event, so it renders in the harbor terminal's feed. Same durable-copy caveat as
   // sendRoutineResult (the outbox is the source of truth).
   sendWorkflowResult(name: string, content: string): boolean {
     if (!this.isConnected()) return false;
@@ -678,7 +686,7 @@ export class RelayClient {
 
   // Tell the app that a live task session was stood up on `termId` (label for display),
   // so it can open a controller connection to that terminal and drive it. Fire-and-forget
-  // over the daemon's management relay.
+  // over the harbor's management relay.
   sendTaskSpawned(termId: string, label: string): void {
     this.rawSend({ type: "task_spawned", termId, label });
   }
@@ -771,6 +779,18 @@ export class RelayClient {
     });
   }
 
+  // Reply to an `@file` autocomplete query with the matching cwd files/dirs. Keyed by
+  // the query's id so the app can match it to the in-flight request. Bounded; paths are
+  // cwd-relative (the caller — searchFiles — never emits a path outside the cwd subtree,
+  // so no machine location leaks beyond the project filenames the driver is browsing).
+  sendFileMatches(id: string, matches: { path: string; isDir: boolean }[]): void {
+    this.rawSend({
+      type: "file_matches",
+      id,
+      matches: matches.slice(0, 50).map((m) => ({ path: safe(m.path, 300), isDir: !!m.isDir })),
+    });
+  }
+
   // Push the terminal's installed Pi extensions (the user's own packages; the moat
   // is excluded upstream) to the app's extensions manager. Sent on request and after
   // each add/remove. `busy` drives a progress indicator; `needsRestart` tells the app
@@ -823,7 +843,7 @@ export class RelayClient {
     });
   }
 
-  // Push the daemon's saved routines to the app's routines manager. Sent on request
+  // Push the harbor's saved routines to the app's routines manager. Sent on request
   // and after each save/delete/pause/run. `busy` drives a progress indicator;
   // `message` carries a one-line result/error. Unlike the feed/webhook paths this is
   // the user's OWN config echoed back to their OWN app, so fields are size-clipped
@@ -873,7 +893,7 @@ export class RelayClient {
     });
   }
 
-  // Push the daemon's channel config to the app's channels manager. Sent on request
+  // Push the harbor's channel config to the app's channels manager. Sent on request
   // and after each save/remove. Like sendRoutines this is the user's OWN config
   // echoed to their OWN app — but a bot token NEVER crosses this wire: only
   // `secretsSet` (which secret fields are present, by NAME) is sent, so a relay /
@@ -953,7 +973,7 @@ export class RelayClient {
     });
   }
 
-  // Push the daemon's saved workflows to the app's workflows manager as SUMMARIES (not
+  // Push the harbor'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
   // fields are clipped (not redacted). List bounded like the other managers.