privateer-agent 0.3.6 → 0.4.1

package/src/daemon/service.ts

@@ -0,0 +1,232 @@
+// Install the resident daemon as a per-user OS service so it auto-starts at login
+// and survives the terminal closing — the difference between "the CLI is running"
+// and "the daemon is reachable from the app even when no CLI is". macOS → launchd
+// user agent; Linux → systemd --user unit. No root: everything lives under the
+// user's own home and login session.
+//
+// ORDERING NOTE: this module is import-safe (node builtins + our paths only, no Pi),
+// so the daemon CLI can load it without going through boot.ts.
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { globalDir } from "../config/paths.ts";
+import { daemonIsRunning } from "./ipc.ts";
+
+const LABEL = "pro.privateer.daemon"; // launchd label / reverse-dns id
+const UNIT = "privateer-daemon.service"; // systemd --user unit name
+
+// Absolute path to the node launcher that boots + runs the daemon (bin/privateer-daemon.mjs).
+// Resolved from THIS module so it's correct for both a dev checkout and a global npm
+// install (…/node_modules/privateer-agent/bin/privateer-daemon.mjs).
+function daemonLauncherPath(): string {
+  const here = dirname(fileURLToPath(import.meta.url)); // …/src/daemon
+  return resolve(here, "../../bin/privateer-daemon.mjs");
+}
+
+// The node binary to bake into the unit. We use the CURRENT interpreter (>=22, the
+// bash launcher already picked a compatible one) by absolute path, so the service
+// never depends on launchd/systemd having a usable PATH.
+function nodeBinaryPath(): string {
+  return process.execPath;
+}
+
+function daemonLogPath(): string {
+  return join(globalDir(), "daemon.log");
+}
+
+// Env we forward into the service so a non-default home / server URL survives. Kept
+// tiny and explicit — the daemon reads the rest from ~/.privateer.
+function forwardedEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  if (process.env.PRIVATEER_HOME) env.PRIVATEER_HOME = process.env.PRIVATEER_HOME;
+  if (process.env.PRIVATEER_SERVER_URL) env.PRIVATEER_SERVER_URL = process.env.PRIVATEER_SERVER_URL;
+  return env;
+}
+
+// ── macOS (launchd) ─────────────────────────────────────────────────────────────
+
+function launchAgentPath(): string {
+  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+function xmlEscape(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function launchdPlist(): string {
+  const args = [nodeBinaryPath(), daemonLauncherPath(), "run"];
+  const envVars = forwardedEnv();
+  const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
+  const envXml = Object.entries(envVars)
+    .map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(v)}</string>`)
+    .join("\n");
+  const log = xmlEscape(daemonLogPath());
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+${envVars.PRIVATEER_HOME || envVars.PRIVATEER_SERVER_URL ? `  <key>EnvironmentVariables</key>\n  <dict>\n${envXml}\n  </dict>\n` : ""}  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${log}</string>
+  <key>StandardErrorPath</key>
+  <string>${log}</string>
+</dict>
+</plist>
+`;
+}
+
+function installLaunchd(): void {
+  const plist = launchAgentPath();
+  mkdirSync(dirname(plist), { recursive: true });
+  writeFileSync(plist, launchdPlist());
+  // Unload a prior copy (ignore failure — it may not be loaded), then load with -w so
+  // it's enabled across reboots.
+  spawnSync("launchctl", ["unload", plist], { stdio: "ignore" });
+  const r = spawnSync("launchctl", ["load", "-w", plist], { encoding: "utf8" });
+  if (r.status !== 0) {
+    throw new Error(`launchctl load failed: ${(r.stderr || r.stdout || "").trim() || `exit ${r.status}`}`);
+  }
+}
+
+function uninstallLaunchd(): void {
+  const plist = launchAgentPath();
+  if (existsSync(plist)) {
+    spawnSync("launchctl", ["unload", "-w", plist], { stdio: "ignore" });
+    rmSync(plist, { force: true });
+  }
+}
+
+// ── Linux (systemd --user) ───────────────────────────────────────────────────────
+
+function systemdUnitPath(): string {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "systemd", "user", UNIT);
+}
+
+function systemdUnit(): string {
+  const exec = [nodeBinaryPath(), daemonLauncherPath(), "run"].map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ");
+  const envLines = Object.entries(forwardedEnv())
+    .map(([k, v]) => `Environment=${k}=${v}`)
+    .join("\n");
+  return `[Unit]
+Description=Privateer resident agent daemon (routines + app-driven task spawns)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Restart=on-failure
+RestartSec=5
+${envLines}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function installSystemd(): void {
+  const unit = systemdUnitPath();
+  mkdirSync(dirname(unit), { recursive: true });
+  writeFileSync(unit, systemdUnit());
+  spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+  // enable-linger so the user service keeps running with no active login session —
+  // the whole point of "reachable even when no shell is open". Best-effort: it needs
+  // no root on most distros, but don't fail the install if it's disallowed.
+  spawnSync("loginctl", ["enable-linger", process.env.USER || ""], { stdio: "ignore" });
+  const r = spawnSync("systemctl", ["--user", "enable", "--now", UNIT], { encoding: "utf8" });
+  if (r.status !== 0) {
+    throw new Error(`systemctl enable failed: ${(r.stderr || r.stdout || "").trim() || `exit ${r.status}`}`);
+  }
+}
+
+function uninstallSystemd(): void {
+  const unit = systemdUnitPath();
+  spawnSync("systemctl", ["--user", "disable", "--now", UNIT], { stdio: "ignore" });
+  if (existsSync(unit)) rmSync(unit, { force: true });
+  spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────────
+
+export interface ServiceInfo {
+  platform: NodeJS.Platform;
+  supported: boolean;
+  installed: boolean;
+  unitPath: string;
+  logPath: string;
+}
+
+function unitPathFor(platform: NodeJS.Platform): string {
+  if (platform === "darwin") return launchAgentPath();
+  if (platform === "linux") return systemdUnitPath();
+  return "";
+}
+
+export function serviceInfo(): ServiceInfo {
+  const platform = process.platform;
+  const unitPath = unitPathFor(platform);
+  return {
+    platform,
+    supported: platform === "darwin" || platform === "linux",
+    installed: !!unitPath && existsSync(unitPath),
+    unitPath,
+    logPath: daemonLogPath(),
+  };
+}
+
+// Install the service for the current platform. Idempotent (rewrites + reloads).
+export function installService(): ServiceInfo {
+  const platform = process.platform;
+  if (platform === "darwin") installLaunchd();
+  else if (platform === "linux") installSystemd();
+  else throw new Error(`Auto-start isn't supported on ${platform}. Run \`privateer daemon\` yourself, or keep a terminal open.`);
+  return serviceInfo();
+}
+
+export function uninstallService(): ServiceInfo {
+  const platform = process.platform;
+  if (platform === "darwin") uninstallLaunchd();
+  else if (platform === "linux") uninstallSystemd();
+  else throw new Error(`No service to remove on ${platform}.`);
+  return serviceInfo();
+}
+
+// Human-readable status line for `privateer daemon status`: whether the service is
+// installed AND whether a daemon is actually answering on the IPC socket right now.
+export async function statusReport(): Promise<string> {
+  const info = serviceInfo();
+  const live = await daemonIsRunning();
+  const lines = [
+    `platform:  ${info.platform}${info.supported ? "" : " (auto-start unsupported — run `privateer daemon` manually)"}`,
+    `service:   ${info.installed ? `installed (${info.unitPath})` : "not installed"}`,
+    `daemon:    ${live ? "running (answering IPC)" : "not reachable"}`,
+    `logs:      ${info.logPath}`,
+  ];
+  // Surface a stale-unit hint: file present but nothing answering usually means it
+  // failed to boot — the log path above is where to look.
+  if (info.installed && !live) lines.push("hint:      service is installed but not answering — check the log for a boot error.");
+  return lines.join("\n");
+}
+
+// Best-effort read of the tail of the daemon log (for a `status --log` affordance or
+// error surfacing). Returns "" if absent.
+export function tailDaemonLog(maxBytes = 4_000): string {
+  try {
+    const buf = readFileSync(daemonLogPath(), "utf8");
+    return buf.length > maxBytes ? buf.slice(buf.length - maxBytes) : buf;
+  } catch {
+    return "";
+  }
+}

