privateer-agent 0.14.0 → 0.14.1

package/README.md

@@ -479,10 +479,30 @@ privateer harbor uninstall
 ```
 
 Installs as a **launchd user agent** on macOS or a **`systemd --user` unit** on Linux — no
-root, no sudo. (There's no Windows service path yet; use `privateer harbor run`.)
+root, no sudo. (There's no Windows service path yet; use `privateer harbor run`.) Logs go to
+`~/.privateer/harbor.log` on macOS (kept under 5 MB, one previous copy as `harbor.log.1`) and
+to the journal on Linux: `journalctl --user -u privateer-harbor`.
 
 Everything the harbor does still runs through the permission gate. Actions needing approval
-surface in the app; routines you approved once run on their own schedule.
+surface in the app; routines you approved once run on their own schedule. Unattended runs
+are confined to their working directory and can't read credential stores (`~/.ssh`,
+`~/.aws`, Privateer's own login and config files), whatever tools they're allowed.
+
+**Chat channels** (Telegram, Slack, Discord, WhatsApp) run beside it, as their own service:
+
+```bash
+privateer channels install    # login service; re-run after changing channels from the app
+privateer channels status     # which platforms are live right now
+privateer channels run        # or in the foreground
+```
+
+**On a VPS:** run both as a dedicated, unprivileged user, never root. A routine you allow
+`bash` runs with that user's full rights. Sign in over SSH with `privateer` and `/login` (it
+prints a code to approve in the app). Nothing needs an inbound port, except WhatsApp's
+webhook. The Linux unit sets `NoNewPrivileges`, `UMask=0077` and a restart limit. It skips
+systemd's namespace sandboxing on purpose, because that fails to start on kernels without
+unprivileged user namespaces. In a container with no systemd, use `privateer harbor run`
+under the container's own restart policy.
 
 ## Workflows
 

package/bin/model-args.d.mts

@@ -0,0 +1,9 @@
+// Types for bin/model-args.mjs — plain .mjs because bin/ runs under a bare `node`.
+
+export function modelArgs(o: {
+  launchArgs: string[];
+  envModel?: string;
+  savedDefault?: string | null;
+  signedIn: boolean;
+  computed: string;
+}): string[];

package/bin/model-args.mjs

@@ -0,0 +1,43 @@
+// Which `--model` the launcher hands Pi, if any.
+//
+// Plain .mjs for the same reason as headless-flags.mjs: bin/ runs under a bare `node`,
+// and the launcher runs on import, so the rule lives where a test can reach it.
+// See tests/modelArgs.test.ts.
+//
+// Precedence:
+//   1. a --model the user typed (already in the args) → add nothing
+//   2. PRIVATEER_MODEL → the computed model
+//   3. a saved pick in settings.json → usually add nothing and let Pi resolve it, which
+//      falls back sanely when a BYO model has vanished from the registry. EXCEPT a
+//      `privateer/*` pick on a signed-in machine, which is passed explicitly (below).
+//   4. nothing saved → the computed model
+//
+// Why the exception. Pi resolves a saved default only when that provider HAS AUTH at
+// the moment the session starts (model-resolver.js findInitialModel, step 3), and if not
+// it silently takes the first model that does: with an OPENROUTER_API_KEY around, that
+// is Pi's openrouter default, moonshotai/kimi-k2.6. The account provider's auth is the
+// one `privateer` entry in auth.json, which is machine-global and removed whenever ANY
+// Privateer process exits (it revokes its own account session on the way out). So a
+// launch that happened to follow another process's exit came up on OpenRouter with no
+// message at all, while settings.json still said privateer/near/…. A `-p` run then sent
+// its work to a ZDR provider instead of the enclave the user picked; under --private it
+// refused every tool and said the model was "zdr-policy", which is how this was found.
+//
+// An explicit --model resolves against every REGISTERED model, auth or not
+// (resolveCliModel → getModels()), and the account credential is armed at
+// session_start, before the first prompt. Being signed in is the condition because
+// that is when arming will succeed; signed out, the saved pick couldn't run anyway and
+// Pi's own resolution is no worse.
+
+/**
+ * @param {{ launchArgs: string[], envModel?: string, savedDefault?: string | null, signedIn: boolean, computed: string }} o
+ * @returns {string[]} args to prepend: [] or ["--model", spec]
+ */
+export function modelArgs({ launchArgs, envModel, savedDefault, signedIn, computed }) {
+  if (launchArgs.includes("--model")) return [];
+  if (envModel) return ["--model", computed];
+  if (savedDefault) {
+    return signedIn && savedDefault.startsWith("privateer/") ? ["--model", savedDefault] : [];
+  }
+  return ["--model", computed];
+}

package/bin/privateer-channels.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Launcher for the channels runner (Telegram/Slack/Discord/WhatsApp → agent turns).
+// Mirrors bin/privateer-harbor.mjs: load dev keys from the repo .env WITHOUT changing
+// cwd, register tsx so TS resolves regardless of the invocation cwd, then hand off to
+// the channels CLI dispatcher (whose `run` imports ./boot.ts before any Pi code).
+//
+// Invoked two ways: interactively via the launcher (`privateer channels …`), and by the
+// installed launchd/systemd service (`node privateer-channels.mjs run`). This is what
+// makes channels runnable from an npm install; it used to need a source checkout
+// (`npm run channels`, tsx and a .env).
+import { register } from "tsx/esm/api";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "..");
+
+try {
+  process.loadEnvFile(resolve(repo, ".env"));
+} catch {
+  /* no .env — rely on the ambient environment / ~/.privateer */
+}
+
+// Same reason as the harbor: channel sessions load the moat in code, so subagent
+// children need the moat-injecting wrapper rather than a bare `pi`.
+process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
+
+register();
+const { runChannelsCli } = await import(pathToFileURL(resolve(repo, "src/cli/channelsCli.ts")).href);
+await runChannelsCli(process.argv.slice(2));

package/bin/privateer-launch.mjs

@@ -31,6 +31,7 @@ import { applyPatchesIfNeeded, resolveDep } from "./apply-patches.mjs";
 import { routeUpdate } from "./update-route.mjs";
 import { APPROVE_IN_APP_ENV, CLI_SPEND_ENV, PI_SUBCOMMANDS, PRIVATE_ENV, authProblem, extractHeadlessFlags, extractPrivateFlag, privateProblem } from "./headless-flags.mjs";
 import { runToCompletion } from "./run-to-completion.mjs";
+import { modelArgs } from "./model-args.mjs";
 import { filterRespawnArgs, listTerminals, requestFresh, runSupervised } from "./fresh-supervisor.mjs";
 import { configureCompileCache } from "./startup-cache.mjs";
 
@@ -555,6 +556,16 @@ else if (sub === "harbor" || sub === "daemon") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)], { forwardSignals: true });
 }
 
+// --- `privateer channels [run|install|uninstall|status]` -------------------
+// The chat-platform bridges (Telegram/Slack/Discord/WhatsApp). Same shape as the
+// harbor: a resident process, its own launcher, its own optional login service.
+else if (sub === "channels") {
+  sweepLegacyShims();
+  sweepBashLogs();
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-channels.mjs"), ...args.slice(1)], { forwardSignals: true });
+}
+
 // --- `privateer verify` ----------------------------------------------------
 // Check the install that is on this disk right now. Every other trust signal we
 // publish is an install-time one (npm provenance at `npm i`, a checksum inside
