privateer-agent 0.1.1 → 0.2.1

package/src/components/OptionPicker.tsx

@@ -0,0 +1,134 @@
+import React, { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import type { UserQuestion, UserAnswer } from "../tools/askUser.ts";
+import { theme } from "./theme.ts";
+
+// Interactive picker shown when the agent calls `ask_user` to choose between
+// competing approaches. The turn is blocked on the human (like the approval prompt).
+// Keys: ↑/↓ move, 1–N jump, Enter confirm, e (or the last row) write a custom answer,
+// Esc dismiss. In multiSelect mode, Space/number toggles and Enter confirms the set.
+export function OptionPicker({
+  question,
+  onRespond,
+}: {
+  question: UserQuestion;
+  onRespond: (answer: UserAnswer) => void;
+}) {
+  const { options, multiSelect } = question;
+  const otherIndex = options.length; // the trailing "write your own" row
+  const total = options.length + 1;
+  const [cursor, setCursor] = useState(0);
+  const [checked, setChecked] = useState<Set<number>>(new Set());
+  const [mode, setMode] = useState<"list" | "custom">("list");
+  const [draft, setDraft] = useState("");
+
+  function toggle(i: number) {
+    setChecked((prev) => {
+      const next = new Set(prev);
+      if (next.has(i)) next.delete(i);
+      else next.add(i);
+      return next;
+    });
+  }
+
+  function confirm() {
+    if (cursor === otherIndex) {
+      setMode("custom");
+      return;
+    }
+    if (multiSelect) {
+      const picks = checked.size > 0 ? [...checked] : [cursor];
+      onRespond({ kind: "selected", indices: picks.sort((a, b) => a - b) });
+    } else {
+      onRespond({ kind: "selected", indices: [cursor] });
+    }
+  }
+
+  useInput((input, key) => {
+    if (mode === "custom") {
+      if (key.escape) {
+        setMode("list");
+        setDraft("");
+      } else if (key.return) {
+        const text = draft.trim();
+        if (text) onRespond({ kind: "custom", text });
+      } else if (key.backspace || key.delete) {
+        setDraft((d) => d.slice(0, -1));
+      } else if (input && !key.ctrl && !key.meta) {
+        setDraft((d) => d + input);
+      }
+      return;
+    }
+
+    if (key.upArrow) setCursor((c) => (c - 1 + total) % total);
+    else if (key.downArrow) setCursor((c) => (c + 1) % total);
+    else if (key.escape) onRespond({ kind: "dismissed" });
+    else if (input === "e") setMode("custom");
+    else if (input >= "1" && input <= "9") {
+      const i = Number(input) - 1;
+      if (i < options.length) {
+        if (multiSelect) {
+          setCursor(i);
+          toggle(i);
+        } else {
+          onRespond({ kind: "selected", indices: [i] });
+        }
+      }
+    } else if (input === " " && multiSelect && cursor < options.length) {
+      toggle(cursor);
+    } else if (key.return) {
+      confirm();
+    }
+  });
+
+  if (mode === "custom") {
+    return (
+      <Box flexDirection="column" marginTop={1} borderStyle="round" borderColor={theme.accent} paddingX={1}>
+        <Text bold color={theme.accent}>
+          {question.question}
+        </Text>
+        <Text>
+          <Text color={theme.dim}>your answer: </Text>
+          {draft}
+          <Text color={theme.accent}>▏</Text>
+        </Text>
+        <Text dimColor>enter submit · esc back to options</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" marginTop={1} borderStyle="round" borderColor={theme.accent} paddingX={1}>
+      <Text bold color={theme.accent}>
+        {question.question}
+      </Text>
+      {options.map((o, i) => {
+        const active = i === cursor;
+        const box = multiSelect ? (checked.has(i) ? "[x] " : "[ ] ") : "";
+        return (
+          <Box key={i} flexDirection="column" marginTop={1}>
+            <Text color={active ? theme.accent : undefined}>
+              <Text color={active ? theme.accent : theme.dim}>{active ? "❯ " : "  "}</Text>
+              <Text color={theme.dim}>{i + 1}. </Text>
+              {box}
+              <Text bold={active}>{o.label}</Text>
+            </Text>
+            {o.description ? <Text dimColor>{"     " + o.description}</Text> : null}
+          </Box>
+        );
+      })}
+      <Box marginTop={1}>
+        <Text color={cursor === otherIndex ? theme.accent : undefined}>
+          <Text color={cursor === otherIndex ? theme.accent : theme.dim}>{cursor === otherIndex ? "❯ " : "  "}</Text>
+          <Text color={theme.dim}>e. </Text>
+          <Text bold={cursor === otherIndex}>Something else — write your own answer</Text>
+        </Text>
+      </Box>
+      <Text dimColor>
+        {multiSelect
+          ? "↑/↓ move · space toggle · enter confirm · esc skip"
+          : "↑/↓ move · 1–" + options.length + " pick · enter confirm · esc skip"}
+      </Text>
+    </Box>
+  );
+}

package/src/components/Root.tsx

@@ -1,4 +1,5 @@
 import React, { useState } from "react";
+import { useStdout } from "ink";
 import { App } from "./App.tsx";
 import { Onboarding, type OnboardingResult } from "./Onboarding.tsx";
 import { PrivateerLogin } from "./PrivateerLogin.tsx";
@@ -30,6 +31,17 @@ export function Root({
   const [modelSpec, setModelSpec] = useState(initialModel);
   const [onboarding, setOnboarding] = useState(startInOnboarding);
   const [loggingIn, setLoggingIn] = useState(false);
+  const { stdout } = useStdout();
+
+  // The App's banner/transcript lives in Ink's <Static> region, which stays in the
+  // terminal scrollback even after the component unmounts. Swapping screens (login,
+  // onboarding) and back therefore stacks a second banner under the stale one. Wipe
+  // screen + scrollback around every top-level swap so each view starts on a clean
+  // page — same trick App uses when the terminal is resized.
+  function swapScreen(update: () => void) {
+    stdout?.write("\x1b[2J\x1b[3J\x1b[H"); // clear screen + scrollback, home cursor
+    update();
+  }
 
   // Providers that already have credentials — pre-checked when re-running onboarding.
   const configured = configuredProviders(config)
@@ -47,9 +59,11 @@ export function Root({
     } catch {
       /* non-fatal: keys just won't persist to disk this run */
     }
-    setConfig(next);
-    setModelSpec(result.defaultModel);
-    setOnboarding(false);
+    swapScreen(() => {
+      setConfig(next);
+      setModelSpec(result.defaultModel);
+      setOnboarding(false);
+    });
   }
 
   // After a successful account login, switch to the Privateer-billed model so the
@@ -68,13 +82,20 @@ export function Root({
     } catch {
       /* non-fatal: model choice just won't persist this run */
     }
-    setConfig(next);
-    setModelSpec(spec);
-    setLoggingIn(false);
+    swapScreen(() => {
+      setConfig(next);
+      setModelSpec(spec);
+      setLoggingIn(false);
+    });
   }
 
   if (loggingIn) {
-    return <PrivateerLogin onComplete={finishLogin} onCancel={() => setLoggingIn(false)} />;
+    return (
+      <PrivateerLogin
+        onComplete={finishLogin}
+        onCancel={() => swapScreen(() => setLoggingIn(false))}
+      />
+    );
   }
 
   if (onboarding) {
@@ -88,8 +109,8 @@ export function Root({
       config={config}
       cwd={cwd}
       resume={resume}
-      onLogin={() => setOnboarding(true)}
-      onPrivateerLogin={() => setLoggingIn(true)}
+      onLogin={() => swapScreen(() => setOnboarding(true))}
+      onPrivateerLogin={() => swapScreen(() => setLoggingIn(true))}
     />
   );
 }

package/src/components/ToolCallView.tsx

@@ -21,6 +21,10 @@ function summarizeInput(name: string, input: unknown): string {
       return String(o.pattern ?? "") + (o.glob ? ` (${o.glob})` : "");
     case "task":
       return String(o.description ?? o.subagent_type ?? "");
+    case "ask_user":
+      return String(o.question ?? "");
+    case "worktree":
+      return String(o.action ?? "") + (o.name ? ` ${o.name}` : "");
     default:
       try {
         return JSON.stringify(o);

package/src/components/Transcript.tsx

@@ -102,20 +102,26 @@ export function EntryView({
       // Split off a trailing `recap:` line so it can render dimmed below the
       // response body. The model is asked to end each turn with one such line.
       const { body, recap } = splitRecap(entry.text);
+      const hasBody = body.trim().length > 0;
+      // Nothing to paint: a whitespace-only entry (possible in transcripts
+      // persisted before the turn loop filtered them) would render a bare ⏺.
+      if (!hasBody && !recap) return null;
       // ⏺ bullet in its own column so wrapped lines align under the text.
       return (
         <Box marginTop={1} flexDirection="column">
-          <Box>
-            <Text color={theme.accent}>{BULLET} </Text>
-            <Box width={bodyWidth}>
-              <Markdown text={body} />
+          {hasBody && (
+            <Box>
+              <Text color={theme.accent}>{BULLET} </Text>
+              <Box width={bodyWidth}>
+                <Markdown text={body} />
+              </Box>
             </Box>
-          </Box>
+          )}
           {recap && (
-            <Box marginTop={1}>
+            <Box marginTop={hasBody ? 1 : 0}>
               <Text color={theme.dim}>{"  "}</Text>
               <Box width={bodyWidth}>
-                <Text color="white">
+                <Text color={theme.dim} dimColor italic>
                   {recap}
                 </Text>
               </Box>
@@ -127,6 +133,7 @@ export function EntryView({
     case "thinking": {
       // The model's reasoning, rendered dimmed under a thinking mark. When
       // collapsed (Ctrl+O), show just a one-line summary instead of the full text.
+      if (entry.text.trim() === "") return null;
       if (collapsed) {
         const lineCount = entry.text.trim() === "" ? 0 : entry.text.trim().split("\n").length;
         return (

package/src/components/theme.ts

@@ -50,6 +50,8 @@ const TOOL_DISPLAY: Record<string, string> = {
   task: "Task",
   web_fetch: "WebFetch",
   web_search: "WebSearch",
+  ask_user: "AskUser",
+  worktree: "Worktree",
 };
 
 export const toolDisplayName = (name: string): string => TOOL_DISPLAY[name] ?? name;

package/src/config/paths.ts

@@ -35,6 +35,7 @@ export interface ScopePaths {
   settingsLocal: string; // settings.local.json — gitignored local overrides
   commands: string; // commands/ — custom slash commands (M2)
   agents: string; // agents/ — custom subagents (M4)
+  skills: string; // skills/ — agent skills, one SKILL.md directory each
   outputStyles: string; // output-styles/ — persona prompts (M2)
   mcp: string; // mcp.json — MCP server declarations (M4)
 }
@@ -47,6 +48,7 @@ function scopePaths(dir: string): ScopePaths {
     settingsLocal: join(dir, "settings.local.json"),
     commands: join(dir, "commands"),
     agents: join(dir, "agents"),
+    skills: join(dir, "skills"),
     outputStyles: join(dir, "output-styles"),
     mcp: join(dir, "mcp.json"),
   };

package/src/context/systemPrompt.ts

@@ -51,6 +51,15 @@ before doing it.
 work is attributed to Privateer as a co-author:
   Co-Authored-By: Privateer <291203302+privateer-first-mate@users.noreply.github.com>
 - Use 'web_fetch' to read a known URL when the user provides one or you need current docs.
+- When the implementation direction is genuinely ambiguous and the choice materially shapes the \
+work — a structural/architectural fork, which library or data model to adopt, the scope of a \
+change — don't silently guess. Lay out the realistic approaches and call 'ask_user' to let the \
+user pick (2–4 options, most-recommended first, each with its trade-offs). Reserve it for \
+consequential forks: for small, reversible choices, just make the call and proceed. After the \
+user chooses, build that direction without re-litigating it.
+- To try a risky or exploratory approach without disturbing the main tree, use 'worktree' to spin \
+up an isolated branch + working copy, do the work there, and let the user compare its diff before \
+keeping or discarding it.
 - Mutating actions (write/edit/bash) may require user approval; that's expected — proceed and let \
 the gate handle it.`;
 

package/src/daemon/index.ts

@@ -0,0 +1,322 @@
+import type { Server } from "node:net";
+import type { ToolSet } from "ai";
+import { loadConfig } from "../config/load.ts";
+import { createSession } from "../session.ts";
+import { autoApproveGate } from "../permissions/gate.ts";
+import { loadMcpServers, connectMcpServers } from "../mcp/client.ts";
+import { RelayClient } from "../remote/relayClient.ts";
+import { hasCredentials, revokeChildSession } from "../auth/privateer.ts";
+import {
+  loadRoutines,
+  upsertRoutine,
+  findRoutine,
+  removeRoutine,
+  addPendingRelay,
+  drainPendingRelay,
+  routineRelayId,
+} from "../routines/store.ts";
+import type { Routine } from "../routines/schema.ts";
+import { triggerError, computeNextRun, advanceAfterRun } from "../routines/trigger.ts";
+import { splitRoutineTools, filterMcpTools } from "../routines/toolSelect.ts";
+import { deliver, type RelayPusher } from "../routines/delivery.ts";
+import { startIpcServer, type IpcRequest, type IpcResponse } from "./ipc.ts";
+
+// The safe, read-only-plus-web toolset for unattended runs. No write/edit/bash, so
+// a routine firing with nobody watching can't mutate the filesystem or shell out.
+const SAFE_TOOLS = ["read", "glob", "grep", "web_fetch", "web_search"];
+
+const TICK_MS = 60_000; // scan for due routines once a minute
+
+function log(msg: string): void {
+  process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
+}
+
+// Render a run's result as a self-contained markdown document for file/notice output.
+function formatResult(routine: Routine, body: string, status: "ok" | "error", error?: string): string {
+  const when = new Date().toISOString();
+  const head = `# ${routine.name}\n\n_${when} · ${status}${routine.model ? ` · ${routine.model}` : ""}_\n\n`;
+  if (status === "error") return `${head}**Run failed:** ${error ?? "unknown error"}\n\n${body}`.trimEnd() + "\n";
+  return `${head}${body.trim() || "(no output)"}\n`;
+}
+
+export class Daemon {
+  private server?: Server;
+  private timer?: ReturnType<typeof setInterval>;
+  private readonly startedAt = Date.now();
+  // Set of routine ids currently executing, so a slow run can't be re-entered by
+  // the next tick.
+  private readonly running = new Set<string>();
+  // Outbound relay connection to the Privateer server, opened lazily when a signed-in
+  // user has a routine that delivers over `relay`. Pushes results to an attached
+  // controller (e.g. the mobile app) in real time.
+  private relay?: RelayClient;
+  // Best-effort "is a controller attached right now?" — set on controller_attached,
+  // cleared when our socket drops. Used to decide push-live vs queue-for-later.
+  private controllerAttached = false;
+  // The app sent `terminate` (End remote access): keep the relay down until the
+  // daemon restarts, even if routine edits re-run syncRelay. Results still queue
+  // durably and deliver over the other channels meanwhile.
+  private relayTerminated = false;
+  // Push a result live if a controller is attached; otherwise persist it to the
+  // pending queue so it flushes the moment the app next attaches. Either path is
+  // durable, so delivery treats both as handled.
+  private readonly pushRelay: RelayPusher = (routine, content) => {
+    if (this.controllerAttached && this.relay?.sendRoutineResult(routine.name, content)) return "live";
+    addPendingRelay({ routine: routine.name, at: new Date().toISOString(), content });
+    return "queued";
+  };
+
+  start(): void {
+    // Prime nextRun for any routine missing one, then start the loop + IPC server.
+    this.primeSchedule();
+    this.timer = setInterval(() => void this.tick(), TICK_MS);
+    this.server = startIpcServer((req) => this.handleIpc(req));
+    this.syncRelay();
+    const count = loadRoutines().filter((r) => r.enabled).length;
+    log(`daemon started (pid ${process.pid}); ${count} enabled routine(s). Tick every ${TICK_MS / 1000}s.`);
+    // Fire an immediate scan so a just-due routine doesn't wait a full minute.
+    void this.tick();
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.server?.close();
+    this.relay?.stop();
+  }
+
+  // Open the relay connection when it's both wanted (a signed-in account + at least
+  // one enabled routine delivering over `relay`) and not already up. Started ahead
+  // of fire time so it's connected when a routine actually pushes. We never tear it
+  // down once up — an idle authenticated socket is cheap and reconnects itself.
+  private syncRelay(): void {
+    if (this.relay || this.relayTerminated) return;
+    if (!hasCredentials()) return;
+    const wantsRelay = loadRoutines().some((r) => r.enabled && r.delivery.includes("relay"));
+    if (!wantsRelay) return;
+    this.relay = new RelayClient({
+      // The daemon publishes results but is not a drivable terminal: ignore any
+      // prompts/approvals a controller might send.
+      onPrompt: () => {},
+      onInterrupt: () => {},
+      onApprovalResponse: () => {},
+      onControllerAttached: () => this.onControllerAttached(),
+      onAttachment: () => {},
+      onTerminate: () => {
+        this.relayTerminated = true;
+        this.controllerAttached = false;
+        this.relay?.stop();
+        this.relay = undefined;
+        log("relay terminated from the app; staying offline until the daemon restarts");
+      },
+      onStatus: (text) => log(`relay: ${text}`),
+      onDisconnected: () => {
+        this.controllerAttached = false;
+      },
+    }, {
+      // Stable identity so the daemon shows up as one recognizable terminal in the
+      // app across restarts, instead of a fresh random "terminal-xxxx" each boot.
+      termId: routineRelayId(),
+      label: "Privateer Routines",
+    });
+    void this.relay.start();
+    log("relay connection starting (routine has relay delivery + account signed in)");
+  }
+
+  // The app attached: greet it, then flush any routine results that finished while it
+  // was closed so it catches up immediately (in fire order).
+  private onControllerAttached(): void {
+    this.controllerAttached = true;
+    this.relay?.sendSnapshot([{ kind: "notice", text: "Privateer routines — results will appear here as they run." }]);
+    const pending = drainPendingRelay();
+    if (pending.length === 0) return;
+    log(`controller attached — flushing ${pending.length} pending routine result(s)`);
+    for (const p of pending) this.relay?.sendRoutineResult(p.routine, p.content);
+  }
+
+  private primeSchedule(): void {
+    for (const r of loadRoutines()) {
+      if (!r.enabled) continue;
+      if (r.nextRun && !Number.isNaN(Date.parse(r.nextRun))) continue;
+      const nr = computeNextRun(r);
+      if (nr) this.persistRun(r.id, { nextRun: nr.toISOString() });
+    }
+  }
+
+  private async tick(): Promise<void> {
+    const now = Date.now();
+    for (const r of loadRoutines()) {
+      if (!r.enabled || this.running.has(r.id)) continue;
+      if (triggerError(r)) continue; // skip malformed triggers
+      if (!r.nextRun) {
+        const nr = computeNextRun(r);
+        this.persistRun(r.id, { nextRun: nr?.toISOString() });
+        continue;
+      }
+      if (Date.parse(r.nextRun) <= now) {
+        await this.runRoutine(r);
+      }
+    }
+  }
+
+  // Execute a routine to completion and deliver the result. Advances nextRun past
+  // now afterwards (skipping any backlog) so at most one run fires per tick.
+  async runRoutine(routine: Routine): Promise<IpcResponse> {
+    if (this.running.has(routine.id)) return { ok: false, message: "already running" };
+    this.running.add(routine.id);
+    log(`running routine "${routine.name}"`);
+
+    const config = loadConfig();
+    const modelSpec = routine.model ?? config.defaultModel;
+    const split = splitRoutineTools(routine.tools);
+    // If the routine names no builtin tools, it still gets the safe read/web set —
+    // a routine that only lists MCP selectors shouldn't lose the ability to read.
+    const allowedTools = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const wantsEmail = routine.delivery.includes("email");
+
+    // MCP tools are fulfilled inside the agent turn. Two grants exist: explicit
+    // "<server>__<tool>" selectors in routine.tools (least privilege: only the named
+    // servers are launched and only the selected tools exposed), and the legacy email
+    // delivery, which exposes every configured server so the mail tool is reachable.
+    // Either way, egress stays an explicit tool action rather than a side channel.
+    let extraTools: ToolSet | undefined;
+    let closeMcp: (() => void) | undefined;
+    let prompt = routine.prompt;
+    if (split.mcp.length > 0 || wantsEmail) {
+      try {
+        const all = loadMcpServers(routine.cwd);
+        for (const s of split.servers) {
+          if (!all[s]) log(`  mcp: server "${s}" not configured in mcp.json — skipping`);
+        }
+        const servers = wantsEmail
+          ? all
+          : Object.fromEntries(Object.entries(all).filter(([name]) => split.servers.includes(name)));
+        const conn = await connectMcpServers(servers, routine.cwd, autoApproveGate);
+        const selected = filterMcpTools(conn.tools, split.mcp);
+        // Email needs every server's tools (the mail tool isn't in the selectors);
+        // otherwise expose only what the routine was granted.
+        extraTools = wantsEmail ? conn.tools : selected;
+        closeMcp = () => conn.clients.forEach((c) => c.close());
+        if (split.mcp.length > 0 && Object.keys(selected).length === 0) {
+          log(`  mcp: selectors matched no tools (${split.mcp.join(", ")})`);
+        }
+        if (wantsEmail) {
+          prompt +=
+            "\n\nWhen finished, email the result to the account owner using the available mail tool " +
+            "(e.g. a Gmail create/send tool). Keep the subject short and put the summary in the body.";
+        }
+      } catch (err) {
+        log(`  mcp setup failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    let out = "";
+    let status: "ok" | "error" = "ok";
+    let error: string | undefined;
+    try {
+      const session = createSession({
+        config,
+        modelSpec,
+        cwd: routine.cwd,
+        gate: autoApproveGate,
+        confineToCwd: true,
+        allowedTools,
+        extraTools,
+      });
+      for await (const ev of session.engine.send(prompt)) {
+        if (ev.type === "text") out += ev.text;
+        else if (ev.type === "error") {
+          status = "error";
+          error = ev.error;
+        }
+      }
+    } catch (err) {
+      status = "error";
+      error = err instanceof Error ? err.message : String(err);
+    } finally {
+      closeMcp?.();
+    }
+
+    const content = formatResult(routine, out, status, error);
+    const report = deliver(routine, content, status, { pushRelay: this.pushRelay });
+    log(`  "${routine.name}" ${status}; delivered via ${report.delivered.join(", ") || "(none)"}`);
+
+    // Recurring routines reschedule; one-offs disable themselves after firing.
+    this.persistRun(routine.id, {
+      lastRun: new Date().toISOString(),
+      lastStatus: status,
+      lastError: error,
+      ...advanceAfterRun(routine),
+    });
+    this.running.delete(routine.id);
+    return { ok: status === "ok", message: report.delivered.join(", ") || undefined };
+  }
+
+  // Merge run bookkeeping into the persisted routine, re-reading first so we don't
+  // clobber concurrent IPC edits (add/pause/remove).
+  private persistRun(id: string, patch: Partial<Routine>): void {
+    const current = findRoutine(loadRoutines(), id);
+    if (!current) return;
+    upsertRoutine({ ...current, ...patch });
+  }
+
+  private async handleIpc(req: IpcRequest): Promise<IpcResponse> {
+    switch (req.cmd) {
+      case "status":
+        return { ok: true, pid: process.pid, uptimeSec: Math.round((Date.now() - this.startedAt) / 1000), routines: loadRoutines() };
+      case "list":
+        return { ok: true, routines: loadRoutines() };
+      case "add": {
+        const err = triggerError(req.routine);
+        if (err) return { ok: false, message: `invalid trigger: ${err}` };
+        const nr = computeNextRun(req.routine);
+        upsertRoutine({ ...req.routine, nextRun: nr?.toISOString() });
+        this.syncRelay(); // connect the relay if this routine introduced relay delivery
+        return { ok: true, message: `routine "${req.routine.name}" saved`, routines: loadRoutines() };
+      }
+      case "remove": {
+        const removed = removeRoutine(req.idOrName);
+        return removed
+          ? { ok: true, message: `removed "${removed.name}"`, routines: loadRoutines() }
+          : { ok: false, message: `no routine "${req.idOrName}"` };
+      }
+      case "pause":
+      case "resume": {
+        const r = findRoutine(loadRoutines(), req.idOrName);
+        if (!r) return { ok: false, message: `no routine "${req.idOrName}"` };
+        const enabled = req.cmd === "resume";
+        const nr = enabled ? computeNextRun(r)?.toISOString() : undefined;
+        upsertRoutine({ ...r, enabled, nextRun: nr });
+        if (enabled) this.syncRelay();
+        return { ok: true, message: `${enabled ? "resumed" : "paused"} "${r.name}"`, routines: loadRoutines() };
+      }
+      case "run-now": {
+        const r = findRoutine(loadRoutines(), req.idOrName);
+        if (!r) return { ok: false, message: `no routine "${req.idOrName}"` };
+        // Fire in the background so the IPC caller isn't blocked on a long run.
+        void this.runRoutine(r);
+        return { ok: true, message: `running "${r.name}" now` };
+      }
+      case "reload":
+        this.primeSchedule();
+        this.syncRelay();
+        return { ok: true, message: "schedule reloaded", routines: loadRoutines() };
+      default:
+        return { ok: false, message: "unknown command" };
+    }
+  }
+}
+
+// Entry point for `privateer daemon`.
+export function runDaemon(): void {
+  const daemon = new Daemon();
+  daemon.start();
+  const shutdown = () => {
+    log("shutting down");
+    daemon.stop();
+    // Release this process's Privateer session so the daemon drops off the
+    // app's Linked Devices immediately (best effort, then exit regardless).
+    void revokeChildSession().finally(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}