privateer-agent 0.1.1 → 0.3.0

package/src/engine/errors.ts

@@ -17,8 +17,11 @@ interface ErrorFacts {
   statusCode?: number;
   providerMessage?: string;
   code?: string; // provider's machine-readable error code, e.g. "DAILY_CAP_HIT"
+  errno?: string; // Node socket-level code, e.g. "ECONNREFUSED"
   model?: string;
   provider?: string;
+  url?: string; // the endpoint the failing request targeted
+  message?: string; // deepest non-empty Error message in the chain
 }
 
 const HOST_LABELS: Record<string, string> = {
@@ -26,70 +29,81 @@ const HOST_LABELS: Record<string, string> = {
   "api.anthropic.com": "Anthropic",
   "api.openai.com": "OpenAI",
   "cloud-api.near.ai": "NEAR AI",
+  "localhost:11434": "Ollama",
+  "127.0.0.1:11434": "Ollama",
 };
 
-// The AI SDK wraps the real provider error: a retry sequence that exhausts its
-// attempts throws AI_RetryError, whose `.lastError` is the APICallError that
-// actually carries statusCode / responseBody / requestBodyValues. Without peeling
-// that off we'd read undefined for every field and fall back to the wrapper's bare
-// "Too Many Requests". Follow `.lastError` (and a `.cause` that looks like a
-// richer error) until we reach the one with the useful fields.
-function unwrap(err: unknown): unknown {
-  let cur = err;
-  for (let i = 0; i < 5; i++) {
-    if (!cur || typeof cur !== "object") break;
-    const e = cur as Record<string, unknown>;
-    const richer = e.statusCode == null && e.responseBody == null;
-    const inner = e.lastError ?? (richer ? e.cause : undefined);
-    if (!inner || inner === cur) break;
-    cur = inner;
-  }
-  return cur;
-}
+// Socket-level failures Node/undici report via an error `code`. Distinct from the
+// provider's machine code (which comes out of the response body) — these mean the
+// request never got a response at all.
+const NETWORK_ERRNO =
+  /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|EPIPE|ENETUNREACH|EHOSTUNREACH|UND_ERR_CONNECT_TIMEOUT|UND_ERR_SOCKET)$/;
 
 // Pull structured fields off an unknown error without trusting any one shape.