@@ -817,14 +828,15 @@ else {
   //   1. a --model the user typed on the privateer command line (already in `args`)
   //   2. PRIVATEER_MODEL — deliberate override, folded into MODEL above
   //   3. a saved pick in settings.json → pass NO flag; Pi resolves it itself (and
-  //      falls back sanely if that model has vanished from the registry)
+  //      falls back sanely if that model has vanished from the registry). Except a
+  //      signed-in `privateer/*` pick, passed explicitly — see bin/model-args.mjs for
+  //      the silent OpenRouter fallback that prevents
   //   4. nothing saved (first run / fresh home) → the computed MODEL above
   //
   // A FUNCTION, called per launch: a fresh agent (bin/fresh-supervisor.mjs) re-reads it,
   // so a model picked in the old session boots the new one instead of being stomped by
   // a first-run --model computed before that pick existed.
   const modelArgsFor = (launchArgs) => {
-    const userPassedModel = launchArgs.includes("--model");
     let savedDefault = null;
     try {
       const s = JSON.parse(fs.readFileSync(path.join(AGENT_DIR, "settings.json"), "utf8"));
@@ -835,7 +847,7 @@ else {
         savedDefault = `${s.defaultProvider}/${s.defaultModel}`;
       }
     } catch { /* absent/unreadable → no saved pick */ }
-    return userPassedModel || (savedDefault && !process.env.PRIVATEER_MODEL) ? [] : ["--model", MODEL];
+    return modelArgs({ launchArgs, envModel: process.env.PRIVATEER_MODEL, savedDefault, signedIn, computed: MODEL });
   };
 
   // Dev convenience: load provider keys from the repo's .env if present.
@@ -866,7 +878,9 @@ else {
   // command, or `privateer fresh` from another terminal can swap this agent for a new
   // process with the old tree reaped. Print/export/version runs have nothing to swap.
   const tuiArgs = (launchArgs) => [...nodeArgs, CLI, ...modelArgsFor(launchArgs), ...extArgs, ...skillArgs, ...launchArgs];
-  if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args));
+  // forwardSignals: a `kill` reaches only this launcher, and a -p run left behind keeps
+  // working (and spending) with nobody waiting for its answer.
+  if (isNonInteractive) runToCompletion(NODE_BIN, tuiArgs(args), { forwardSignals: true });
   else runSupervised(NODE_BIN, (first) => tuiArgs(first ? args : filterRespawnArgs(args)), { home: PRIVATEER_HOME });
 }
 
@@ -1047,7 +1061,8 @@ function printPrivateerHelp(cmd = process.env.PRIVATEER_CMD || "privateer") {
       "Commands:",
       `  ${cmd} init [directory]     Create a starter PRIVATEER.md project-context file`,
       `  ${cmd} update [--all]       Fetch the latest release or newer tool packs`,
-      `  ${cmd} harbor <command>     Manage the resident background Harbor daemon (run/install/uninstall/status)`,
+      `  ${cmd} harbor <command>     Manage Harbor, the always-on agent behind the app (run/install/uninstall/status)`,
+      `  ${cmd} channels <command>   Run chat channels: Telegram, Slack, Discord, WhatsApp (run/install/uninstall/status)`,
       `  ${cmd} verify               Check local installation integrity and patch state`,
       `  ${cmd} acp                  Run as an Agent Client Protocol server (JSON-RPC on stdio)`,
       `  ${cmd} fresh [n]            Replace a running terminal's agent with a new one (stops everything it started)`,

package/extensions/privateer-gate.ts

@@ -41,6 +41,7 @@ import { childSpendAllows } from "../src/permissions/childSpend.ts";
 import { CliSpendLedger, headlessSpendGuidance, isSpendRequest, readCliSpendGrant } from "../src/permissions/cliSpend.ts";
 import { BILLED_MEDIA_TOOLS } from "../src/permissions/classify.ts";
 import { privateModeFromEnv } from "../src/permissions/privateMode.ts";
+import { REPLY_TIMEOUT_ENV, StallWatchdog, replyTimeoutMs } from "../src/engine/stallWatchdog.ts";
 import type { PermissionRequest } from "../src/permissions/gate.ts";
 import { HeadlessAppApprover } from "../src/remote/headlessApproval.ts";
 import { describeErrorText } from "../src/engine/errors.ts";
@@ -772,11 +773,44 @@ export default function privateerControl(pi: any): void {
     };
   });
 