package/src/ext/permissionGate.ts

@@ -44,6 +44,14 @@ export interface GateController {
   confineToCwd?: boolean;
   getRemote?(): boolean;
   getNoQuarter?(): boolean;
+  // Block a tool outright while the turn is remote-driven (only consulted when
+  // getRemote() is true). For tools whose own prompts render on the host terminal
+  // rather than the relay — e.g. pi-subagents — so a driven turn can't wedge on an
+  // invisible local prompt. Returns true to block. See isRemoteUnsafeTool.
+  blockedWhenRemote?(toolName: string): boolean;
+  // Notified when blockedWhenRemote blocked a tool, so the controller can surface a
+  // one-line reason in the app feed (a `notice` frame) explaining why nothing ran.
+  onRemoteBlocked?(toolName: string): void;
   // 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
@@ -60,6 +68,23 @@ export interface GateBlock {
   reason: string;
 }
 
+// Tools that CANNOT be driven from the app and so are blocked outright on a
+// remote-driven turn (see chat.ts wiring). pi-subagents runs each subagent as a
+// child session/subprocess whose own permission gate + UI aren't wired to the
+// relay — its approvals and "TUI clarification" prompts surface on the HOST
+// terminal, never in the app. A driven turn that spawned one would wedge on a
+// prompt the phone can't answer. `contact_supervisor`/`intercom` are the child→
+// parent tools; they only exist in child sessions but are listed for safety.
+// Blocking is fail-closed and matches the "remote turns never auto-approve"
+// posture: the feature is simply disabled while driving until its prompts relay.
+export const REMOTE_UNSAFE_TOOLS: ReadonlySet<string> = new Set([
+  "subagent",
+  "contact_supervisor",
+  "intercom",
+]);
+
+export const isRemoteUnsafeTool = (toolName: string): boolean => REMOTE_UNSAFE_TOOLS.has(toolName);
+
 // 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(
@@ -68,6 +93,19 @@ export async function decideToolCall(
   input: unknown,
   ctx: ToolCallCtx,
 ): Promise<GateBlock | undefined> {
+  // Remote-driven turn: a few tools can't be driven from the app because their own
+  // interactive prompts render on the host terminal, not the relay (pi-subagents
+  // spawns child sessions outside the bridge). Block them fail-closed BEFORE any
+  // classification so a driven turn never wedges on a prompt the phone can't answer,
+  // and tell the controller so it can post a notice to the app feed.
+  if (ctrl.getRemote?.() && ctrl.blockedWhenRemote?.(toolName)) {
+    ctrl.onRemoteBlocked?.(toolName);
+    return {
+      block: true,
+      reason: `${toolName} is unavailable while this terminal is driven remotely — its prompts can't reach the app. Complete the task without it, or ask the operator to run it from the terminal directly.`,
+    };
+  }
+
   const req = classifyToolCall(toolName, input, {
     cwd: ctrl.cwd,
     confineToCwd: ctrl.confineToCwd,

package/src/permissions/classify.ts

@@ -1,4 +1,5 @@
-import { resolve, isAbsolute, relative } from "node:path";
+import { resolve, isAbsolute, relative, dirname, join, basename } from "node:path";
+import { realpathSync } from "node:fs";
 import { isProtectedPath } from "./protected.ts";
 import type { PermissionRequest } from "./gate.ts";
 
@@ -18,8 +19,31 @@ export interface ScopeOptions {
   allowedOutsideRoots?: string[];
 }
 
+// Resolve symlinks so an in-cwd symlink can't smuggle a path outside scope past the
+// lexical `resolve()` check (P5-1: `resolve` normalizes `..` but does NOT follow
+// symlinks, so `cwd/link/secret` where `link -> /etc` looks in-cwd lexically). We
+// realpath the DEEPEST EXISTING ancestor — a write target's leaf may not exist yet —
+// and re-append the missing tail; the escape lives in the existing prefix, so
+// canonicalizing that is what matters. Falls back to the lexical path when nothing
+// resolves (e.g. a fully-nonexistent tree, as in unit tests).
+function realBase(abs: string): string {
+  let dir = abs;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      const real = realpathSync(dir);
+      return tail.length ? join(real, ...tail) : real;
+    } catch {
+      const parent = dirname(dir);
+      if (parent === dir) return abs; // reached the FS root without resolving → lexical
+      tail.unshift(basename(dir));
+      dir = parent;
+    }
+  }
+}
+
 function resolveInCwd(cwd: string, p: string): string {
-  return isAbsolute(p) ? p : resolve(cwd, p);
+  return realBase(isAbsolute(p) ? p : resolve(cwd, p));
 }
 
 function isInsideDir(root: string, abs: string): boolean {
@@ -29,11 +53,14 @@ function isInsideDir(root: string, abs: string): boolean {
 }
 
 // Outside the agent's working-directory scope? Only when confinement is on and the
-// path is neither inside cwd nor inside a session-approved outside root.
+// path is neither inside cwd nor inside a session-approved outside root. Both sides are
+// symlink-canonicalized (realBase) so a symlinked cwd — or a symlink inside cwd — can't
+// fake containment (P5-1).
 export function isOutsideScope(scope: ScopeOptions, abs: string): boolean {
   if (scope.confineToCwd === false) return false;
-  if (isInsideDir(scope.cwd, abs)) return false;
-  return !(scope.allowedOutsideRoots ?? []).some((root) => isInsideDir(root, abs));
+  const target = realBase(abs);
+  if (isInsideDir(realBase(scope.cwd), target)) return false;
+  return !(scope.allowedOutsideRoots ?? []).some((root) => isInsideDir(realBase(root), target));
 }
 
 function str(v: unknown): string {
@@ -44,6 +71,21 @@ function firstPath(input: Record<string, unknown>): string {
   return str(input.path ?? input.file_path ?? input.file ?? input.filename ?? input.dir ?? input.directory);
 }
 
+// A write/edit tool call whose target path we can't statically extract — an aliased
+// param name, or a patch tool whose target paths live in the DIFF BODY rather than a
+// param (P5-4). Fail safe: mark it outside-scope so it prompts (in default/acceptEdits)
+// instead of defaulting to a silent in-cwd auto-write. Precise patch-body path parsing
+// needs Pi's apply_patch schema — TODO(verify) against the full builtin tool catalog.
+function unknownTarget(toolName: string, kind: "write" | "edit"): PermissionRequest {
+  return {
+    tool: toolName,
+    kind,
+    title: kind === "write" ? "Write to an unverified path" : "Edit an unverified path",
+    detail: "(target path not statically known — approve to allow)",
+    outside: true,
+  };
+}
+
 // Known-safe read-only / meta builtins that never mutate and never leave the
 // machine: no gate regardless of arguments. Tunable — the conservative default for
 // anything NOT listed here is to ask (see below). TODO(verify) against Pi's full
@@ -96,6 +138,7 @@ export function classifyToolCall(
   // Write — create/overwrite a file.
   if (WRITE_TOOLS.has(name)) {
     const p = firstPath(obj);
+    if (!p) return unknownTarget(toolName, "write"); // P5-4: no extractable path → fail safe
     const abs = resolveInCwd(scope.cwd, p);
     const outside = isOutsideScope(scope, abs);
     return {
@@ -112,6 +155,7 @@ export function classifyToolCall(
   // Edit — modify an existing file.
   if (EDIT_TOOLS.has(name)) {
     const p = firstPath(obj);
+    if (!p) return unknownTarget(toolName, "edit"); // P5-4: no extractable path → fail safe
     const abs = resolveInCwd(scope.cwd, p);
     const outside = isOutsideScope(scope, abs);
     return {

package/src/providers/account.ts

@@ -20,6 +20,7 @@ import {
   notifySignedIn,
 } from "../auth/privateer.ts";
 import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
+import { ACCOUNT_DEFAULT_MODEL_ID, ensurePiDefaultModel } from "./defaultModel.ts";
 
 // Seed/fallback catalog: registered synchronously so the account provider has real
 // models the instant it loads (before the live /api/models fetch resolves) — in
@@ -28,7 +29,7 @@ import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } fro
 // confidential-compute (TEE, attestable) model — the strongest privacy tier. Also the
 // fallback list if the live listing can't be reached.
 const DEFAULT_MODELS = [
-  "near/zai-org/GLM-5.1-FP8",
+  ACCOUNT_DEFAULT_MODEL_ID,
   "anthropic/claude-sonnet-4.6",
   "openai/gpt-5.5",
   "deepseek/deepseek-v4-flash",
@@ -101,6 +102,11 @@ export const privateerOAuthProvider = {
     }
     if (cb.signal?.aborted) throw new Error("Login cancelled");
     const creds = await spawnAccountCredentials();
+    // Seed Pi's saved model default to the account channel, so the next launch resolves
+    // to a billable subscription model instead of falling through to a keyless built-in
+    // (the "No API key found for openrouter" trap). No-op if the user already has a
+    // chosen default. See providers/defaultModel.ts.
+    ensurePiDefaultModel();
     // The fresh path already fired notifySignedIn (pollForToken); fire here for the
     // already-linked path so the header re-renders to "connected" on this terminal too.
     if (wasLinked) notifySignedIn();

package/src/providers/defaultModel.ts

@@ -0,0 +1,119 @@
+// The single source of truth for "which model do we default to?" — shared by every
+// entry point that has to pick a model when the user hasn't named one: the REPL
+// (cli/chat.ts), the daemon (routines), the channels runner, and the login-time hook
+// that seeds Pi's TUI default (ensurePiDefaultModel).
+//
+// The bug this fixes: each of those sites used to hardcode `openrouter/openai/gpt-4o-
+// mini`, which assumes a BYO OpenRouter key. A user who is ONLY signed into their
+// Privateer subscription has no such key, so the runtime resolved to OpenRouter and
+// then failed at request time with "No API key found for openrouter". Being signed in
+// never nominated a model. resolveDefaultModel() makes the account channel the default
+// the moment credentials exist, and keeps the legacy BYO behaviour otherwise.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hasCredentials } from "../auth/privateer.ts";
+import { agentDir } from "../config/paths.ts";
+
+// The signed-in default: a NEAR confidential-compute (TEE, attestable) model — the
+// strongest privacy tier, and the same id the app shows first. Kept here as the one
+// definition; providers/account.ts imports it so its seed catalog can't drift.
+export const ACCOUNT_DEFAULT_MODEL_ID = "near/zai-org/GLM-5.1-FP8";
+export const ACCOUNT_DEFAULT_SPEC = `privateer/${ACCOUNT_DEFAULT_MODEL_ID}`;
+
+// Last-resort BYO default, preserved from the pre-resolver code so a user who set an
+// OpenRouter key (and isn't signed in) keeps the old behaviour. If they have no key
+// either, this still surfaces the familiar "No API key found for openrouter" — a clear
+// signal to run /login or set a key, which is better than an empty/undefined model.
+export const LEGACY_BYO_FALLBACK = "openrouter/openai/gpt-4o-mini";
+
+// BYO providers we can positively detect from the environment, in preference order.
+// Each model id matches Pi's own defaultModelPerProvider so it actually resolves once
+// the key is present. OpenRouter stays on the legacy cheap default for continuity.
+const BYO_BY_KEY: Array<{ env: string; spec: string }> = [
+  { env: "ANTHROPIC_API_KEY", spec: "anthropic/claude-opus-4-8" },
+  { env: "OPENAI_API_KEY", spec: "openai/gpt-5.5" },
+  { env: "OPENROUTER_API_KEY", spec: LEGACY_BYO_FALLBACK },
+];
+
+export interface ResolveDefaultModelOptions {
+  // An explicit, user-chosen spec (e.g. config.defaultModel, a channel's `model`).
+  // Wins over everything when non-empty — it's a deliberate choice, not a fallback.
+  explicit?: string | null;
+  // Override for testing / non-process callers. Defaults to process.env.
+  env?: NodeJS.ProcessEnv;
+  // Override the signed-in check (testing). Defaults to hasCredentials().
+  signedIn?: boolean;
+}
+
+// Resolve the model spec ("provider/id") to use when no model is named. Pure and
+// synchronous (only reads env + the credentials file), so it's safe to call from any
+// entry point at startup. Precedence:
+//   1. explicit user choice (config/channel)      — deliberate, always wins
+//   2. PRIVATEER_MODEL env                         — dev/global override
+//   3. signed into Privateer → the account default — the fix: subscription users
+//   4. a BYO provider whose key is present         — anthropic, openai, openrouter
+//   5. LEGACY_BYO_FALLBACK                          — familiar "add a key" signal
+export function resolveDefaultModel(opts: ResolveDefaultModelOptions = {}): string {
+  const env = opts.env ?? process.env;
+
+  const explicit = opts.explicit?.trim();
+  if (explicit) return explicit;
+
+  const fromEnv = env.PRIVATEER_MODEL?.trim();
+  if (fromEnv) return fromEnv;
+
+  const signedIn = opts.signedIn ?? hasCredentials();
+  if (signedIn) return ACCOUNT_DEFAULT_SPEC;
+
+  for (const { env: keyName, spec } of BYO_BY_KEY) {
+    if (env[keyName]?.trim()) return spec;
+  }
+
+  return LEGACY_BYO_FALLBACK;
+}
+
+// Split a "provider/id" spec on its first slash (model ids themselves contain "/", so
+// only the first delimiter separates provider from model). Returns null for a spec
+// with no provider prefix.
+function splitSpec(spec: string): { provider: string; modelId: string } | null {
+  const slash = spec.indexOf("/");
+  if (slash <= 0 || slash === spec.length - 1) return null;
+  return { provider: spec.slice(0, slash), modelId: spec.slice(slash + 1) };
+}
+
+// The TUI consumer. Pi's own model resolution (findInitialModel) checks its saved
+// settings default BEFORE it falls through to a keyless built-in, but nothing ever
+// pointed that default at the account channel — Pi's provider-default table has no
+// `privateer` entry, so a signed-in-only user landed on OpenRouter and errored. On a
+// successful login we seed Pi's global settings.json (agentDir/settings.json — the
+// same file its SettingsManager reads) with the account default, so the NEXT launch
+// resolves cleanly.
+//
+// Guarded: we only write when the user has NOT already chosen a default (no
+// `defaultModel` key), so a deliberate /model choice is never stomped. Best-effort —
+// any read/parse/write failure is swallowed; a missing seed just means the user picks
+// a model once via /model. Returns the spec written, or null if we left it alone.
+export function ensurePiDefaultModel(spec: string = ACCOUNT_DEFAULT_SPEC): string | null {
+  const parts = splitSpec(spec);
+  if (!parts) return null;
+  const settingsPath = join(agentDir(), "settings.json");
+  try {
+    let settings: Record<string, unknown> = {};
+    if (existsSync(settingsPath)) {
+      const raw = readFileSync(settingsPath, "utf8").trim();
+      if (raw) settings = JSON.parse(raw) as Record<string, unknown>;
+    }
+    // Respect an existing choice — presence of the key means the user (or Pi) already
+    // has a default; don't override it.
+    if (typeof settings.defaultModel === "string" && settings.defaultModel.trim()) {
+      return null;
+    }
+    settings.defaultProvider = parts.provider;
+    settings.defaultModel = parts.modelId;
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return spec;
+  } catch {
+    return null;
+  }
+}