privateer-agent 0.3.5 → 0.4.0

package/src/daemon/service.ts

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

package/src/ext/permissionGate.ts

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

package/src/permissions/classify.ts

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

package/src/providers/account.ts

@@ -17,8 +17,9 @@ import {
   authedFetch,
   spawnAccountCredentials,
   refreshAccountCredentials,
+  notifySignedIn,
 } from "../auth/privateer.ts";
-import { interpretReport, teePosture, type PrivacyTier } from "pi-privacy";
+import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
 
 // Seed/fallback catalog: registered synchronously so the account provider has real
 // models the instant it loads (before the live /api/models fetch resolves) — in
@@ -73,7 +74,12 @@ export const privateerOAuthProvider = {
   // authentication…" screen hangs with no way out. See auth/privateer.ts
   // pollForToken, which checks the signal and rejects with "Login cancelled.".
   async login(cb: { onDeviceCode?: (info: unknown) => void; signal?: AbortSignal }) {
-    if (!hasCredentials()) {
+    // Fresh machine? The device-code flow below fires notifySignedIn itself (via
+    // pollForToken). Already linked? No device code runs — so we announce the
+    // completed subscription login ourselves at the end, or the header/badge would
+    // keep showing "not signed in" until the next launch.
+    const wasLinked = hasCredentials();
+    if (!wasLinked) {
       try {
         await runDeviceLogin({
           signal: cb.signal,
@@ -94,7 +100,11 @@ export const privateerOAuthProvider = {
       }
     }
     if (cb.signal?.aborted) throw new Error("Login cancelled");
-    return spawnAccountCredentials();
+    const creds = await spawnAccountCredentials();
+    // The fresh path already fired notifySignedIn (pollForToken); fire here for the
+    // already-linked path so the header re-renders to "connected" on this terminal too.
+    if (wasLinked) notifySignedIn();
+    return creds;
   },
   async refreshToken(creds: { refresh: string }) {
     try {
@@ -124,13 +134,11 @@ export interface AccountPosture {
 
 // Posture for an account-channel model. For NEAR models the attestation is fetched
 // through the SERVER proxy (the account's NEAR key stays server-side): the server
-// mints the nonce AND returns the report, so the CLIENT contributes no freshness and
-// can't bind the report to the live TLS key. That is a trust-the-server posture, not
-// client-verified — materially weaker than the direct nearai path (which supplies its
-// own randomNonce). So we must NOT promote it to `tee-verified`: that tier reads as
-// cryptographically proven and, critically, disables pi-privacy's PII gate. We cap a
-// green server posture at `tee-unverified` (honest yellow — the PII gate stays on) and
-// still surface the raw teePosture for display. ZDR-channel models route to
+// mints the nonce and returns the report. A green attestation is trusted as a genuine
+// TEE — promoted to `tee-verified` (green shield "Trusted Execution" in the badge) —
+// so an attested confidential-compute model reads as verified-private. A yellow report
+// stays `tee-unverified` (unconfirmed) and red falls back to `standard`; the raw
+// teePosture is still surfaced for display. ZDR-channel models route to
 // zero-retention endpoints server-side, which we can't observe here — a policy claim.
 export async function accountPosture(modelId: string): Promise<AccountPosture> {
   if (privateerChannel(modelId) === "zdr") {
@@ -144,8 +152,8 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
     const data = (await res.json()) as { nonce?: string; report?: unknown };
     const att = interpretReport(modelId, data.nonce ?? "", data.report ?? {});
     const tp = teePosture(att);
-    // Cap at client-unverifiable: server-proxied green never earns `tee-verified`.
-    const tier: PrivacyTier = tp === "red" ? "standard" : "tee-unverified";
+    // green → tee-verified, yellow → tee-unverified, red → standard.
+    const tier: PrivacyTier = tierFromTeePosture(tp);
     return { tier, teePosture: tp };
   } catch (e) {
     return { tier: "tee-unverified", error: (e as Error).message };

package/src/remote/channelsControl.ts

@@ -0,0 +1,192 @@
+/**
+ * Channel management for the app — the sibling of routinesControl.ts, but for the
+ * messaging-channel config (Telegram/Slack/Discord/WhatsApp) rather than scheduled
+ * routines.
+ *
+ * Like routines, this is owned by the ALWAYS-ON daemon relay (daemon/index.ts),
+ * NOT the channels daemon (channels/run.ts) — which may be down, and which the app
+ * must be able to configure before it has ever run. So this control edits the
+ * `channels` block of ~/.privateer/config.json; the channels daemon adopts changes
+ * on its next RESTART, matching run.ts's deliberate "no in-chat toggle, restart is
+ * the fail-safe reset" posture. `running` is a best-effort read of the channels
+ * daemon's heartbeat (channels/status.ts), never a dependency.
+ *
+ * SECRETS: bot tokens are WRITE-ONLY from the app's perspective. list() NEVER
+ * returns a token value — it reports `configured`, `running`, and `secretsSet`
+ * (which secret fields are present, by name only). save() persists whatever secret
+ * VALUES it is handed in `draft.secrets`; the seal/open of those values in transit
+ * is the caller's job (Phase 3), so this module only ever deals in the plaintext
+ * config.json it already owns.
+ *
+ * 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 { configPath } from "../config/paths.ts";
+
+// The platforms channels/run.ts knows how to start. Order is the app's display
+// order. Keep in sync with the `startChannel` calls in run.ts.
+export const CHANNEL_PLATFORMS = ["telegram", "slack", "discord", "whatsapp"] as const;
+export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+
+const POSTURES = ["readonly", "approve", "auto"] as const;
+export type ChannelPosture = (typeof POSTURES)[number];
+
+// The secret (never-echoed) fields per platform — the union of the token blocks
+// run.ts requires to START each platform. `secretsSet` reports presence of these.
+const SECRET_FIELDS: Record<ChannelPlatform, string[]> = {
+  telegram: ["botToken"],
+  slack: ["appToken", "botToken"],
+  discord: ["botToken"],
+  whatsapp: ["phoneNumberId", "accessToken", "verifyToken", "appSecret"],
+};
+
+// Non-secret projection of one platform's config, sent to the app. No token
+// values, ever — only which secret fields are already present (`secretsSet`).
+export interface RemoteChannel {
+  platform: ChannelPlatform;
+  configured: boolean; // a config block exists for this platform
+  running: boolean; // the channels daemon is currently serving it
+  adminCount: number;
+  memberCount: number;
+  posture: ChannelPosture;
+  tools: string[];
+  model?: string;
+  secretsSet: string[]; // e.g. ["botToken"] — names only, never values
+}
+
+// An app-submitted edit. Non-secret fields REPLACE when present; `secrets` maps a
+// secret field name → its (already-opened) value, and only present, non-empty
+// values overwrite — omitted means "keep the existing value".
+export interface ChannelDraft {
+  platform: ChannelPlatform;
+  admins?: string[];
+  members?: string[];
+  posture?: ChannelPosture;
+  tools?: string[];
+  model?: string;
+  secrets?: Record<string, string>;
+}
+
+export interface ChannelsControl {
+  // All four platforms, always — configured or not — so the app can show empty
+  // slots to set up. Order follows CHANNEL_PLATFORMS.
+  list(): RemoteChannel[];
+  // Create or edit a platform's config. Validates posture + fail-closes on a block
+  // with no admins/members (mirrors run.ts). Returns a one-line result.
+  save(draft: ChannelDraft): { ok: boolean; message?: string };
+  // Delete a platform's config entirely. ok:false when nothing was configured.
+  remove(platform: ChannelPlatform): { ok: boolean; message?: string };
+}
+
+function isPlatform(v: unknown): v is ChannelPlatform {
+  return typeof v === "string" && (CHANNEL_PLATFORMS as readonly string[]).includes(v);
+}
+
+function normalizePosture(v: unknown): ChannelPosture | undefined {
+  return typeof v === "string" && (POSTURES as readonly string[]).includes(v) ? (v as ChannelPosture) : undefined;
+}
+
+function cleanStrList(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out = v.map((x) => String(x ?? "").trim()).filter(Boolean);
+  return out.length > 0 ? out : [];
+}
+
+export function makeChannelsControl(opts: {
+  // Which platforms the channels daemon is serving right now (heartbeat read).
+  // Absent → everything reports not-running.
+  runningPlatforms?: () => Set<string>;
+}): ChannelsControl {
+  const running = opts.runningPlatforms ?? (() => new Set<string>());
+
+  function readCfg(): any {
+    try {
+      return JSON.parse(readFileSync(configPath(), "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  function toRemote(platform: ChannelPlatform, block: any, live: Set<string>): RemoteChannel {
+    const admins = block?.admins ?? block?.allowFrom ?? []; // legacy allowFrom == admins
+    return {
+      platform,
+      configured: !!block,
+      running: live.has(platform),
+      adminCount: Array.isArray(admins) ? admins.length : 0,
+      memberCount: Array.isArray(block?.members) ? block.members.length : 0,
+      posture: normalizePosture(block?.posture) ?? "approve",
+      tools: Array.isArray(block?.tools) ? block.tools.map(String) : [],
+      model: typeof block?.model === "string" ? block.model : undefined,
+      secretsSet: SECRET_FIELDS[platform].filter((f) => block?.[f]),
+    };
+  }
+
+  return {
+    list(): RemoteChannel[] {
+      const ch = readCfg().channels ?? {};
+      const live = running();
+      return CHANNEL_PLATFORMS.map((p) => toRemote(p, ch[p], live));
+    },
+
+    save(draft: ChannelDraft): { ok: boolean; message?: string } {
+      if (!isPlatform(draft?.platform)) return { ok: false, message: "Unknown platform." };
+      if (draft.posture !== undefined && !normalizePosture(draft.posture))
+        return { ok: false, message: "Invalid posture." };
+
+      const cfg = readCfg();
+      cfg.channels ??= {};
+      const block: any = { ...(cfg.channels[draft.platform] ?? {}) };
+
+      // Non-secret fields replace when provided. An explicit empty array clears.
+      const admins = cleanStrList(draft.admins);
+      if (admins !== undefined) block.admins = admins;
+      const members = cleanStrList(draft.members);
+      if (members !== undefined) block.members = members;
+      if (draft.posture !== undefined) block.posture = draft.posture;
+      const tools = cleanStrList(draft.tools);
+      if (tools !== undefined) block.tools = tools;
+      if (draft.model !== undefined) {
+        const m = String(draft.model).trim();
+        if (m) block.model = m;
+        else delete block.model;
+      }
+
+      // Secrets: a present, non-empty value overwrites; omitted keeps the existing.
+      for (const [k, v] of Object.entries(draft.secrets ?? {})) {
+        if (!SECRET_FIELDS[draft.platform].includes(k)) continue;
+        const val = String(v ?? "").trim();
+        if (val) block[k] = val;
+      }
+
+      // Fail-closed: never persist a block that can't authorize anyone (mirrors
+      // run.ts:261 — a channel with no admins/members is skipped anyway).
+      const hasAdmins = Array.isArray(block.admins) && block.admins.length > 0;
+      const hasMembers = Array.isArray(block.members) && block.members.length > 0;
+      if (!hasAdmins && !hasMembers)
+        return { ok: false, message: "Add at least one admin before saving." };
+
+      cfg.channels[draft.platform] = block;
+      try {
+        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+      } catch (e) {
+        return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Saved ${draft.platform}. Restart the channels daemon to apply.` };
+    },
+
+    remove(platform: ChannelPlatform): { ok: boolean; message?: string } {
+      if (!isPlatform(platform)) return { ok: false, message: "Unknown platform." };
+      const cfg = readCfg();
+      if (!cfg.channels?.[platform]) return { ok: false, message: "Not configured." };
+      delete cfg.channels[platform];
+      try {
+        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+      } catch (e) {
+        return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Removed ${platform}. Restart the channels daemon to apply.` };
+    },
+  };
+}