+  // A headless run must not wait forever on a provider that went silent (see
+  // src/engine/stallWatchdog.ts). Armed per request, re-armed by every streamed event,
+  // off between requests. On a stall: say so on stderr, abort the turn, exit non-zero.
+  let stallCtx: any;
+  const stallMs = replyTimeoutMs();
+  const watchdog = new StallWatchdog(stallMs, () => {
+    const secs = Math.round(stallMs / 1000);
+    process.stderr.write(
+      `privateer: no reply from ${currentSpec || "the model"} for ${secs}s — stopped. The provider accepted the ` +
+        `request and then sent nothing.\n  Re-run, or pick another model with --model. ` +
+        `${REPLY_TIMEOUT_ENV}=<seconds> changes the limit (0 turns it off).\n`,
+    );
+    process.exitCode = 1;
+    try {
+      stallCtx?.abort?.();
+    } catch {
+      /* the turn is already ending */
+    }
+  });
+  pi.on("before_provider_request", (_e: any, ctx: any) => {
+    if (!headlessRun) return;
+    stallCtx = ctx;
+    watchdog.arm();
+  });
+  pi.on("message_start", (ev: any) => {
+    if (headlessRun && ev?.message?.role === "assistant") watchdog.arm();
+  });
+  pi.on("message_update", () => {
+    if (headlessRun) watchdog.arm();
+  });
+  pi.on("message_end", () => watchdog.disarm());
+
   // Print mode prints a failed turn's raw SDK text — "401 status code (no body)",
   // "Connection error." — and exits. Follow it with what that means and what to do,
   // on stderr so stdout stays the answer (or the JSON stream).
   pi.on("agent_end", (ev: any) => {
-    if (!headlessRun) return;
+    watchdog.disarm();
+    if (!headlessRun || watchdog.stalled) return; // a stall already said what happened
     const msgs: any[] = Array.isArray(ev?.messages) ? ev.messages : [];
     const last = [...msgs].reverse().find((m) => m?.role === "assistant");
     if (last?.stopReason !== "error" || typeof last.errorMessage !== "string") return;

package/extensions/privateer-hints.ts

@@ -21,11 +21,12 @@
 // /hints on|off persists { hints: { enabled } } in ~/.privateer/config.json (ours;
 // Pi never reads that file) — read-modify-write, preserving unrelated keys.
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { keyText } from "@earendil-works/pi-coding-agent";
 import { configPath, globalDir } from "../src/config/paths.ts";
 import { desktopAppPath } from "../src/config/desktopApp.ts";
+import { writeFileAtomic } from "../src/util/atomicWrite.ts";
 
 const FIRST_MS = 6_000; // a turn shorter than this never shows a tip
 const EVERY_MS = 12_000;
@@ -120,7 +121,7 @@ function persistEnabled(enabled: boolean): void {
   cfg.hints = { ...(cfg.hints ?? {}), enabled };
   try {
     mkdirSync(globalDir(), { recursive: true });
-    writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n");
+    writeFileAtomic(configPath(), JSON.stringify(cfg, null, 2) + "\n");
   } catch {
     /* best effort — the toggle still holds for this session */
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/src/channels/run.ts

@@ -53,6 +53,8 @@ import { modelRegistryOf } from "../providers/piAuthStore.ts";
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
 import { CRYPTO_TOOL_NAMES } from "../tools/crypto.ts";
 import { MEDIA_TOOL_NAMES } from "../tools/media.ts";
+import { rotateLogIfLarge } from "../harbor/logRotate.ts";
+import { logFilePath } from "../harbor/service.ts";
 
 // Read-only default toolset — same rationale as the routines harbor's SAFE_TOOLS:
 // a turn nobody is watching can't mutate the filesystem or shell out. Now that the
@@ -147,10 +149,19 @@ async function main() {
 
   // ── config ──────────────────────────────────────────────────────────────────
   let cfg: any = {};
+  let raw: string;
   try {
-    cfg = JSON.parse(readFileSync(configPath(), "utf8"));
+    raw = readFileSync(configPath(), "utf8");
   } catch {
-    log(`no config at ${configPath()} — add a channels block (see run.ts header).`);
+    // Nothing configured yet is a clean exit (see the no-bridges case below for why).
+    log(`no config at ${configPath()} — add a channels block (see run.ts header), or set channels up from the app.`);
+    process.exit(0);
+  }
+  try {
+    cfg = JSON.parse(raw);
+  } catch (e) {
+    // A config that exists but won't parse IS a failure: say so, and exit non-zero.
+    log(`can't parse ${configPath()}: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(1);
   }
   const ch = cfg.channels ?? {};
@@ -404,15 +415,23 @@ async function main() {
   }
 
   if (bridges.length === 0) {
-    log("no channels started — configure a channels.<platform> block in config.json.");
-    process.exit(1);
+    // Exit 0, not 1: under the login service (`privateer channels install`) a failure
+    // exit is restarted, and "nothing configured yet" doesn't get better by retrying —
+    // it got restarted until systemd's start limit, filling the log with this line.
+    // Configure a channel (from the app or config.json), then start it again.
+    log("no channels started — configure a channels.<platform> block in config.json (or from the app), then run `privateer channels install` again.");
+    process.exit(0);
   }
 
   // Heartbeat: announce the live platforms now and refresh on a cadence so the app's
   // channels manager can tell running from merely-configured. A stale/absent file
   // reads as offline (see channels/status.ts).
   writeChannelsStatus(startedPlatforms);
-  const heartbeat = setInterval(() => writeChannelsStatus(startedPlatforms), HEARTBEAT_MS);
+  const heartbeat = setInterval(() => {
+    writeChannelsStatus(startedPlatforms);
+    // Bound the log launchd appends to (macOS service; a no-op elsewhere). See logRotate.ts.
+    if (rotateLogIfLarge(logFilePath("channels"))) log("rotated channels.log (previous kept as channels.log.1)");
+  }, HEARTBEAT_MS);
   heartbeat.unref?.();
 
   const shutdown = () => {

package/src/cli/channelsCli.ts

@@ -0,0 +1,67 @@
+// `privateer channels [run|install|uninstall|status]` dispatcher.
+//
+// ORDERING CONTRACT: `run` dynamically imports channels/run.ts, which imports
+// ./boot.ts first (env pin + attestation dispatcher) and starts on import. The service
+// subcommands touch no Pi code (harbor/service.ts is import-safe), so they don't pay
+// the session-stack import cost.
+
+function usage(): string {
+  return [
+    "Usage: privateer channels [command]",
+    "",
+    "  run          Run the channels in the foreground (default). Bridges every",
+    "               channels.<platform> block in ~/.privateer/config.json.",
+    "  install      Install it as a login service so it starts at login and stays up.",
+    "               Re-run after changing channels from the app: it restarts them.",
+    "  uninstall    Remove the login service.",
+    "  status       Show whether the service is installed and which channels are live.",
+  ].join("\n");
+}
+
+export async function runChannelsCli(argv: string[]): Promise<void> {
+  const sub = argv[0] ?? "run";
+  switch (sub) {
+    case "run": {
+      await import("../channels/run.ts"); // starts on import, installs its own signal handlers
+      return;
+    }
+    case "install": {
+      const { installService } = await import("../harbor/service.ts");
+      try {
+        const info = installService("channels");
+        process.stdout.write(
+          `Channels installed as a login service.\n  unit: ${info.unitPath}\n  logs: ${info.logPath}\n` +
+            "They start now and at every login. Manage with `privateer channels status|uninstall`.\n",
+        );
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+      }
+      return;
+    }
+    case "uninstall": {
+      const { uninstallService } = await import("../harbor/service.ts");
+      try {
+        uninstallService("channels");
+        process.stdout.write("Channels login service removed.\n");
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+      }
+      return;
+    }
+    case "status": {
+      const { channelsStatusReport } = await import("../harbor/service.ts");
+      process.stdout.write((await channelsStatusReport()) + "\n");
+      return;
+    }
+    case "-h":
+    case "--help":
+    case "help":
+      process.stdout.write(usage() + "\n");
+      return;
+    default:
+      process.stderr.write(`Unknown channels command: ${sub}\n\n${usage()}\n`);
+      process.exit(1);
+  }
+}

package/src/config/mediaModels.ts

@@ -18,9 +18,10 @@
  * Missing file, unreadable file and malformed JSON all mean "no choice" — the account
  * default — never a crash in the middle of a tool call.
  */
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { configPath } from "./paths.ts";
+import { writeFileAtomic } from "../util/atomicWrite.ts";
 
 export type MediaKind = "image" | "video";
 
@@ -55,7 +56,7 @@ export function setMediaModelPref(kind: MediaKind, id: string | null): void {
   const next: Record<string, unknown> = { ...cfg, media };
   if (Object.keys(media).length === 0) delete next.media;
   mkdirSync(dirname(configPath()), { recursive: true });
-  writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n");
+  writeFileAtomic(configPath(), JSON.stringify(next, null, 2) + "\n");
 }
 
 /** The model a call should send: its own `model`, else this machine's choice, else none. */

package/src/config/piiAllow.ts

@@ -28,8 +28,9 @@
 // made in an editor is picked up on the next scan, exactly like one made through the
 // command — there is no "restart to apply" step to explain.
 
-import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { configPath } from "./paths.ts";
+import { writeFileAtomic } from "../util/atomicWrite.ts";
 
 let cached: string[] = [];
 let cachedStamp = "";
@@ -89,7 +90,7 @@ function write(entries: string[]): void {
     /* new or unreadable — a fresh object, so one bad file doesn't lose the edit */
   }
   const privacy = { ...((cfg.privacy as Record<string, unknown>) ?? {}), piiAllow: entries };
-  writeFileSync(configPath(), JSON.stringify({ ...cfg, privacy }, null, 2) + "\n");
+  writeFileAtomic(configPath(), JSON.stringify({ ...cfg, privacy }, null, 2) + "\n");
   invalidate();
 }
 

package/src/config/whatsNew.json

@@ -1,10 +1,10 @@
 {
   "$comment": "The banner's What's New list, newest first: the two to four things a returning user should notice, not a changelog. `reviewedFor` is the release this list was last looked at for. A release can't ship until it equals package.json's version (scripts/check-whats-new.mjs, run by `npm test` and by release.yml before anything builds), so every release, patches included, is a deliberate look at this list. If nothing new is worth a line, bumping `reviewedFor` alone is the answer. `since` is the release an entry arrived in. `cmd` is shown in the accent colour.",
-  "reviewedFor": "0.14.0",
+  "reviewedFor": "0.14.1",
   "items": [
+    { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" },
     { "text": "Hand off sensitive files: privateer --private", "since": "0.14.0" },
     { "text": "Open and switch named terminals —", "cmd": "/term", "since": "0.13.0" },
-    { "text": "Voice follows the window you're in", "since": "0.13.0" },
-    { "text": "Searchable model picker —", "cmd": "/models", "since": "0.12.53" }
+    { "text": "Voice follows the window you're in", "since": "0.13.0" }
   ]
 }

package/src/engine/stallWatchdog.ts

@@ -0,0 +1,61 @@
+// A stall watchdog for headless runs.
+//
+// `privateer -p` waits on the model with no limit. A provider that accepts the request
+// and then sends nothing (measured on the account channel: glm-5-2 stalled 5 of 14
+// requests, see providers/defaultModel.ts) leaves the run hanging forever with nothing
+// on stdout. That is what a 14-minute "hang" on 2026-10-02 looked like from the outside;
+// the session file never appeared, because Pi writes it only once a first reply lands.
+//
+// So: armed when a request goes out, re-armed by every streamed event (text, thinking,
+// tool-call deltas all count, so a slow but live stream never trips it), disarmed when
+// the message ends. Between requests (tool execution) it is off — a long local command
+// is not a provider stall. If it fires, the caller aborts the turn and says why.
+//
+// The limit: PRIVATEER_REPLY_TIMEOUT seconds, default 180, 0 turns it off. Silence, not
+// total time, is what is measured, so a long answer is never cut off for being long.
+
+export const REPLY_TIMEOUT_ENV = "PRIVATEER_REPLY_TIMEOUT";
+export const DEFAULT_REPLY_TIMEOUT_MS = 180_000;
+
+/** The stall limit in ms from the environment; 0 means off. Garbage falls back to the default. */
+export function replyTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = (env[REPLY_TIMEOUT_ENV] ?? "").trim();
+  if (!raw) return DEFAULT_REPLY_TIMEOUT_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_REPLY_TIMEOUT_MS;
+  return Math.round(n * 1000);
+}
+
+export class StallWatchdog {
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private fired = false;
+
+  constructor(
+    private readonly ms: number,
+    private readonly onStall: () => void,
+    private readonly timers: { set: typeof setTimeout; clear: typeof clearTimeout } = { set: setTimeout, clear: clearTimeout },
+  ) {}
+
+  /** A request went out, or something streamed: (re)start the silence clock. */
+  arm(): void {
+    if (this.ms <= 0 || this.fired) return;
+    this.disarm();
+    this.timer = this.timers.set(() => {
+      this.timer = undefined;
+      this.fired = true;
+      this.onStall();
+    }, this.ms);
+    // Never the reason a finished run stays alive (see docs/one-shot-exit.md).
+    (this.timer as { unref?: () => void })?.unref?.();
+  }
+
+  /** The message ended, or the run did: nothing to wait on. */
+  disarm(): void {
+    if (this.timer !== undefined) this.timers.clear(this.timer);
+    this.timer = undefined;
+  }
+
+  get stalled(): boolean {
+    return this.fired;
+  }
+}

package/src/harbor/index.ts

@@ -66,6 +66,8 @@ import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlre
 import { serializeBuild } from "./buildLock.ts";
 import { createAccountLease } from "./accountLease.ts";
 import { closeSession } from "./closeSession.ts";
+import { rotateLogIfLarge } from "./logRotate.ts";
+import { logFilePath } from "./service.ts";
 import { isHosted, publishRelayPub, webEnabled, mediaEnabled } from "../config/hosted.ts";
 import { relayExposureAllowed } from "../config/relayExposure.ts";
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
@@ -715,6 +717,8 @@ export class Harbor {
     // returns immediately once a client exists, or while remote access is off.
     this.syncRelay();
     void this.flushPendingCloud();
+    // Bound the log launchd appends us to (see logRotate.ts). A stat a minute.
+    if (rotateLogIfLarge(logFilePath("harbor"))) log("rotated harbor.log (previous kept as harbor.log.1)");
     const now = Date.now();
     for (const r of loadRoutines()) {
       if (!r.enabled || this.running.has(r.id)) continue;

package/src/harbor/logRotate.ts

@@ -0,0 +1,31 @@
+// Keep a service's log file bounded.
+//
+// On macOS launchd appends the harbor's stdout/stderr to ~/.privateer/harbor.log and
+// nothing ever trimmed it — one boot loop once grew it to 7 MB of the same line. The
+// harbor can't rename the file out from under launchd (launchd keeps writing to the
+// renamed file), so this copies it to <log>.1 and truncates it in place. launchd opened
+// it O_APPEND, so its next write lands at the new end rather than leaving a hole.
+// The few lines written between the copy and the truncate are lost; a log is allowed
+// that. On Linux the unit logs to the journal and there is no file — a no-op.
+//
+// IMPORT-SAFETY: node builtins only.
+import { copyFileSync, statSync, truncateSync, chmodSync } from "node:fs";
+
+export const LOG_MAX_BYTES = Number(process.env.PRIVATEER_LOG_MAX_BYTES) || 5 * 1024 * 1024;
+
+/** Rotate `path` when it has grown past `maxBytes`. True when it rotated. Never throws. */
+export function rotateLogIfLarge(path: string, maxBytes: number = LOG_MAX_BYTES): boolean {
+  try {
+    if (statSync(path).size <= maxBytes) return false;
+    copyFileSync(path, `${path}.1`);
+    try {
+      chmodSync(`${path}.1`, 0o600);
+    } catch {
+      /* non-POSIX */
+    }
+    truncateSync(path, 0);
+    return true;
+  } catch {
+    return false; // no file (Linux, a manual foreground run), or unwritable
+  }
+}

package/src/harbor/service.ts

@@ -4,32 +4,57 @@
 // user agent; Linux → systemd --user unit. No root: everything lives under the
 // user's own home and login session.
 //
+// The channels runner (chat platforms → agent turns) installs the same way, as its own
+// unit: every function here takes a ServiceKind, defaulting to the harbor, so the
+// desktop app's calls (installService(), serviceInfo(), …) are unchanged.
+//
 // ORDERING NOTE: this module is import-safe (node builtins + our paths only, no Pi),
 // so the harbor CLI can load it without going through boot.ts.
-import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync, openSync, readSync, closeSync, fstatSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { homedir } from "node:os";
+import { homedir, userInfo } from "node:os";
 import { join, dirname, resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globalDir } from "../config/paths.ts";
 import { harborIsRunning, sendToHarbor, describeRelay, formatDuration, type IpcResponse } from "./ipc.ts";
 
-const LABEL = "pro.privateer.harbor"; // launchd label / reverse-dns id
-const UNIT = "privateer-harbor.service"; // systemd --user unit name
-
-// Pre-rename service identity ("daemon"). Kept ONLY so install/uninstall can evict a
-// service a user installed before the harbor rename — otherwise it lingers as an
-// orphaned launchd agent / systemd unit still running the old launcher. Never written,
-// only torn down.
-const OLD_LABEL = "pro.privateer.daemon";
-const OLD_UNIT = "privateer-daemon.service";
+export type ServiceKind = "harbor" | "channels";
+
+interface ServiceSpec {
+  label: string; // launchd label / reverse-dns id
+  unit: string; // systemd --user unit name
+  launcher: string; // bin/ file the unit runs with "run"
+  description: string;
+  // Pre-rename identity, kept ONLY so install/uninstall can evict a service a user
+  // installed before the harbor rename ("daemon") — otherwise it lingers as an orphaned
+  // launchd agent / systemd unit still running the old launcher. Never written.
+  oldLabel?: string;
+  oldUnit?: string;
+}
 
-// Absolute path to the node launcher that boots + runs the harbor (bin/privateer-harbor.mjs).
+const SPECS: Record<ServiceKind, ServiceSpec> = {
+  harbor: {
+    label: "pro.privateer.harbor",
+    unit: "privateer-harbor.service",
+    launcher: "privateer-harbor.mjs",
+    description: "Privateer resident agent harbor (routines + app-driven task spawns)",
+    oldLabel: "pro.privateer.daemon",
+    oldUnit: "privateer-daemon.service",
+  },
+  channels: {
+    label: "pro.privateer.channels",
+    unit: "privateer-channels.service",
+    launcher: "privateer-channels.mjs",
+    description: "Privateer channels (Telegram/Slack/Discord/WhatsApp chats to agent turns)",
+  },
+};
+
+// Absolute path to the node launcher that boots + runs the service (bin/privateer-*.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-harbor.mjs).
-function harborLauncherPath(): string {
+function launcherPath(kind: ServiceKind): string {
   const here = dirname(fileURLToPath(import.meta.url)); // …/src/harbor
-  return resolve(here, "../../bin/privateer-harbor.mjs");
+  return resolve(here, "../../bin", SPECS[kind].launcher);
 }
 
 // The node binary to bake into the unit. We use the CURRENT interpreter (>=22, the
@@ -39,8 +64,16 @@ function nodeBinaryPath(): string {
   return process.execPath;
 }
 
-function harborLogPath(): string {
-  return join(globalDir(), "harbor.log");
+// The log FILE the service writes to (exported for the in-process rotation, logRotate.ts). macOS only: launchd appends stdout/stderr here.
+// On Linux the unit logs to the journal (see logLocation), which rotates on its own.
+export function logFilePath(kind: ServiceKind = "harbor"): string {
+  return join(globalDir(), `${kind}.log`);
+}
+
+// Where to read this service's log, for humans: a file on macOS, a journalctl command
+// on Linux. Reporting harbor.log on Linux pointed people at a file nothing ever wrote.
+function logLocation(kind: ServiceKind, platform: NodeJS.Platform = process.platform): string {
+  return platform === "linux" ? `journalctl --user -u ${SPECS[kind].unit}` : logFilePath(kind);
 }
 
 // Whether the interpreter we're baking in is an Electron binary rather than a plain
@@ -79,8 +112,8 @@ function forwardedEnv(): Record<string, string> {
 
 // ── macOS (launchd) ─────────────────────────────────────────────────────────────
 
-function launchAgentPath(): string {
-  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+function launchAgentPath(kind: ServiceKind = "harbor"): string {
+  return join(homedir(), "Library", "LaunchAgents", `${SPECS[kind].label}.plist`);
 }
 
 function xmlEscape(s: string): string {
@@ -93,20 +126,20 @@ function xmlEscape(s: string): string {
 // holding the machine lock (exit 0 every ~10s, appending the same line to harbor.log
 // forever — this is what produced a 7 MB log of "already running"), and a deliberate
 // shutdown, which launchd would undo. Matches the systemd unit's Restart=on-failure.
-export function launchdPlist(): string {
-  const args = [nodeBinaryPath(), harborLauncherPath(), "run"];
+export function launchdPlist(kind: ServiceKind = "harbor"): string {
+  const args = [nodeBinaryPath(), launcherPath(kind), "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(harborLogPath());
+  const log = xmlEscape(logFilePath(kind));
   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>
+  <string>${SPECS[kind].label}</string>
   <key>ProgramArguments</key>
   <array>
 ${argXml}
@@ -129,19 +162,21 @@ ${Object.keys(envVars).length ? `  <key>EnvironmentVariables</key>\n  <dict>\n${
 
 // Evict a pre-rename launchd agent (pro.privateer.daemon) if one is installed, so the
 // harbor rename doesn't leave the old service running the old launcher alongside it.
-function evictOldLaunchd(): void {
-  const oldPlist = join(homedir(), "Library", "LaunchAgents", `${OLD_LABEL}.plist`);
+function evictOldLaunchd(kind: ServiceKind): void {
+  const old = SPECS[kind].oldLabel;
+  if (!old) return;
+  const oldPlist = join(homedir(), "Library", "LaunchAgents", `${old}.plist`);
   if (existsSync(oldPlist)) {
     spawnSync("launchctl", ["unload", "-w", oldPlist], { stdio: "ignore" });
     rmSync(oldPlist, { force: true });
   }
 }
 
-function installLaunchd(): void {
-  evictOldLaunchd();
-  const plist = launchAgentPath();
+function installLaunchd(kind: ServiceKind): void {
+  evictOldLaunchd(kind);
+  const plist = launchAgentPath(kind);
   mkdirSync(dirname(plist), { recursive: true });
-  writeFileSync(plist, launchdPlist());
+  writeFileSync(plist, launchdPlist(kind));
   // 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" });
@@ -151,9 +186,9 @@ function installLaunchd(): void {
   }
 }
 
-function uninstallLaunchd(): void {
-  evictOldLaunchd();
-  const plist = launchAgentPath();
+function uninstallLaunchd(kind: ServiceKind): void {
+  evictOldLaunchd(kind);
+  const plist = launchAgentPath(kind);
   if (existsSync(plist)) {
     spawnSync("launchctl", ["unload", "-w", plist], { stdio: "ignore" });
     rmSync(plist, { force: true });
@@ -162,65 +197,122 @@ function uninstallLaunchd(): void {
 
 // ── Linux (systemd --user) ───────────────────────────────────────────────────────
 
-function systemdUnitPath(): string {
+function systemdUnitPath(kind: ServiceKind = "harbor"): string {
   const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(base, "systemd", "user", UNIT);
+  return join(base, "systemd", "user", SPECS[kind].unit);
+}
+
+// One systemd word: double-quoted with C-style escapes, and `%` doubled — systemd
+// expands %-specifiers inside ExecStart= and Environment=, so a path or value with a
+// literal % would otherwise be rewritten (or rejected) when the unit loads.
+function sdQuote(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
 }
 
-function systemdUnit(): string {
-  const exec = [nodeBinaryPath(), harborLauncherPath(), "run"].map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ");
+// The unit, hardened as far as a --user unit can go everywhere:
+//   • NoNewPrivileges — nothing the agent runs can gain privileges (no sudo, no
+//     setuid helpers). A routine allowed `bash` runs with exactly the user's rights.
+//   • UMask=0077 — every file it creates (results, logs, staged media) is owner-only.
+//   • StartLimit* — Restart=on-failure with no limit restarted a harbor that crashes
+//     at boot every few seconds forever; five tries in five minutes, then it stays
+//     down and `systemctl --user status` says why.
+//   • KillMode=mixed — SIGTERM reaches the harbor alone, so its shutdown handler can
+//     revoke its sessions; anything still running (MCP servers it spawned) is killed
+//     after TimeoutStopSec.
+// Deliberately NOT here: ProtectSystem/ProtectHome/PrivateTmp and the rest of the
+// namespace family. In a user manager they need unprivileged user namespaces, and
+// where those are off (many VPS kernels, hardened distros) systemd refuses to start
+// the unit at all (status=226/NAMESPACE). Run the harbor as a dedicated user instead
+// — that is the boundary that works on every box.
+function systemdUnit(kind: ServiceKind = "harbor"): string {
+  const exec = [nodeBinaryPath(), launcherPath(kind), "run"].map(sdQuote).join(" ");
   const envLines = Object.entries(forwardedEnv())
-    .map(([k, v]) => `Environment=${k}=${v}`)
+    .map(([k, v]) => `Environment=${sdQuote(`${k}=${v}`)}`)
     .join("\n");
   return `[Unit]
-Description=Privateer resident agent harbor (routines + app-driven task spawns)
+Description=${SPECS[kind].description}
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=${exec}
 Restart=on-failure
-RestartSec=5
-${envLines}
-
+RestartSec=10
+UMask=0077
+NoNewPrivileges=yes
+KillMode=mixed
+TimeoutStopSec=15
+${envLines ? `${envLines}\n` : ""}
 [Install]
 WantedBy=default.target
 `;
 }
 
+/** The generated systemd unit text (exported for tests). */
+export function systemdUnitText(kind: ServiceKind = "harbor"): string {
+  return systemdUnit(kind);
+}
+
 // Evict a pre-rename systemd --user unit (privateer-daemon.service) if present, so the
 // harbor rename doesn't leave the old unit enabled alongside the new one.
-function evictOldSystemd(): void {
+function evictOldSystemd(kind: ServiceKind): void {
+  const old = SPECS[kind].oldUnit;
+  if (!old) return;
   const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  const oldUnit = join(base, "systemd", "user", OLD_UNIT);
+  const oldUnit = join(base, "systemd", "user", old);
   if (existsSync(oldUnit)) {
-    spawnSync("systemctl", ["--user", "disable", "--now", OLD_UNIT], { stdio: "ignore" });
+    spawnSync("systemctl", ["--user", "disable", "--now", old], { stdio: "ignore" });
     rmSync(oldUnit, { force: true });
     spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
   }
 }
 
-function installSystemd(): void {
-  evictOldSystemd();
-  const unit = systemdUnitPath();
+// The login name to linger. $USER is unset under cron, `su -c`, some container shells
+// and CI — and `loginctl enable-linger ""` silently did nothing, so the service died
+// with the SSH session that installed it. The passwd entry is the reliable answer.
+function loginName(): string {
+  try {
+    return userInfo().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || "";
+  }
+}
+
+function installSystemd(kind: ServiceKind): void {
+  // A box with no systemd user manager (a Docker/LXC container, WSL without systemd)
+  // used to fail with systemctl's own cryptic error. Say what to do instead.
+  const probe = spawnSync("systemctl", ["--user", "show-environment"], { encoding: "utf8" });
+  if (probe.error || probe.status !== 0) {
+    throw new Error(
+      `No systemd user manager here (${(probe.stderr || probe.error?.message || `exit ${probe.status}`).trim()}). ` +
+        `Run \`privateer ${kind} run\` under your own supervisor (a container's restart policy, supervisord, tmux) instead.`,
+    );
+  }
+  evictOldSystemd(kind);
+  const unit = systemdUnitPath(kind);
   mkdirSync(dirname(unit), { recursive: true });
-  writeFileSync(unit, systemdUnit());
+  writeFileSync(unit, systemdUnit(kind));
   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" });
+  const user = loginName();
+  if (user) spawnSync("loginctl", ["enable-linger", user], { stdio: "ignore" });
+  // Clear a StartLimit hit from an earlier, broken install, so --now actually starts it.
+  spawnSync("systemctl", ["--user", "reset-failed", SPECS[kind].unit], { stdio: "ignore" });
+  const r = spawnSync("systemctl", ["--user", "enable", "--now", SPECS[kind].unit], { encoding: "utf8" });
   if (r.status !== 0) {
     throw new Error(`systemctl enable failed: ${(r.stderr || r.stdout || "").trim() || `exit ${r.status}`}`);
   }
 }
 
-function uninstallSystemd(): void {
-  evictOldSystemd();
-  const unit = systemdUnitPath();
-  spawnSync("systemctl", ["--user", "disable", "--now", UNIT], { stdio: "ignore" });
+function uninstallSystemd(kind: ServiceKind): void {
+  evictOldSystemd(kind);
+  const unit = systemdUnitPath(kind);
+  spawnSync("systemctl", ["--user", "disable", "--now", SPECS[kind].unit], { stdio: "ignore" });
   if (existsSync(unit)) rmSync(unit, { force: true });
   spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
 }
@@ -273,10 +365,14 @@ export function unitProgramPaths(platform: NodeJS.Platform, unitPath: string): s
   if (platform === "linux") {
     const line = body.match(/^ExecStart=(.*)$/m);
     if (!line) return null;
-    // Written as single-quoted words with '\'' for an embedded quote (systemdUnit()).
-    const args = [...line[1].matchAll(/'((?:[^']|'\\'')*)'|(\S+)/g)].map((m) =>
-      m[1] !== undefined ? m[1].replace(/'\\''/g, "'") : m[2],
-    );
+    // Today's units write double-quoted words with C escapes and %% (sdQuote). Units
+    // installed before that wrote single-quoted words with '\'' for an embedded quote;
+    // both are still out there, so both parse.
+    const args = [...line[1].matchAll(/"((?:[^"\\]|\\.)*)"|'((?:[^']|'\\'')*)'|(\S+)/g)].map((m) => {
+      if (m[1] !== undefined) return m[1].replace(/\\(.)/g, "$1").replace(/%%/g, "%");
+      if (m[2] !== undefined) return m[2].replace(/'\\''/g, "'");
+      return m[3];
+    });
     return args.length ? args : null;
   }
   return null;
@@ -326,46 +422,69 @@ export function unitNeedsRefresh(platform: NodeJS.Platform, unitPath: string): b
     return false;
   }
   if (platform === "darwin" && /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(body)) return true;
+  // The Linux twin of the always-restart plist: no StartLimitBurst means a harbor that
+  // crashes at boot is restarted every few seconds, forever.
+  if (platform === "linux" && !/^StartLimitBurst=/m.test(body)) return true;
   const args = unitProgramPaths(platform, unitPath);
   if (args?.[0] && interpreterIsElectron(args[0]) && !/ELECTRON_RUN_AS_NODE/.test(body)) return true;
   return false;
 }
 
-function unitPathFor(platform: NodeJS.Platform): string {
-  if (platform === "darwin") return launchAgentPath();
-  if (platform === "linux") return systemdUnitPath();
+function unitPathFor(platform: NodeJS.Platform, kind: ServiceKind): string {
+  if (platform === "darwin") return launchAgentPath(kind);
+  if (platform === "linux") return systemdUnitPath(kind);
   return "";
 }
 
-export function serviceInfo(): ServiceInfo {
+export function serviceInfo(kind: ServiceKind = "harbor"): ServiceInfo {
   const platform = process.platform;
-  const unitPath = unitPathFor(platform);
+  const unitPath = unitPathFor(platform, kind);
   return {
     platform,
     supported: platform === "darwin" || platform === "linux",
     installed: !!unitPath && existsSync(unitPath),
     unitPath,
-    logPath: harborLogPath(),
+    logPath: logLocation(kind, platform),
     needsRefresh: unitNeedsRefresh(platform, unitPath),
     stale: !!unitPath && unitIsStale(platform, unitPath),
   };
 }
 
 // Install the service for the current platform. Idempotent (rewrites + reloads).
-export function installService(): ServiceInfo {
+export function installService(kind: ServiceKind = "harbor"): 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 harbor\` yourself, or keep a terminal open.`);
-  return serviceInfo();
+  if (platform === "darwin") installLaunchd(kind);
+  else if (platform === "linux") installSystemd(kind);
+  else throw new Error(`Auto-start isn't supported on ${platform}. Run \`privateer ${kind}\` yourself, or keep a terminal open.`);
+  return serviceInfo(kind);
 }
 
-export function uninstallService(): ServiceInfo {
+export function uninstallService(kind: ServiceKind = "harbor"): ServiceInfo {
   const platform = process.platform;
-  if (platform === "darwin") uninstallLaunchd();
-  else if (platform === "linux") uninstallSystemd();
+  if (platform === "darwin") uninstallLaunchd(kind);
+  else if (platform === "linux") uninstallSystemd(kind);
   else throw new Error(`No service to remove on ${platform}.`);
-  return serviceInfo();
+  return serviceInfo(kind);
+}
+
+// `privateer channels status`: the unit, and which platforms the runner is serving
+// right now (its heartbeat — channels/status.ts). Imported lazily: status.ts is
+// import-safe, but this module should not pay for it on the harbor's paths.
+export async function channelsStatusReport(): Promise<string> {
+  const info = serviceInfo("channels");
+  const { readRunningPlatforms } = await import("../channels/status.ts");
+  const live = [...readRunningPlatforms()];
+  const lines = [
+    `platform:  ${info.platform}${info.supported ? "" : " (auto-start unsupported — run `privateer channels` manually)"}`,
+    `service:   ${info.installed ? `installed (${info.unitPath})${info.stale ? " — STALE: run `privateer channels uninstall`" : info.needsRefresh ? " — needs rewriting; run `privateer channels install`" : ""}` : "not installed"}`,
+    `channels:  ${live.length ? `serving ${live.join(", ")}` : "not running (no fresh heartbeat)"}`,
+    `logs:      ${info.logPath}`,
+  ];
+  if (info.installed && !live.length) {
+    lines.push("hint:      installed but not serving — check the log. With no channels.<platform> block in config.json it exits on purpose.");
+  }
+  lines.push("note:      channel changes from the app apply on restart (`privateer channels install` restarts it).");
+  return lines.join("\n");
 }
 
 // Human-readable status for `privateer harbor status`: whether the service is
@@ -406,12 +525,20 @@ export async function statusReport(): Promise<string> {
 }
 
 // Best-effort read of the tail of the harbor log (for a `status --log` affordance or
-// error surfacing). Returns "" if absent.
+// error surfacing). Returns "" if absent. Reads only the last `maxBytes` — the log can
+// be megabytes, and this used to load all of it to keep 4 KB.
 export function tailHarborLog(maxBytes = 4_000): string {
+  let fd: number | undefined;
   try {
-    const buf = readFileSync(harborLogPath(), "utf8");
-    return buf.length > maxBytes ? buf.slice(buf.length - maxBytes) : buf;
+    fd = openSync(logFilePath("harbor"), "r");
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, maxBytes);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    return buf.toString("utf8");
   } catch {
     return "";
+  } finally {
+    if (fd !== undefined) closeSync(fd);
   }
 }

package/src/remote/channelsControl.ts

@@ -21,13 +21,14 @@
  * Framework-agnostic: nothing here imports React or the relay. The caller owns the
  * frame plumbing and the running-presence read.
  */
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { configPath } from "../config/paths.ts";
 // The platform roster, per-platform secret field names, and the "is this block
 // startable" predicate all live in ONE place, shared with the channels runtime —
 // see channels/platforms.ts. Re-exported here so existing importers of
 // CHANNEL_PLATFORMS/ChannelPlatform from this module keep working unchanged.
 import { CHANNEL_PLATFORMS, SECRET_FIELDS, isChannelPlatform, type ChannelPlatform } from "../channels/platforms.ts";
+import { writeFileAtomic } from "../util/atomicWrite.ts";
 
 export { CHANNEL_PLATFORMS };
 export type { ChannelPlatform };
@@ -161,7 +162,7 @@ export function makeChannelsControl(opts: {
 
       cfg.channels[draft.platform] = block;
       try {
-        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+        writeFileAtomic(configPath(), JSON.stringify(cfg, null, 2) + "\n");
       } catch (e) {
         return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
       }
@@ -174,7 +175,7 @@ export function makeChannelsControl(opts: {
       if (!cfg.channels?.[platform]) return { ok: false, message: "Not configured." };
       delete cfg.channels[platform];
       try {
-        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+        writeFileAtomic(configPath(), JSON.stringify(cfg, null, 2) + "\n");
       } catch (e) {
         return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
       }

package/src/remote/mcpControl.ts

@@ -35,9 +35,10 @@
  * Framework-agnostic: nothing here imports React or the relay. The caller owns the
  * frame plumbing and the sealed-secret open.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { agentDir } from "../config/paths.ts";
+import { writeFileAtomic } from "../util/atomicWrite.ts";
 
 export type McpTransport = "stdio" | "http";
 
@@ -200,7 +201,7 @@ export function makeMcpControl(opts?: {
 
   function writeSource(src: SourceFile): void {
     mkdirSync(dirname(sourcePath()), { recursive: true });
-    writeFileSync(sourcePath(), JSON.stringify(src, null, 2) + "\n");
+    writeFileAtomic(sourcePath(), JSON.stringify(src, null, 2) + "\n");
     project(src);
   }
 
@@ -220,7 +221,7 @@ export function makeMcpControl(opts?: {
       mcpServers[name] = toStandard(e);
     }
     mkdirSync(dirname(projectionPath()), { recursive: true });
-    writeFileSync(
+    writeFileAtomic(
       projectionPath(),
       JSON.stringify({ mcpServers, settings: { toolPrefix: "server" } }, null, 2) + "\n",
     );

package/src/routines/store.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync, unlinkSync } from "node:fs";
+import { writeFileAtomic } from "../util/atomicWrite.ts";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { globalDir } from "../config/paths.ts";
@@ -64,11 +65,9 @@ export function saveRoutines(routines: Routine[]): void {
   mkdirSync(dir, { recursive: true });
   tryChmod(dir, 0o700);
   const payload: RoutineFile = { routines };
-  writeFileSync(routinesFilePath(), JSON.stringify(payload, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 0o600,
-  });
-  tryChmod(routinesFilePath(), 0o600);
+  // Atomic: a half-written routines.json reads as "no routines" (loadRoutines), and the
+  // next save would then persist only the one routine it was given.
+  writeFileAtomic(routinesFilePath(), JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
 }
 
 // Look up by id first, then by (case-insensitive) name for CLI convenience.
@@ -99,18 +98,48 @@ export function removeRoutine(idOrName: string): Routine | null {
   return target;
 }
 
-// Write a run's result to the routine's output dir: a dated file plus latest.md.
+// Dated result files kept per routine. An hourly routine on an always-on box wrote one
+// every hour, forever; latest.md is what anything reads, and this many is history enough.
+export const ROUTINE_OUTPUT_KEEP = Number(process.env.PRIVATEER_ROUTINE_OUTPUT_KEEP) || 30;
+
+// Write a run's result to the routine's output dir: a dated file plus latest.md, then
+// prune the dated files to the newest ROUTINE_OUTPUT_KEEP. Owner-only, like the rest of
+// the global dir: a result can quote whatever the routine read.
 // Returns the absolute path of latest.md.
 export function writeRoutineOutput(name: string, content: string): string {
   const dir = routineOutputDir(name);
   mkdirSync(dir, { recursive: true });
   const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  writeFileSync(join(dir, `${stamp}.md`), content, "utf8");
+  writeFileSync(join(dir, `${stamp}.md`), content, { encoding: "utf8", mode: 0o600 });
   const latest = join(dir, "latest.md");
-  writeFileSync(latest, content, "utf8");
+  writeFileAtomic(latest, content, { mode: 0o600 });
+  pruneRoutineOutput(dir, ROUTINE_OUTPUT_KEEP);
   return latest;
 }
 
+// Our dated names (ISO with ':' and '.' → '-') sort chronologically as strings, so the
+// oldest are first. Only files of that shape are touched — anything else a user put in
+// the folder is theirs. Best-effort: a prune failure never fails a delivery.
+const DATED_OUTPUT = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.md$/;
+
+export function pruneRoutineOutput(dir: string, keep: number): number {
+  let removed = 0;
+  try {
+    const dated = readdirSync(dir).filter((f) => DATED_OUTPUT.test(f)).sort();
+    for (const f of dated.slice(0, Math.max(0, dated.length - keep))) {
+      try {
+        unlinkSync(join(dir, f));
+        removed++;
+      } catch {
+        /* already gone */
+      }
+    }
+  } catch {
+    /* unreadable dir */
+  }
+  return removed;
+}
+
 // A pending routine result queued for the next interactive session ("notice"
 // delivery). The TUI drains these on startup so results surface even when no
 // terminal was attached at fire time.
@@ -144,7 +173,7 @@ export function addNotice(notice: RoutineNotice): void {
   notices.push(notice);
   // Keep the queue bounded so an offline stretch can't grow it without limit.
   const trimmed = notices.slice(-50);
-  writeFileSync(noticesPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  writeFileAtomic(noticesPath(), JSON.stringify(trimmed, null, 2) + "\n", { mode: 0o600 });
   tryChmod(noticesPath(), 0o600);
 }
 
@@ -189,7 +218,7 @@ export function addPendingRelay(entry: PendingRelay): void {
   const queue = loadPendingRelay();
   queue.push(entry);
   const trimmed = queue.slice(-50); // bound the backlog
-  writeFileSync(pendingRelayPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  writeFileAtomic(pendingRelayPath(), JSON.stringify(trimmed, null, 2) + "\n", { mode: 0o600 });
   tryChmod(pendingRelayPath(), 0o600);
 }
 
@@ -271,6 +300,6 @@ export function addPendingCloud(entry: PendingCloud): void {
 export function savePendingCloud(entries: PendingCloud[]): void {
   const dir = join(globalDir(), "routines");
   mkdirSync(dir, { recursive: true });
-  writeFileSync(pendingCloudPath(), JSON.stringify(entries, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  writeFileAtomic(pendingCloudPath(), JSON.stringify(entries, null, 2) + "\n", { mode: 0o600 });
   tryChmod(pendingCloudPath(), 0o600);
 }

package/src/util/atomicWrite.ts

@@ -0,0 +1,46 @@
+// Replace a file all at once: write a sibling temp file, then rename it over the target.
+//
+// A plain writeFileSync truncates first and writes second, so a crash, a full disk or a
+// kill in between leaves a short or empty file. For the files this is used on that is
+// worse than losing the write: loadRoutines() reads a half-written routines.json as "no
+// routines", and the next save from the app then writes just the one routine it holds —
+// every other routine gone. rename() is atomic on one filesystem, so a reader sees the
+// old file or the new one and never anything between.
+//
+// Permissions carry over from the file being replaced (a config.json someone chmod'ed
+// 0600 stays 0600). A new file gets `mode`, default 0600: everything written through
+// here is config that can hold tokens.
+//
+// IMPORT-SAFETY: node builtins only.
+import { chmodSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+export function writeFileAtomic(path: string, data: string, opts: { mode?: number } = {}): void {
+  // Follow a symlinked config to the file it names, so we replace the file rather than
+  // the link (which would quietly detach a dotfiles-managed config).
+  let target = path;
+  let mode = opts.mode ?? 0o600;
+  try {
+    target = realpathSync(path);
+    if (opts.mode === undefined) mode = statSync(target).mode & 0o777;
+  } catch {
+    /* new file */
+  }
+  const tmp = `${target}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tmp, data, { encoding: "utf8", mode });
+    try {
+      chmodSync(tmp, mode); // writeFileSync's mode is filtered by the umask
+    } catch {
+      /* non-POSIX filesystem */
+    }
+    renameSync(tmp, target);
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* never created */
+    }
+    throw e;
+  }
+}