+//
+// The AI SDK nests the useful error: retry exhaustion throws AI_RetryError, whose
+// `.lastError` is the APICallError carrying statusCode / url / responseBody, whose
+// `.cause` on a connection failure is the socket error (often an AggregateError
+// with an EMPTY message but an errno code). No single level has everything, so
+// walk the whole chain and merge: HTTP-ish facts keep the first (shallowest)
+// value found, while `message` keeps the deepest NON-EMPTY one — inner messages
+// are more specific ("Cannot connect to API") than the wrapper's ("Failed after
+// 3 attempts…"), but the socket error at the very bottom may have none at all.
 function extract(err: unknown): ErrorFacts {
-  const e = (err ?? {}) as Record<string, unknown>;
-  const statusCode = typeof e.statusCode === "number" ? e.statusCode : undefined;
+  const facts: ErrorFacts = {};
 
   // The provider's own message + machine code, preferred over the SDK's wrapper
   // text. Providers disagree on shape: OpenAI/OpenRouter nest under `error`, while
   // the Privateer account backend returns a flat `{ message, code }` (e.g. a daily
   // usage cap). Read both shapes; keep the first message/code we find.
-  let providerMessage: string | undefined;
-  let code: string | undefined;
   const readBody = (body: unknown) => {
     const b = body as
       | { error?: { message?: unknown; code?: unknown }; message?: unknown; code?: unknown }
       | undefined;
     if (!b || typeof b !== "object") return;
     const msg = b.error?.message ?? b.message;
-    if (providerMessage == null && typeof msg === "string") providerMessage = msg;
+    if (facts.providerMessage == null && typeof msg === "string") facts.providerMessage = msg;
     const c = b.error?.code ?? b.code;
-    if (code == null && typeof c === "string") code = c;
+    if (facts.code == null && typeof c === "string") facts.code = c;
   };
-  readBody(e.data);
-  if (typeof e.responseBody === "string") {
-    try {
-      readBody(JSON.parse(e.responseBody));
-    } catch {
-      /* responseBody wasn't JSON — fall back to the wrapper message */
+
+  let cur: unknown = err;
+  for (let i = 0; i < 6 && cur && typeof cur === "object"; i++) {
+    const e = cur as Record<string, unknown>;
+
+    if (facts.statusCode == null && typeof e.statusCode === "number") facts.statusCode = e.statusCode;
+    readBody(e.data);
+    if (typeof e.responseBody === "string") {
+      try {
+        readBody(JSON.parse(e.responseBody));
+      } catch {
+        /* responseBody wasn't JSON — fall back to the wrapper message */
+      }
     }
-  }
 
-  const reqBody = e.requestBodyValues as { model?: unknown } | undefined;
-  const model = typeof reqBody?.model === "string" ? reqBody.model : undefined;
+    const reqBody = e.requestBodyValues as { model?: unknown } | undefined;
+    if (facts.model == null && typeof reqBody?.model === "string") facts.model = reqBody.model;
 
-  let provider: string | undefined;
-  if (typeof e.url === "string") {
-    try {
-      provider = HOST_LABELS[new URL(e.url).host];
-    } catch {
-      /* not a URL */
+    if (facts.url == null && typeof e.url === "string" && /^https?:/.test(e.url)) {
+      facts.url = e.url;
+      try {
+        facts.provider = HOST_LABELS[new URL(e.url).host];
+      } catch {
+        /* not a URL */
+      }
     }
+
+    if (facts.errno == null && typeof e.code === "string" && NETWORK_ERRNO.test(e.code)) {
+      facts.errno = e.code;
+    }
+    if (typeof e.message === "string" && e.message.trim()) facts.message = e.message;
+
+    const next = e.lastError ?? e.cause;
+    if (!next || next === cur) break;
+    cur = next;
   }
 
-  return { statusCode, providerMessage, code, model, provider };
+  return facts;
 }
 
 // Machine codes the Privateer backend returns for a hard account cap (daily /
@@ -116,10 +130,9 @@ function rawMessage(err: unknown): string {
 // Map a provider error to a friendly message + hint. Falls back to the raw
 // (redacted) message for anything we don't recognize, so nothing is swallowed.
 export function describeError(err: unknown): DescribedError {
-  const inner = unwrap(err);
-  const facts = extract(inner);
+  const facts = extract(err);
   const status = facts.statusCode;
-  const text = facts.providerMessage ?? rawMessage(inner);
+  const text = facts.providerMessage ?? facts.message ?? rawMessage(err);
   const forModel = facts.model ? ` for ${facts.model}` : "";
   const forProvider = facts.provider ? ` for ${facts.provider}` : "";
 
@@ -153,6 +166,16 @@ export function describeError(err: unknown): DescribedError {
       hint: "Upgrade or top up your Privateer account, or run /provider to use your own API key.",
     });
   }
+  // Privateer machine-login expiry (thrown by the session spawn after the
+  // server rejects the parent refresh token). The stored credentials are
+  // already wiped; the only fix is a fresh /login, so say exactly that and
+  // never mark it retryable.
+  if (/privateer session expired/i.test(text)) {
+    return out({
+      message: "Your Privateer session expired — this terminal was signed out.",
+      hint: "Run /login to sign back in to your Privateer account.",
+    });
+  }
   if (status === 401 || status === 403) {
     return out({
       message: `Authentication failed${forProvider} (${status}).`,
@@ -185,9 +208,36 @@ export function describeError(err: unknown): DescribedError {
       retryable: true,
     });
   }
-  if (/fetch failed|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|network/i.test(text)) {
+  if (
+    facts.errno != null ||
+    /fetch failed|cannot connect|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|network/i.test(text)
+  ) {
+    let origin: string | undefined;
+    let localhost = false;
+    if (facts.url) {
+      try {
+        const u = new URL(facts.url);
+        origin = u.origin;
+        localhost = /^(localhost$|127\.|0\.0\.0\.0$|\[::1\]$)/.test(u.hostname);
+      } catch {
+        /* not a URL */
+      }
+    }
+    // A local inference server that refuses connections isn't a flaky network —
+    // it isn't running. Say which one and how to start it; retrying won't help
+    // until the user acts, so no `retryable` flag.
+    if (localhost) {
+      const label = facts.provider ?? "the local server";
+      return out({
+        message: `Cannot connect to ${label} at ${origin} — nothing is listening there.`,
+        hint:
+          facts.provider === "Ollama"
+            ? "Start Ollama (run `ollama serve`, or open the Ollama app), then try again — or run /model to switch models."
+            : "Start the server (or check its base URL), then try again — or run /model to switch models.",
+      });
+    }
     return out({
-      message: "Network error reaching the provider.",
+      message: `Network error reaching ${facts.provider ?? origin ?? "the provider"}.`,
       hint: "Check your connection and try again.",
       retryable: true,
     });

package/src/engine/router.ts

@@ -1,165 +1,11 @@
-import type { LanguageModel, ModelMessage } from "ai";
-import type { Modality } from "../util/images.ts";
-
-export type { Modality };
-
-// The named routes the engine can switch between per turn. `default` is always
-// present (it's the session's configured model); the rest are optional specialized
-// targets resolved from the `router` config block.
-export type RouteName = "default" | "vision" | "document" | "audio" | "video" | "long" | "fast";
-
-// Routes that exist to satisfy a specific input modality, in the order we prefer them
-// when several could cover a turn's requirements.
-const MODALITY_ROUTES: { name: RouteName; modality: Modality }[] = [
-  { name: "vision", modality: "image" },
-  { name: "document", modality: "document" },
-  { name: "audio", modality: "audio" },
-  { name: "video", modality: "video" },
-];
-
-// A resolved, ready-to-stream model plus the per-model knobs that travel with it
-// (Anthropic caching/thinking depend on the model family, so they're per-route) and
-// the set of input modalities it accepts (so the router can satisfy a turn's needs).
-export interface Route {
-  spec: string; // "provider:model"
-  model: LanguageModel;
-  cacheControl: boolean;
-  thinkingBudget?: number;
-  label: string; // short display name for UI notices (the model id tail)
-  supports: Set<Modality>;
-}
-
-export interface RouteSet {
-  default: Route;
-  vision?: Route;
-  document?: Route;
-  audio?: Route;
-  video?: Route;
-  long?: Route;
-  fast?: Route;
-  longThreshold: number; // estimated tokens above which `long` applies
-  fastMaxChars: number; // prompt length at/below which `fast` applies
-}
-
-// What the current turn looks like, used to pick a route.
-export interface RouteSignals {
-  modalities: Set<Modality>; // input modalities anywhere in the conversation (sticky)
-  estTokens: number; // estimated tokens of the whole conversation
-  promptChars: number; // length of the new user prompt
-}
-
-export interface RouteSelection {
-  name: RouteName;
-  route: Route;
-  reason?: string; // short human reason, for the UI notice
-  missing?: Modality[]; // modalities the chosen route can't satisfy (warn)
-}
-
-function covers(route: Route | undefined, required: Set<Modality>): route is Route {
-  if (!route) return false;
-  for (const m of required) if (!route.supports.has(m)) return false;
-  return true;
-}
-
-function missingFrom(route: Route, required: Set<Modality>): Modality[] {
-  return [...required].filter((m) => !route.supports.has(m));
-}
-
-// Candidate routes to consider for an attachment-bearing turn, in preference order:
-// the dedicated modality routes first, then long/fast/default as fallbacks (they may
-// happen to be multimodal). Deduped by identity.
-function candidateRoutes(routes: RouteSet): Route[] {
-  const ordered = [
-    ...MODALITY_ROUTES.map((r) => routes[r.name]),
-    routes.long,
-    routes.fast,
-    routes.default,
-  ].filter((r): r is Route => Boolean(r));
-  return [...new Set(ordered)];
-}
-
-// Pick the model for this turn.
-//   • If the turn requires input modalities, choose the highest-preference route whose
-//     `supports` covers the whole union (capability is a hard requirement). If none
-//     fully covers, fall back to the route covering the most, flagging what's missing.
-//   • Otherwise apply the soft preferences: long (large context) > fast (short prompt)
-//     > default.
-export function selectRoute(routes: RouteSet, s: RouteSignals): RouteSelection {
-  if (s.modalities.size > 0) {
-    const candidates = candidateRoutes(routes);
-    const full = candidates.find((r) => covers(r, s.modalities));
-    if (full) {
-      const name = routeNameOf(routes, full);
-      return { name, route: full, reason: reasonFor(s.modalities) };
-    }
-    // No single route covers everything — pick the one that covers the most and warn.
-    let best = routes.default;
-    let bestMissing = missingFrom(best, s.modalities);
-    for (const r of candidates) {
-      const miss = missingFrom(r, s.modalities);
-      if (miss.length < bestMissing.length) {
-        best = r;
-        bestMissing = miss;
-      }
-    }
-    return {
-      name: routeNameOf(routes, best),
-      route: best,
-      reason: reasonFor(s.modalities),
-      missing: bestMissing,
-    };
-  }
-  if (routes.long && s.estTokens > routes.longThreshold) {
-    return { name: "long", route: routes.long, reason: "long context" };
-  }
-  if (routes.fast && s.promptChars <= routes.fastMaxChars) {
-    return { name: "fast", route: routes.fast, reason: "short prompt" };
-  }
-  return { name: "default", route: routes.default };
-}
-
-function reasonFor(modalities: Set<Modality>): string {
-  return `${[...modalities].join("+")} input`;
-}
-
-// Recover the route name for a resolved Route (for the UI/event). Falls back to
-// "default" if it isn't one of the named slots.
-function routeNameOf(routes: RouteSet, route: Route): RouteName {
-  const names: RouteName[] = ["vision", "document", "audio", "video", "long", "fast"];
-  for (const n of names) if (routes[n] === route) return n;
-  return "default";
-}
-
-const MEDIA_MODALITY: { test: RegExp; modality: Modality }[] = [
-  { test: /^image\//, modality: "image" },
-  { test: /^audio\//, modality: "audio" },
-  { test: /^video\//, modality: "video" },
-  { test: /^application\/pdf$/, modality: "document" },
-];
-
-function modalityOfMediaType(mediaType: string): Modality | null {
-  return MEDIA_MODALITY.find((m) => m.test.test(mediaType))?.modality ?? null;
-}
-
-// The input modalities present anywhere in the conversation. Keyed off the whole
-// history (not just the new message) so that once an attachment is in context,
-// follow-up turns stay on a model that can accept it rather than replaying it to one
-// that can't.
-export function requiredModalities(messages: ModelMessage[]): Set<Modality> {
-  const out = new Set<Modality>();
-  for (const m of messages) {
-    const content = m.content;
-    if (!Array.isArray(content)) continue;
-    for (const part of content) {
-      if (!part || typeof part !== "object" || !("type" in part)) continue;
-      const t = (part as { type: string }).type;
-      if (t === "image") out.add("image");
-      else if (t === "file") {
-        const mt = (part as { mediaType?: string }).mediaType;
-        const mod = mt ? modalityOfMediaType(mt) : null;
-        if (mod) out.add(mod);
-      }
-    }
-  }
-  return out;
-}
+// Route/modality types referenced by the EngineEvent `routed` variant.
+//
+// STUB — the full router (tree-cli/src/engine/router.ts) is DELETE in the
+// migration (Pi's model registry + our models.json generator replace it). Only
+// the two type names survive as part of the relay wire vocabulary, so they live
+// here as a types-only module until the `routed` event's producer is wired in a
+// later phase. Kept structurally identical to the original so events.ts ports
+// verbatim.
+export type Modality = "text" | "image" | "audio" | "video" | "pdf";
+
+export type RouteName = "default" | "vision" | "long-context" | "fast" | (string & {});

package/src/ext/permissionGate.ts

@@ -0,0 +1,216 @@
+// The permission gate — the safe-by-default moat, as a Pi extension.
+//
+// Phase 2. Ties together the ported policy: a `tool_call` hook classifies the
+// call (./…/classify.ts), runs it through the ModeGate policy engine
+// (./…/modeGate.ts → decideAuto), and blocks the tool when the decision is deny.
+// The gate SUSPENDS the turn while an approval is pending (spike-B proven), routes
+// to a LOCAL prompt (ctx.ui) or a REMOTE approver (the relay, Phase 4), and is
+// FAIL-CLOSED: any throw, timeout, or abort blocks the tool. A `tool_result` hook
+// redacts secrets from output before it reaches the model / relay.
+//
+// The load-bearing decision path is `decideToolCall`, kept pure and Pi-free so the
+// ported tests exercise it without a live session.
+
+import type { PermissionMode } from "../config/permissionMode.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+import { ModeGate, type AskOutcome } from "../permissions/modeGate.ts";
+import { classifyToolCall } from "../permissions/classify.ts";
+import { redactText } from "../util/redact.ts";
+import { DEFAULT_DENYLIST } from "../permissions/danger.ts";
+
+// The per-tool_call hook context we read (structural subset of Pi's ctx — kept
+// local so the gate stays import-order-safe and unit-testable).
+export interface ToolCallCtx {
+  signal?: AbortSignal;
+  hasUI?: boolean;
+  mode?: "tui" | "rpc" | "json" | "print" | string;
+  // Pi's ExtensionUIContext shape (verified against pi-coding-agent 0.80):
+  // select(title, options: string[]) → chosen string | undefined; confirm(title, message).
+  ui?: {
+    select?: (title: string, options: string[], opts?: unknown) => Promise<string | undefined>;
+    confirm?: (title: string, message: string, opts?: unknown) => Promise<boolean>;
+  };
+}
+
+// Session-scoped state + askers. Mutable fields (mode/allowlist/allowedOutsideRoots)
+// persist across tool_calls; the askers are invoked per call.
+export interface GateController {
+  getMode(): PermissionMode;
+  setMode(mode: PermissionMode): void;
+  allowlist: string[];
+  allowedOutsideRoots: string[];
+  denylist?: string[];
+  cwd: string;
+  confineToCwd?: boolean;
+  getRemote?(): boolean;
+  getNoQuarter?(): boolean;
+  // Local interactive approval via the per-call ctx. Default provided below.
+  localAsk(req: PermissionRequest, ctx: ToolCallCtx): Promise<AskOutcome>;
+  // Remote (relay) approval. Optional until Phase 4; when absent, a remote turn
+  // falls back to localAsk.
+  remoteAsk?(req: PermissionRequest, signal?: AbortSignal): Promise<AskOutcome>;
+  // Secret redactor for tool output. Defaults to redactText.
+  redact?(text: string): string;
+  // Hard ceiling on waiting for a decision before failing closed.
+  approvalTimeoutMs?: number;
+}
+
+export interface GateBlock {
+  block: true;
+  reason: string;
+}
+
+// THE decision path. Classify → policy → decision, fail-closed on any error.
+// Returns a block directive to deny, or undefined to let the tool run.
+export async function decideToolCall(
+  ctrl: GateController,
+  toolName: string,
+  input: unknown,
+  ctx: ToolCallCtx,
+): Promise<GateBlock | undefined> {
+  const req = classifyToolCall(toolName, input, {
+    cwd: ctrl.cwd,
+    confineToCwd: ctrl.confineToCwd,
+    allowedOutsideRoots: ctrl.allowedOutsideRoots,
+  });
+  if (!req) return undefined; // no gate needed — read-only/in-scope/meta
+
+  // Route the ask: a remote-driven turn goes to the relay approver (if wired),
+  // otherwise the local UI. ModeGate decides *whether* to ask; this decides *who*.
+  const ask = (r: PermissionRequest): Promise<AskOutcome> =>
+    ctrl.getRemote?.() && ctrl.remoteAsk
+      ? ctrl.remoteAsk(r, ctx.signal)
+      : ctrl.localAsk(r, ctx);
+
+  const gate = new ModeGate({
+    getMode: ctrl.getMode,
+    setMode: ctrl.setMode,
+    allowlist: ctrl.allowlist,
+    allowedOutsideRoots: ctrl.allowedOutsideRoots,
+    // Default to the built-in dangerous-command patterns so bypass / no-quarter /
+    // headless-subagent runs still force dangerous shell + secret-exfil to "ask"
+    // (→ headless deny). A controller can extend, but never silently disable, this.
+    denylist: ctrl.denylist ?? DEFAULT_DENYLIST,
+    ask,
+    getRemote: ctrl.getRemote,
+    getNoQuarter: ctrl.getNoQuarter,
+  });
+
+  let decision: "allow" | "deny";
+  try {
+    decision = await withTimeout(gate.request(req), ctrl.approvalTimeoutMs, ctx.signal);
+  } catch (err) {
+    // Fail closed: a thrown/aborted/timed-out approval blocks the tool.
+    return {
+      block: true,
+      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default`,
+    };
+  }
+  if (decision === "deny") {
+    return { block: true, reason: `${req.title} denied by permission gate` };
+  }
+  return undefined;
+}
+
+// Default local asker: prompt via ctx.ui when a UI is present; fail closed
+// (deny) when headless (no UI) — the gate is the real safety, never auto-trust.
+// TODO(verify) the exact ctx.ui.select/confirm API shape against Pi when the TUI
+// is wired (Phase 6); coded defensively for now.
+const ALLOW_ONCE = "Allow once";
+const ALLOW_ALWAYS = "Allow and remember";
+const DENY = "Deny";
+
+export async function defaultLocalAsk(req: PermissionRequest, ctx: ToolCallCtx): Promise<AskOutcome> {
+  if (!ctx.hasUI || !ctx.ui) return "deny"; // headless → fail closed
+  const title = `${req.title}: ${req.detail}`;
+  if (typeof ctx.ui.select === "function") {
+    const choice = await ctx.ui.select(title, [ALLOW_ONCE, ALLOW_ALWAYS, DENY]);
+    if (choice === ALLOW_ONCE) return "allow";
+    if (choice === ALLOW_ALWAYS) return "always";
+    return "deny"; // Deny, or cancel (undefined)
+  }
+  if (typeof ctx.ui.confirm === "function") {
+    return (await ctx.ui.confirm("Permission", title)) ? "allow" : "deny";
+  }
+  return "deny";
+}
+
+// Build the extension factory. Pass to DefaultResourceLoader({ extensionFactories }).
+export function makePermissionGate(ctrl: GateController) {
+  const redact = ctrl.redact ?? redactText;
+  if (!ctrl.localAsk) ctrl.localAsk = defaultLocalAsk;
+
+  // Structural view of the Pi extension API surface we use (documented at
+  // pi.dev/docs/latest/extensions).
+  interface PiExtensionApi {
+    on(
+      event: "tool_call",
+      handler: (
+        event: { toolName: string; toolCallId: string; input: unknown },
+        ctx: ToolCallCtx,
+      ) => Promise<GateBlock | undefined>,
+    ): void;
+    on(
+      event: "tool_result",
+      handler: (
+        event: {
+          toolName: string;
+          toolCallId: string;
+          content: Array<{ type: string; text?: string; [k: string]: unknown }>;
+          details?: unknown;
+          isError?: boolean;
+        },
+        ctx: unknown,
+      ) => { content?: unknown[] } | undefined,
+    ): void;
+  }
+
+  return function permissionGate(pi: PiExtensionApi): void {
+    pi.on("tool_call", (event, ctx) => decideToolCall(ctrl, event.toolName, event.input, ctx));
+
+    // Redact secrets from tool output before it reaches the model / relay.
+    // tool_result delivers content PARTS (per the Pi extension contract), not a
+    // bare string — patch text parts and return a partial { content }; omitted
+    // fields keep their current values.
+    pi.on("tool_result", (event) => {
+      let touched = false;
+      const content = event.content.map((part) => {
+        if (typeof part.text === "string") {
+          const red = redact(part.text);
+          if (red !== part.text) touched = true;
+          return { ...part, text: red };
+        }
+        return part;
+      });
+      return touched ? { content } : undefined;
+    });
+  };
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number | undefined, signal?: AbortSignal): Promise<T> {
+  if (!ms && !signal) return p;
+  return new Promise<T>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    if (ms) timer = setTimeout(() => reject(new Error("approval timeout")), ms);
+    if (signal) {
+      if (signal.aborted) return onAbort();
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        reject(e);
+      },
+    );
+  });
+}

package/src/main.ts

@@ -0,0 +1,32 @@
+// Entrypoint. The ONE ordering rule: import ./boot.ts first (env +
+// attestation dispatcher), then dynamically import everything Pi-touching so
+// boot's side effects are guaranteed to have run before any Pi module loads.
+//
+// Phase 1 skeleton: this prints the resolved boot state so `npm start` proves
+// the boot chain end-to-end (env pinned, dispatcher installed) without a TUI.
+// Phases 4/6 replace the body with the daemon/relay wiring and the pi-tui app.
+
+import "./boot.ts";
+
+async function main() {
+  // Only import Pi-touching / config code AFTER boot has run.
+  const { agentDir, globalDir } = await import("./config/paths.ts");
+  const { capturedHosts } = await import("pi-privacy/attest");
+
+  const home = globalDir();
+  const agent = process.env.PI_CODING_AGENT_DIR ?? agentDir();
+
+  console.log("privateer-agent 0.3 — boot skeleton");
+  console.log(`  PRIVATEER_HOME        ${home}`);
+  console.log(`  PI_CODING_AGENT_DIR   ${agent}`);
+  console.log(`  attestation dispatcher installed: yes`);
+  console.log(`  hosts attested so far: ${capturedHosts().size}`);
+  console.log("");
+  console.log("Phases 1–2 skeleton in place (adapter + gate promoted from pi-spike).");
+  console.log("Next: wire a real headless session — see docs/pi-migration-plan.md §2.");
+}
+
+main().catch((err) => {
+  console.error(err?.stack ?? err);
+  process.exit(1);
+});