privateer-agent 0.1.1 → 0.2.1

package/src/daemon/ipc.ts

@@ -0,0 +1,127 @@
+import { createServer, createConnection, type Socket, type Server } from "node:net";
+import { existsSync, unlinkSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/load.ts";
+import type { Routine } from "../routines/schema.ts";
+
+// The CLI/TUI talks to the resident daemon over a unix domain socket. The protocol
+// is one JSON request per connection, answered with one JSON response, both
+// newline-terminated. Kept tiny and local — nothing crosses the machine boundary.
+
+export function daemonSocketPath(): string {
+  return join(globalDir(), "daemon.sock");
+}
+
+export type IpcRequest =
+  | { cmd: "status" }
+  | { cmd: "list" }
+  | { cmd: "add"; routine: Routine }
+  | { cmd: "remove"; idOrName: string }
+  | { cmd: "pause"; idOrName: string }
+  | { cmd: "resume"; idOrName: string }
+  | { cmd: "run-now"; idOrName: string }
+  | { cmd: "reload" };
+
+export interface IpcResponse {
+  ok: boolean;
+  message?: string;
+  routines?: Routine[];
+  // Daemon liveness/uptime for `status`.
+  pid?: number;
+  uptimeSec?: number;
+}
+
+export type IpcHandler = (req: IpcRequest) => Promise<IpcResponse> | IpcResponse;
+
+// Start the daemon-side socket server. Returns the Server so the caller can close it.
+export function startIpcServer(handler: IpcHandler): Server {
+  const path = daemonSocketPath();
+  // A stale socket file from a previous crash would block bind; remove it first.
+  if (existsSync(path)) {
+    try {
+      unlinkSync(path);
+    } catch {
+      /* ignore — bind will surface a clearer error */
+    }
+  }
+  const server = createServer((sock: Socket) => {
+    let buf = "";
+    sock.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return; // wait for the full line
+      const line = buf.slice(0, nl);
+      void (async () => {
+        let res: IpcResponse;
+        try {
+          res = await handler(JSON.parse(line) as IpcRequest);
+        } catch (err) {
+          res = { ok: false, message: err instanceof Error ? err.message : String(err) };
+        }
+        sock.end(JSON.stringify(res) + "\n");
+      })();
+    });
+    sock.on("error", () => sock.destroy());
+  });
+  server.listen(path, () => {
+    try {
+      chmodSync(path, 0o600); // owner-only IPC endpoint
+    } catch {
+      /* non-POSIX — best effort */
+    }
+  });
+  return server;
+}
+
+// Client side: send one request, resolve with the response. Rejects if the daemon
+// isn't running (no socket / connection refused) so callers can offer to start it.
+export function sendToDaemon(req: IpcRequest, timeoutMs = 5_000): Promise<IpcResponse> {
+  const path = daemonSocketPath();
+  return new Promise<IpcResponse>((resolve, reject) => {
+    if (!existsSync(path)) {
+      reject(new DaemonNotRunningError());
+      return;
+    }
+    const sock = createConnection(path);
+    let buf = "";
+    const timer = setTimeout(() => {
+      sock.destroy();
+      reject(new Error("daemon did not respond in time"));
+    }, timeoutMs);
+    sock.on("connect", () => sock.end(JSON.stringify(req) + "\n"));
+    sock.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+    });
+    sock.on("end", () => {
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(buf.trim()) as IpcResponse);
+      } catch {
+        reject(new Error("malformed response from daemon"));
+      }
+    });
+    sock.on("error", (err: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      // ECONNREFUSED means a stale socket file with no listener behind it.
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") reject(new DaemonNotRunningError());
+      else reject(err);
+    });
+  });
+}
+
+export class DaemonNotRunningError extends Error {
+  constructor() {
+    super("Privateer daemon is not running. Start it with `privateer daemon`.");
+    this.name = "DaemonNotRunningError";
+  }
+}
+
+// Convenience: is the daemon reachable right now?
+export async function daemonIsRunning(): Promise<boolean> {
+  try {
+    const res = await sendToDaemon({ cmd: "status" }, 2_000);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

package/src/engine/errors.ts

@@ -153,6 +153,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}).`,

package/src/main.tsx

@@ -1,13 +1,18 @@
 import React from "react";
 import { render } from "ink";
 import { Command } from "commander";
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { join } from "node:path";
 import { Root } from "./components/Root.tsx";
 import { NAME, VERSION, DESCRIPTION } from "./version.ts";
-import { loadConfig } from "./config/load.ts";
+import { loadConfig, globalDir } from "./config/load.ts";
 import { createSession } from "./session.ts";
 import { loadLatest, loadSession } from "./memory/store.ts";
 import { configuredProviders } from "./providers/resolve.ts";
 import { describeError } from "./engine/errors.ts";
+import { runDaemon } from "./daemon/index.ts";
+import { revokeChildSession } from "./auth/privateer.ts";
 
 // Set while Ink owns the screen. A stray unhandled rejection while the TUI is up
 // must NOT reach stdout/stderr — Node's default printer dumps the whole error
@@ -58,6 +63,16 @@ async function main() {
     .option("-r, --resume <id>", "resume a specific session by id (printed on exit)")
     .option("--onboard", "run the provider/key setup flow")
     .action(async (promptParts: string[], options: CliOptions) => {
+      // Terminal-window close (SIGHUP) or a kill (SIGTERM) bypasses the normal
+      // exit path below — revoke this terminal's Privateer session first so it
+      // drops off the app's Linked Devices immediately instead of lingering
+      // until server-side expiry. Installing a handler replaces Node's default
+      // terminate-on-signal, so exit explicitly with the conventional code.
+      const revokeAndExit = (code: number) => () => {
+        void revokeChildSession().finally(() => process.exit(code));
+      };
+      process.on("SIGHUP", revokeAndExit(129));
+      process.on("SIGTERM", revokeAndExit(143));
       try {
         if (options.cwd) process.chdir(options.cwd);
         const config = loadConfig();
@@ -79,6 +94,7 @@ async function main() {
 
         if (options.print) {
           await runPrint(modelSpec, promptParts.join(" ").trim(), config.confineToCwd);
+          await revokeChildSession();
           return;
         }
 
@@ -101,6 +117,11 @@ async function main() {
         await waitUntilExit();
         tuiActive = false;
 
+        // This terminal is done — release its Privateer session so it leaves the
+        // app's Linked Devices right away. Started before the resume hint prints
+        // and awaited after, so it doesn't delay the output.
+        const revoked = revokeChildSession();
+
         // On exit, print a hash that resumes this conversation later (à la Claude
         // Code). The latest persisted session carries the id used this run; it only
         // exists once at least one turn has been saved.
@@ -108,6 +129,7 @@ async function main() {
         if (last && last.messages.length > 0) {
           process.stdout.write(`\nResume this session:  ${NAME} --resume ${last.id}\n`);
         }
+        await revoked;
       } catch (err) {
         // Configuration/resolution errors are expected and user-facing — print them
         // cleanly without a stack trace.
@@ -116,6 +138,26 @@ async function main() {
       }
     });
 
+  // The scheduler daemon: a resident process that fires routines on their cron
+  // schedule. Runs in the foreground by default; --detach forks a background copy.
+  program
+    .command("daemon")
+    .description("run the scheduler that fires saved routines on their cron schedule")
+    .option("--detach", "start the daemon in the background and return")
+    .action((opts: { detach?: boolean }) => {
+      if (opts.detach) {
+        const logPath = join(globalDir(), "daemon.log");
+        const out = openSync(logPath, "a");
+        // Re-invoke this same runtime + script without --detach, fully detached.
+        const args = process.argv.slice(1).filter((a) => a !== "--detach");
+        const child = spawn(process.argv[0], args, { detached: true, stdio: ["ignore", out, out] });
+        child.unref();
+        process.stdout.write(`Daemon started in background (pid ${child.pid}).\nLogs: ${logPath}\n`);
+        return;
+      }
+      runDaemon();
+    });
+
   await program.parseAsync(process.argv);
 }
 

package/src/mcp/client.ts

@@ -23,6 +23,10 @@ export interface McpToolDef {
   name: string;
   description?: string;
   inputSchema?: Record<string, unknown>;
+  // Standard MCP behavioral hints. We use `destructiveHint`/`readOnlyHint` to
+  // decide whether a tool may auto-approve: a tool that performs an irreversible
+  // external action marks itself destructive so it ALWAYS reaches the human.
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean };
 }
 
 // Read mcp.json from project then user scope (project overrides). Accepts either a
@@ -148,7 +152,12 @@ export class McpClient {
   async listTools(): Promise<McpToolDef[]> {
     const res = await this.client!.listTools();
     return Array.isArray(res?.tools)
-      ? res.tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema as Record<string, unknown> }))
+      ? res.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema as Record<string, unknown>,
+          annotations: t.annotations as McpToolDef["annotations"],
+        }))
       : [];
   }
 
@@ -184,6 +193,11 @@ export function adaptMcpTools(
   const set: ToolSet = {};
   for (const d of defs) {
     const name = `${server}__${d.name}`;
+    // A mutating tool (e.g. send email, delete file) marks itself destructive. We
+    // map that to `alwaysAsk`, which the gate never auto-approves — so it always
+    // prompts the human (phone on remote turns, terminal otherwise) even under
+    // bypass mode or the allowlist. Read-only tools follow the normal policy.
+    const destructive = d.annotations?.destructiveHint === true && d.annotations?.readOnlyHint !== true;
     set[name] = tool({
       description: d.description ?? `${d.name} (MCP server: ${server})`,
       inputSchema: jsonSchema((d.inputSchema as any) ?? { type: "object", properties: {} }),
@@ -193,6 +207,7 @@ export function adaptMcpTools(
           kind: "fetch",
           title: `MCP ${server}: ${d.name}`,
           detail: JSON.stringify(args ?? {}).slice(0, 120),
+          alwaysAsk: destructive,
         });
         if (decision === "deny") throw new PermissionDeniedError(name);
         return client.callTool(d.name, args);

package/src/permissions/gate.ts

@@ -14,6 +14,11 @@ export interface PermissionRequest {
   title: string; // short action label, e.g. "Run command"
   detail: string; // the command, or file path + change preview
   protected?: boolean; // target is a guarded file: never auto-approve, always prompt
+  // Always require a human decision, ABOVE bypass mode and the allowlist (like a
+  // dangerous shell command). Set for MCP tools that declare themselves
+  // destructive (destructiveHint), so even a "take no prisoners" run can't fire
+  // an irreversible external action silently. The decision is never remembered.
+  alwaysAsk?: boolean;
   // Target resolves outside the working directory: never auto-approve (unless bypass),
   // always prompt. `path` carries the absolute target so "always" can remember its dir.
   outside?: boolean;

package/src/permissions/mode.ts

@@ -27,6 +27,10 @@ export function decideAuto(
   // Dangerous shell (destructive / secret-exfil) always confirms — this sits
   // above bypass and the allowlist so an injected command can't run silently.
   if (req.kind === "bash" && isDangerousCommand(req.detail, denylist)) return "ask";
+  // Explicitly destructive actions (e.g. an MCP tool that declares destructiveHint)
+  // always confirm too — also above bypass, so "skip permissions" can't fire them
+  // blind.
+  if (req.alwaysAsk) return "ask";
   if (mode === "bypass") return "allow";
   // Access outside the working directory always confirms (the user has to explicitly
   // allow leaving cwd), even under acceptEdits or the allowlist.

package/src/permissions/uiGate.ts

@@ -48,9 +48,10 @@ export class ModeGate implements PermissionGate {
 
     if (auto !== "ask") return auto;
 
-    // A dangerous command can be approved once, but is never remembered: adding
-    // it to the allowlist would let a later injected variant slip through.
-    const dangerous = req.kind === "bash" && isDangerousCommand(req.detail, denylist);
+    // A dangerous command (or an always-ask destructive action) can be approved
+    // once, but is never remembered: adding it to the allowlist or relaxing the
+    // mode would let a later variant slip through.
+    const dangerous = req.alwaysAsk === true || (req.kind === "bash" && isDangerousCommand(req.detail, denylist));
 
     const outcome = await this.deps.ask(req);
     if (outcome === "deny") return "deny";

package/src/remote/relayClient.ts

@@ -54,6 +54,11 @@ export interface RelayCallbacks {
   onPrompt: (text: string) => void;
   // The app asked to interrupt the in-flight turn.
   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
+  // callbacks that predate it keep compiling.
+  onTerminate?: () => void;
   // The app answered a relayed approval request.
   onApprovalResponse: (id: string, decision: "allow" | "deny") => void;
   // A controller attached — push a transcript snapshot so it can catch up.
@@ -63,6 +68,8 @@ export interface RelayCallbacks {
   onAttachment: (file: { name: string; mediaType: string; base64: string }) => void;
   // Surface a one-line status/notice in the TUI.
   onStatus?: (text: string) => void;
+  // The relay socket closed (controller no longer reachable until reconnect).
+  onDisconnected?: () => void;
 }
 
 const RECONNECT_MS = 3000;
@@ -71,6 +78,9 @@ const RECONNECT_MS = 3000;
 // memory with a lying `size` or a flood of concurrent transfers.
 const MAX_ATTACH_BYTES = 10 * 1024 * 1024; // 10 MB per file
 const MAX_INFLIGHT_ATTACH = 8; // simultaneous transfers
+// Base64 chars per file_chunk frame for agent→app sends (~135 KB decoded), kept
+// under the relay's 256 KB per-frame cap. Mirrors the app's CHUNK_CHARS.
+const FILE_CHUNK_CHARS = 180_000;
 // Coalesce streaming deltas so we don't emit one WS frame per token.
 const TEXT_FLUSH_MS = 60;
 
@@ -125,9 +135,12 @@ export class RelayClient {
   private bufKind: "text" | "reasoning" | null = null;
   private buf = "";
   private flushTimer: ReturnType<typeof setTimeout> | undefined;
-  // Stable for this process so reconnects keep the same terminal identity.
-  private readonly termId = randomUUID();
-  private readonly label = terminalLabel();
+  // 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
+  // recognizable "Privateer Routines" terminal across restarts instead of a fresh
+  // random one each time).
+  private readonly termId: string;
+  private readonly label: string;
   // In-progress file transfers from the app, keyed by the controller's attachment
   // id. Reassembled from attach_begin/chunk/end frames, then handed to onAttachment.
   private readonly incoming = new Map<
@@ -135,7 +148,13 @@ export class RelayClient {
     { name: string; mediaType: string; chunks: string[]; received: number }
   >();
 
-  constructor(private readonly cb: RelayCallbacks) {}
+  constructor(
+    private readonly cb: RelayCallbacks,
+    opts?: { termId?: string; label?: string },
+  ) {
+    this.termId = opts?.termId ?? randomUUID();
+    this.label = opts?.label ?? terminalLabel();
+  }
 
   async start(): Promise<void> {
     this.closed = false;
@@ -182,6 +201,7 @@ export class RelayClient {
       ws.on("message", (data) => this.handle(data));
       ws.on("close", () => {
         if (this.ws === ws) this.ws = null;
+        this.cb.onDisconnected?.();
         if (!this.closed) {
           this.cb.onStatus?.(
             opened
@@ -247,6 +267,9 @@ export class RelayClient {
       case "interrupt":
         this.cb.onInterrupt();
         break;
+      case "terminate":
+        this.cb.onTerminate?.();
+        break;
       case "approval_response":
         if (frame.id) this.cb.onApprovalResponse(frame.id, frame.decision === "deny" ? "deny" : "allow");
         break;
@@ -320,6 +343,23 @@ export class RelayClient {
 
   // ── agent → controller ──────────────────────────────────────────────────────
 
+  // Is the relay socket currently open? (Not the same as "a controller is
+  // attached" — the server forwards to a controller only when one is present.)
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  // Push a finished routine result to any attached controller as a text event, so
+  // it renders in the app's live feed. Returns whether the socket was open to send
+  // on; a durable channel (file/notice) still backs this up, since we can't know
+  // for certain a controller was attached.
+  sendRoutineResult(name: string, content: string): boolean {
+    if (!this.isConnected()) return false;
+    this.flushDeltas();
+    this.rawSend({ type: "event", event: { type: "text", text: safe(`⏺ Routine "${name}"\n\n${content}`, 8000) } });
+    return true;
+  }
+
   sendEvent(ev: EngineEvent): void {
     if (ev.type === "text") return this.bufferDelta("text", ev.text);
     if (ev.type === "reasoning") return this.bufferDelta("reasoning", ev.text);
@@ -335,6 +375,38 @@ export class RelayClient {
     this.rawSend({ type: "snapshot", entries: trimmed });
   }
 
+  // ── agent → app file transfer (chunked) ─────────────────────────────────────
+  // Reverse of the attach_* path: file_begin → file_chunk* → file_end, each frame
+  // under the relay's 256 KB cap. Fire-and-forget past the socket — the server
+  // drops frames when no controller is attached and there is no ack, so "ok" means
+  // "handed to an open socket", not "the app received it". The payload is base64
+  // binary, so no redactSecrets (it would corrupt the bytes) — the caller decides
+  // what's safe to send.
+  async sendFile(file: {
+    name: string;
+    mediaType: string;
+    base64: string;
+    size: number;
+  }): Promise<{ ok: boolean; reason?: string }> {
+    if (!this.isConnected()) return { ok: false, reason: "relay socket not connected" };
+    if (file.size > MAX_ATTACH_BYTES) {
+      return { ok: false, reason: `exceeds the ${Math.round(MAX_ATTACH_BYTES / (1024 * 1024))} MB relay limit` };
+    }
+    this.flushDeltas(); // land the file in order relative to buffered text
+    const id = randomUUID();
+    this.rawSend({ type: "file_begin", id, name: file.name, mediaType: file.mediaType, size: file.size });
+    for (let off = 0, seq = 0; off < file.base64.length; off += FILE_CHUNK_CHARS, seq++) {
+      if (!this.isConnected()) return { ok: false, reason: "connection lost mid-transfer" };
+      this.rawSend({ type: "file_chunk", id, seq, data: file.base64.slice(off, off + FILE_CHUNK_CHARS) });
+      // Yield between frames of a multi-chunk file so a big send doesn't starve
+      // the event loop (ws buffers internally; no drain dance needed at ≤10 MB).
+      if (file.base64.length > FILE_CHUNK_CHARS) await new Promise((r) => setImmediate(r));
+    }
+    if (!this.isConnected()) return { ok: false, reason: "connection lost mid-transfer" };
+    this.rawSend({ type: "file_end", id });
+    return { ok: true };
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/routines/cron.ts

@@ -0,0 +1,109 @@
+// A minimal standard 5-field cron parser: "minute hour day-of-month month day-of-week".
+// Supports `*`, single numbers, comma lists (`1,15`), ranges (`1-5`), and steps
+// (`*/2`, `0-30/10`). Month (1-12) and day-of-week (0-6, Sunday=0) also accept the
+// usual three-letter names (jan…dec, sun…sat). Kept dependency-free on purpose.
+
+interface CronFields {
+  minute: Set<number>;
+  hour: Set<number>;
+  dom: Set<number>; // day of month
+  month: Set<number>;
+  dow: Set<number>; // day of week, 0=Sun
+  domRestricted: boolean; // field was not "*"
+  dowRestricted: boolean;
+}
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+
+function nameToNum(token: string, names: string[]): string {
+  const i = names.indexOf(token.toLowerCase());
+  return i >= 0 ? String(i + (names === MONTHS ? 1 : 0)) : token;
+}
+
+// Expand one field into the set of matching integers, validating against [min,max].
+function parseField(field: string, min: number, max: number, names?: string[]): Set<number> {
+  const out = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) throw new Error(`invalid step in "${part}"`);
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else {
+      const bounds = rangePart.split("-").map((t) => (names ? nameToNum(t, names) : t));
+      lo = Number(bounds[0]);
+      hi = bounds.length > 1 ? Number(bounds[1]) : lo;
+      if (!Number.isInteger(lo) || !Number.isInteger(hi)) throw new Error(`invalid range "${rangePart}"`);
+      // Allow Sunday as both 0 and 7 for day-of-week.
+      if (max === 6) {
+        if (lo === 7) lo = 0;
+        if (hi === 7) hi = 0;
+      }
+      if (lo < min || hi > max || lo > hi) throw new Error(`out-of-range field "${rangePart}"`);
+    }
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  if (out.size === 0) throw new Error(`empty field "${field}"`);
+  return out;
+}
+
+export function parseCron(expr: string): CronFields {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`cron expression must have 5 fields (got ${parts.length}): "${expr}"`);
+  }
+  const [minute, hour, dom, month, dow] = parts;
+  return {
+    minute: parseField(minute, 0, 59),
+    hour: parseField(hour, 0, 23),
+    dom: parseField(dom, 1, 31),
+    month: parseField(month, 1, 12, MONTHS),
+    dow: parseField(dow, 0, 6, DAYS),
+    domRestricted: dom !== "*",
+    dowRestricted: dow !== "*",
+  };
+}
+
+// Validate an expression, returning an error message or null if it parses.
+export function cronError(expr: string): string | null {
+  try {
+    parseCron(expr);
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+function matches(f: CronFields, d: Date): boolean {
+  if (!f.minute.has(d.getMinutes())) return false;
+  if (!f.hour.has(d.getHours())) return false;
+  if (!f.month.has(d.getMonth() + 1)) return false;
+  // Standard cron: when BOTH day-of-month and day-of-week are restricted, a match
+  // on EITHER is sufficient. When only one is restricted, it alone must match.
+  const domOk = f.dom.has(d.getDate());
+  const dowOk = f.dow.has(d.getDay());
+  if (f.domRestricted && f.dowRestricted) return domOk || dowOk;
+  if (f.domRestricted) return domOk;
+  if (f.dowRestricted) return dowOk;
+  return true;
+}
+
+// The next fire time strictly after `from` (local time), or null if none within a
+// ~4-year horizon (e.g. Feb 30). Seconds/millis are cleared; we scan minute by minute.
+export function nextRun(expr: string, from: Date = new Date()): Date | null {
+  const fields = parseCron(expr);
+  const d = new Date(from.getTime());
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1); // strictly after `from`
+  const limit = 366 * 4 * 24 * 60; // minutes in ~4 years
+  for (let i = 0; i < limit; i++) {
+    if (matches(fields, d)) return d;
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  return null;
+}

package/src/routines/delivery.ts

@@ -0,0 +1,75 @@
+import type { Routine } from "./schema.ts";
+import { writeRoutineOutput, addNotice } from "./store.ts";
+
+// A relay pusher, injected by the daemon. Given the finished result it either
+// forwards it to an attached controller immediately ("live") or persists it to the
+// pending-relay queue to flush when the app next attaches ("queued"). Either way the
+// result is durably accounted for, so delivery doesn't add a notice backstop for it.
+export type RelayPusher = (routine: Routine, content: string) => "live" | "queued";
+
+export interface DeliveryContext {
+  pushRelay?: RelayPusher;
+}
+
+export interface DeliveryReport {
+  // Channels that actually delivered (email is handled inside the agent run, so it
+  // never appears here — see the daemon).
+  delivered: string[];
+  // Absolute path to latest.md when file delivery ran.
+  filePath?: string;
+}
+
+function previewOf(content: string): string {
+  return content.replace(/\s+/g, " ").trim().slice(0, 120) || "(no output)";
+}
+
+// Deliver a routine's result to its configured channels. `file` and `notice` are
+// deterministic and on-box. `relay` pushes to an attached controller in real time
+// (best-effort — the socket may be up with no controller attached), so we ALSO keep
+// a durable record when the routine has no other on-box channel, guaranteeing the
+// result is never silently lost. `email` is intentionally not handled here: it is
+// fulfilled inside the agent turn (the daemon adds the Gmail tool + an instruction
+// to the prompt) so plaintext egress stays an explicit, gated action.
+export function deliver(
+  routine: Routine,
+  content: string,
+  status: "ok" | "error",
+  ctx: DeliveryContext = {},
+): DeliveryReport {
+  const delivered: string[] = [];
+  const wants = new Set(routine.delivery);
+  let filePath: string | undefined;
+  let noticed = false;
+
+  const leaveNotice = () => {
+    if (noticed) return;
+    addNotice({ routine: routine.name, at: new Date().toISOString(), status, preview: previewOf(content), path: filePath });
+    noticed = true;
+  };
+
+  // On-box copy.
+  if (wants.has("file")) {
+    filePath = writeRoutineOutput(routine.name, content);
+    delivered.push("file");
+  }
+
+  // Relay: pushed live to an attached controller, or queued to flush when the app
+  // next attaches (the daemon persists that queue, so it's durable either way). Only
+  // when no pusher is wired at all do we fall back to a notice so it isn't lost.
+  if (wants.has("relay")) {
+    const status = ctx.pushRelay?.(routine, content);
+    if (status === "live") delivered.push("relay");
+    else if (status === "queued") delivered.push("relay(queued)");
+    else if (!wants.has("file") && !wants.has("notice")) {
+      leaveNotice();
+      delivered.push("notice(backstop)");
+    }
+  }
+
+  if (wants.has("notice")) {
+    leaveNotice();
+    delivered.push("notice");
+  }
+
+  return { delivered, filePath };
+}