moshcode 0.89.0 → 0.91.0

package/prd/README.md

@@ -27,4 +27,6 @@ Start one with `moshcode prd "<idea>"` (TUI: `/prd`).
 | [0009](0009-persistent-agent-runtime.md) | Keep the herd alive — a persistent runtime, semantic agent state, and one control surface for humans and agents | Accepted |
 | [0010](0010-cloud-settings-sync.md) | Sync the pit's settings to your moshcode.sh account | Draft |
 | [0011](0011-herd-agent-protocol.md) | Teach the herd the agent protocol — hooks-first state, a task ledger, and an A2A surface for local and remote agents | Draft |
+| [0012](0012-billing-baked-into-the-agent-cli.md) | Bake billing into the agent CLI — timer, clients, teams, rates, invoices, rails | Draft |
+| [0013](0013-persistent-ssh-workspaces.md) | Add persistent SSH workspaces for humans and agents | Draft |
 <!-- PRD-INDEX:END -->

package/src/cli-schema.mjs

@@ -207,6 +207,36 @@ export const CORE_CLI_COMMANDS = [
     seeAlso: ["herd", "ps"],
     note: "this brings back the shape — sessions, directories, engines. the processes are new; work that was in flight is not still running.",
   },
+  {
+    name: "ssh",
+    group: "runtime",
+    description: "persistent SSH workspaces — one connection, many clean commands",
+    synopsis: [
+      ["moshcode ssh", "targets, and whether each one is connected"],
+      ["moshcode ssh <name>", "an interactive shell over the shared connection"],
+      ["moshcode ssh exec <name> [flags] -- <command…>", "one command over it: stdout, stderr and exit status kept apart"],
+      ["moshcode ssh <verb> [args…]", "add, open, check, close, put, get, shell, bench"],
+    ],
+    verbs: "SSH_VERBS",
+    flags: [
+      ["--json", "machine-readable, on every verb that does not take the terminal", ""],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+    ],
+    examples: [
+      ["moshcode ssh add dev deploy@example.com --cwd /srv/app", "a name for a box (or an alias from ~/.ssh/config)"],
+      ["moshcode ssh open dev", "authenticate once"],
+      ["moshcode ssh exec dev -- git status --short", "…then every command reuses it"],
+      ["moshcode ssh exec dev --json -- pnpm test", "exit code, stdout and stderr as one object"],
+      ["git diff | moshcode ssh exec dev --stdin -- git apply -", "a multi-file patch in one round trip"],
+      ["moshcode ssh dev", "a real shell on the same connection"],
+      ["moshcode ssh shell dev --name app", "a remote tmux shell that survives your laptop sleeping"],
+      ["moshcode ssh close dev", "hang up (or let --persist expire)"],
+    ],
+    seeAlso: ["herd", "shell"],
+    note: "nothing secret is stored: targets.json holds a host, a port and a directory, and OpenSSH keeps using your ~/.ssh, "
+      + "agent, known_hosts and ProxyJump exactly as it does at the prompt. `exec` gives every call a fresh command channel — "
+      + "no shell state carries between calls; `shell` is for the workflows that need it.",
+  },
   {
     name: "install",
     group: "engines",
@@ -1325,6 +1355,82 @@ export const HERD_VERBS = [
 // The business layer's verbs. Flatter than the herd's on purpose: these are
 // commands somebody types between other work, and a verb that needs a paragraph
 // to explain itself is a verb in the wrong place.
+export const SSH_VERBS = [
+  { name: "list", description: "every target, and whether its connection is up",
+    synopsis: [["moshcode ssh [list] [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "add", description: "name a box: user@host, or an alias from ~/.ssh/config",
+    synopsis: [["moshcode ssh add <name> <user@host|alias> [--port N] [--cwd PATH] [--persist 10m]", ""]],
+    flags: [
+      ["--port <n>", "ssh port, when ~/.ssh/config does not say", "22"],
+      ["--cwd <path>", "where exec and the interactive shell start", "the remote login directory"],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+      ["--json", "machine-readable", ""],
+    ] },
+  { name: "remove", description: "forget a target (and close its connection)",
+    synopsis: [["moshcode ssh remove <name>", ""]] },
+  { name: "show", description: "one target in full, with its socket and state",
+    synopsis: [["moshcode ssh show <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "open", description: "authenticate once and keep the connection",
+    synopsis: [["moshcode ssh open <name> [--persist 10m] [--batch] [--json]", ""]],
+    flags: [
+      ["--persist <dur>", "how long it outlives its last client", "10m"],
+      ["--batch", "never prompt — fail instead (the default when stdin is not a terminal)", ""],
+      ["--json", "machine-readable; alreadyOpen says whether it was up", ""],
+    ] },
+  { name: "check", description: "is the connection up? (exit 0 yes, 1 no)",
+    synopsis: [["moshcode ssh check <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "close", description: "hang up, with ssh's own -O exit",
+    synopsis: [["moshcode ssh close <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "exec", description: "one command over the connection — no PTY, no shared shell state",
+    synopsis: [["moshcode ssh exec <name> [--cwd PATH] [--env K=V…] [--stdin] [--tty] [--timeout 2m] [--sh] [--json] -- <command…>", ""]],
+    flags: [
+      ["--cwd <path>", "run it here, this once", "the target's cwd"],
+      ["--env <K=V>", "an environment variable for this command only (repeatable)", ""],
+      ["--stdin", "forward this process's stdin, raw", ""],
+      ["--tty", "allocate a terminal (sudo, editors, anything that insists)", ""],
+      ["--timeout <dur>", "kill it after this long — exit 124", ""],
+      ["--sh", "the one argument is a shell snippet, pipes and all", ""],
+      ["--batch", "never prompt for auth — fail instead", ""],
+      ["--json", "{ ok, transportOk, code, signal, stdout, stderr, durationMs }", ""],
+    ],
+    examples: [
+      ["moshcode ssh exec dev -- git status --short", ""],
+      ["moshcode ssh exec dev --json -- grep -rn TODO src", "exit 1 is grep's answer, not a transport failure"],
+      ["moshcode ssh exec dev --sh 'git log --oneline | head -5'", "a pipeline, on purpose"],
+    ] },
+  { name: "put", description: "copy a file up over the connection, atomically",
+    synopsis: [["moshcode ssh put <name> <local> <remote> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "get", description: "copy a file down over the connection",
+    synopsis: [["moshcode ssh get <name> <remote> <local> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "shell", description: "a persistent remote shell in tmux, and the verbs to drive it",
+    synopsis: [
+      ["moshcode ssh shell <name> --name <session>", "create or attach — Ctrl-b d leaves it running"],
+      ["moshcode ssh shell send <name>/<session> <text>", "type a line into it"],
+      ["moshcode ssh shell read <name>/<session> [--lines N]", "its screen, as text"],
+      ["moshcode ssh shell kill <name>/<session>", "end it"],
+      ["moshcode ssh shell list <name>", "every moshcode shell on the box"],
+    ],
+    flags: [
+      ["--name <session>", "which shell", "main"],
+      ["--lines <n>", "how much screen to read", "60"],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode ssh shell dev --name app", ""],
+      ["moshcode ssh shell send dev/app \"pnpm dev\"", ""],
+      ["moshcode ssh shell read dev/app --lines 40", ""],
+    ] },
+  { name: "bench", description: "measure fresh connections against the shared one, on this host",
+    synopsis: [["moshcode ssh bench <name> [--n 20] [--json]", ""]],
+    flags: [["--n <runs>", "how many of each", "20"], ["--json", "machine-readable", ""]] },
+];
+
 export const TIMER_VERBS = [
   { name: "on", description: "start the clock", synopsis: [["moshcode timer on [client] [--task …] [--agents N|auto]", ""]] },
   { name: "off", description: "stop it and write the entry", synopsis: [["moshcode timer off [--note …]", ""]] },
@@ -1377,6 +1483,7 @@ export const PAYMENT_VERBS = [
 
 export const VERB_TABLES = {
   HERD_VERBS,
+  SSH_VERBS,
   TIMER_VERBS,
   CLIENT_VERBS,
   TEAM_VERBS,
@@ -1428,6 +1535,8 @@ export const PIT_COMMANDS = [
     description: "block until a session is blocked or done" },
   { name: "restore", args: "[--resume]", cli: "restore",
     description: "rebuild the herd's sessions after a reboot" },
+  { name: "ssh", args: "[name|verb] [args…]", cli: "ssh",
+    description: "persistent SSH workspaces — one connection, many clean commands" },
   { name: "tools", args: "[name] [args…]", cli: "tools",
     description: "list workflow tools, or run one" },
   { name: "trade", args: "<verb> [args…]", cli: "trade",

package/src/commands.mjs

@@ -22,6 +22,27 @@ import { capture, killSession, remoteStatus, sendPrompt } from "./herd.mjs";
 import { herdStart, isRemoteMember, roster, waitForMany, waitMember } from "./herd-cli.mjs";
 import { endTask, findTask, readTasks, startTask } from "./herd-tasks.mjs";
 import { shellInvocation } from "./shell.mjs";
+import {
+  checkMaster as sshCheckMaster, closeMaster as sshCloseMaster, exec as sshRun, get as sshGetFile,
+  openMaster as sshOpenMaster, parseSessionRef as sshParseSessionRef, parseTimeout as parseSshTimeout,
+  put as sshPutFile, resolveTarget as sshResolve,
+  shellKill as sshShellKillRemote, shellRead as sshShellReadRemote, shellSend as sshShellSendRemote,
+} from "./ssh.mjs";
+
+/** The registry entry for a named ssh target, or a moshscript error naming the verb. */
+function sshTarget(name, verb) {
+  if (!name) throw new Error(`moshscript: ${verb}(name) requires a target name`);
+  const found = sshResolve(String(name));
+  if (found.error) throw new Error(`moshscript: ${verb}: ${found.error.replace(/^ssh: /, "")}`);
+  return found.entry;
+}
+
+/** `dev/app` → the target entry and the session name, or a moshscript error. */
+function sshShellRef(ref, verb) {
+  const parsed = sshParseSessionRef(ref);
+  if (parsed.error) throw new Error(`moshscript: ${verb}: ${parsed.error.replace(/^ssh: /, "")}`);
+  return { found: sshTarget(parsed.name, verb), session: parsed.session };
+}
 import { captureSpec } from "./pty.mjs";
 import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
 import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
@@ -654,6 +675,148 @@ const COMMANDS = [
     },
   },
 
+  // SSH workspaces (PRD 0013 R49–R52). Value-returning for the herd's reason:
+  // a script that runs a command on a remote box wants its stdout back, and a
+  // cliVerb's { ok, code } cannot carry it. Each returns the same object the
+  // CLI prints under --json, so a script and a shell pipeline read one shape.
+  //
+  //   sshOpen("dev");
+  //   const r = sshExec("dev", ["git", "status", "--short"], { cwd: "/srv/app" });
+  //   if (!r.ok) say(r.stderr);
+  //   sshExec("dev", ["git", "apply", "-"], { stdin: patch });
+  //   sshClose("dev");
+  {
+    name: "sshOpen",
+    summary: "authenticate to a named ssh target once and keep the connection",
+    usage: "sshOpen(name, { persist })",
+    detail: "returns { ok, connected, alreadyOpen }; a live connection is left alone",
+    run(ctx, name, opts = {}) {
+      const found = sshTarget(name, "sshOpen");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshOpen(${name}) → would open a master to ${found.target}`); return { ok: true, target: found.name, connected: true, dryRun: true }; }
+      const r = sshOpenMaster(found, { persist: opts.persist, batch: opts.batch });
+      ctx.out(r.ok ? `  🔌 sshOpen(${name}) → ${r.alreadyOpen ? "already connected" : "connected"}` : `  ✗ sshOpen(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshCheck",
+    summary: "is the connection to a target up?",
+    usage: "sshCheck(name)",
+    detail: "returns { connected, stale, pid }; never connects",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshCheck");
+      if (ctx.dryRun) return { target: found.name, connected: false, dryRun: true };
+      const s = sshCheckMaster(found);
+      return { target: found.name, connected: s.connected, stale: s.stale, pid: s.pid ?? null };
+    },
+  },
+  {
+    name: "sshExec",
+    summary: "run one command over the shared connection and RETURN its result",
+    usage: "sshExec(name, [cmd, ...args], { cwd, env, stdin, timeout, sh })",
+    detail: "returns { ok, transportOk, code, signal, stdout, stderr, durationMs }; opens the connection if it is down. ok is the command's verdict, transportOk is ssh's",
+    run(ctx, name, argv, opts = {}) {
+      const found = sshTarget(name, "sshExec");
+      const command = Array.isArray(argv) ? argv.map(String) : [String(argv ?? "")].filter(Boolean);
+      if (!command.length) throw new Error("moshscript: sshExec(name, [command, ...args]) needs a command");
+      if (ctx.dryRun) {
+        ctx.out(`  ▶ sshExec(${name}) → would run on ${found.target}: ${command.join(" ")}`);
+        return { ok: true, transportOk: true, target: found.name, connected: true, code: 0, signal: null, stdout: "", stderr: "", durationMs: 0, dryRun: true };
+      }
+      ctx.out(`  ▶ sshExec(${name}) → ${command.join(" ").slice(0, 60)}${command.join(" ").length > 60 ? "…" : ""}`);
+      const timeoutMs = opts.timeout === undefined ? undefined
+        : (typeof opts.timeout === "number" ? opts.timeout : parseSshTimeout(opts.timeout));
+      const r = sshRun(found, command, {
+        cwd: opts.cwd, remoteEnv: opts.env || {}, stdin: opts.stdin, sh: Boolean(opts.sh), timeoutMs, persist: opts.persist, batch: opts.batch ?? true,
+      });
+      if (!r.transportOk) ctx.out(`  ✗ sshExec(${name}) → ${r.error}`);
+      else if (!r.ok) ctx.out(`  ✗ sshExec(${name}) exited ${r.signal || r.code}`);
+      return r;
+    },
+  },
+  {
+    name: "sshClose",
+    summary: "hang up a target's connection",
+    usage: "sshClose(name)",
+    detail: "returns { ok, closed, wasOpen }",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshClose");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshClose(${name}) → would send -O exit`); return { ok: true, target: found.name, closed: true, dryRun: true }; }
+      const r = sshCloseMaster(found);
+      ctx.out(r.ok ? `  🔌 sshClose(${name}) → ${r.wasOpen ? "closed" : "was not connected"}` : `  ✗ sshClose(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshPut",
+    summary: "copy a local file to a target, atomically",
+    usage: "sshPut(name, local, remote)",
+    detail: "returns { ok, remote }; scp to a temp path over the shared connection, then rename",
+    run(ctx, name, local, remote) {
+      const found = sshTarget(name, "sshPut");
+      if (!local || !remote) throw new Error("moshscript: sshPut(name, local, remote) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📤 sshPut(${name}) → would copy ${local} to ${remote}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshPutFile(found, String(local), String(remote));
+      ctx.out(r.ok ? `  📤 sshPut(${name}) → ${r.remote}` : `  ✗ sshPut(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshGet",
+    summary: "copy a file down from a target",
+    usage: "sshGet(name, remote, local)",
+    detail: "returns { ok, local }",
+    run(ctx, name, remote, local) {
+      const found = sshTarget(name, "sshGet");
+      if (!local || !remote) throw new Error("moshscript: sshGet(name, remote, local) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📥 sshGet(${name}) → would copy ${remote} to ${local}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshGetFile(found, String(remote), String(local));
+      ctx.out(r.ok ? `  📥 sshGet(${name}) → ${r.local}` : `  ✗ sshGet(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellSend",
+    summary: "type a line into a persistent remote shell",
+    usage: 'sshShellSend("dev/app", text)',
+    detail: "returns { ok }; literal text then Enter, into the remote tmux session",
+    run(ctx, ref, ...words) {
+      const { found, session } = sshShellRef(ref, "sshShellSend");
+      const text = words.join(" ");
+      if (!text) throw new Error("moshscript: sshShellSend(ref, text) needs text");
+      if (ctx.dryRun) { ctx.out(`  💬 sshShellSend(${ref}) → would send: ${text}`); return { ok: true, dryRun: true }; }
+      const r = sshShellSendRemote(found, session, text);
+      if (!r.ok) ctx.out(`  ✗ sshShellSend(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellRead",
+    summary: "the screen of a persistent remote shell, as a string",
+    usage: 'sshShellRead("dev/app", { lines })',
+    detail: "returns the text (empty on failure); the same capture-pane the CLI's read prints",
+    run(ctx, ref, opts = {}) {
+      const { found, session } = sshShellRef(ref, "sshShellRead");
+      if (ctx.dryRun) { ctx.out(`  📖 sshShellRead(${ref}) → would capture the pane`); return ""; }
+      const r = sshShellReadRemote(found, session, { lines: opts.lines });
+      if (!r.ok) { ctx.out(`  ✗ sshShellRead(${ref}) → ${r.error}`); return ""; }
+      return r.screen;
+    },
+  },
+  {
+    name: "sshShellKill",
+    summary: "end a persistent remote shell",
+    usage: 'sshShellKill("dev/app")',
+    detail: "returns { ok }",
+    run(ctx, ref) {
+      const { found, session } = sshShellRef(ref, "sshShellKill");
+      if (ctx.dryRun) { ctx.out(`  ☠ sshShellKill(${ref}) → would kill the session`); return { ok: true, dryRun: true }; }
+      const r = sshShellKillRemote(found, session);
+      if (!r.ok) ctx.out(`  ✗ sshShellKill(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+
   // CLI verbs — each is `moshcode <name> ...args`. This is the whole point:
   // scripting the CLI. Add a capability by adding a line here.
   //
@@ -695,6 +858,7 @@ const COMMANDS = [
   cliVerb("elevenlabs", "drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
+  cliVerb("ssh", "persistent SSH workspaces (moshcode ssh <verb>) — see sshExec/sshOpen for values"),
 
   // Research and feeds. The *Read() verbs above return the data; these are the
   // rendered CLI, for when a script wants the table on the operator's screen.

package/src/dns-service.mjs

@@ -29,9 +29,8 @@
 // it, and the entry is the script this very command was invoked from. Nothing
 // is guessed and nothing depends on PATH.
 import { spawn } from "node:child_process";
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { operatorHome } from "./trust.mjs";
 
@@ -48,10 +47,49 @@ export const UNIT_NAME = "moshcode-dns.service";
  * /run/user/<uid>/moshpit-dns.pid for the daemon and for the person asking
  * after it. Under a system unit those are two different paths.
  */
-export function servicePaths({ system = false, home = homedir() } = {}) {
+export function servicePaths({ system = false, home = operatorHome(), env = process.env } = {}) {
   return system
     ? { path: join("/etc/systemd/system", UNIT_NAME), systemctl: ["systemctl"], scope: "system" }
-    : { path: join(home, ".config/systemd/user", UNIT_NAME), systemctl: ["systemctl", "--user"], scope: "user" };
+    : { path: join(home, ".config/systemd/user", UNIT_NAME), systemctl: userSystemctl(env), scope: "user" };
+}
+
+/**
+ * How to reach the operator's own systemd from wherever this is running.
+ *
+ * `systemctl --user` talks to the session of whoever is running it. `dns enable`
+ * escalates, so from there it is root's session — which has no bridge in it, has
+ * never had one, and reports every query about one as "not loaded". Meanwhile
+ * the operator's bridge keeps running with whatever it started with.
+ *
+ * That is why enabling proxy mode could be detected, written, and still not take
+ * effect: the unit that had to change belongs to a session the escalated half of
+ * the command cannot see.
+ *
+ * So an escalated run drops back to the invoking user, and hands them the runtime
+ * directory their session bus lives in — deriving it rather than inheriting it,
+ * because sudo does not carry XDG_RUNTIME_DIR across and the default under sudo
+ * points at root's.
+ */
+export function userSystemctl(env = process.env, { home = operatorHome({ env }), owner = ownerOf } = {}) {
+  const user = env.SUDO_USER || env.DOAS_USER;
+  // Not escalated, or escalated from root itself: the session in reach is the
+  // right one.
+  if (!user || user === "root") return ["systemctl", "--user"];
+  // sudo publishes the uid; doas publishes only the name. Falling back to the
+  // owner of the operator's home covers that, and covers an escalator that
+  // publishes neither — without it, a doas machine would quietly address root's
+  // session, which has no bridge in it and never will.
+  const uid = env.SUDO_UID || env.DOAS_UID || owner(home);
+  if (uid === null || uid === undefined) return ["systemctl", "--user"];
+  return ["sudo", "-u", user, "env", `XDG_RUNTIME_DIR=/run/user/${uid}`, "systemctl", "--user"];
+}
+
+function ownerOf(path) {
+  try {
+    return statSync(path).uid;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -127,6 +165,8 @@ export function serviceUnit({
   return lines.join("\n");
 }
 
+const defaultRead = async (path) => readFile(path, "utf8").catch(() => "");
+
 function run(command, args) {
   return new Promise((resolve) => {
     const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
@@ -140,8 +180,8 @@ function run(command, args) {
 }
 
 /** Write the unit and start it. Returns the steps taken, in order, for printing. */
-export async function installService(unit, { system = false, home = homedir(), exec = run } = {}) {
-  const { path, systemctl, scope } = servicePaths({ system, home });
+export async function installService(unit, { system = false, home = operatorHome(), exec = run, env = process.env } = {}) {
+  const { path, systemctl, scope } = servicePaths({ system, home, env });
   const steps = [];
   try {
     await mkdir(dirname(path), { recursive: true });
@@ -152,7 +192,14 @@ export async function installService(unit, { system = false, home = homedir(), e
   }
 
   const [cmd, ...flags] = systemctl;
-  for (const args of [[...flags, "daemon-reload"], [...flags, "enable", "--now", UNIT_NAME]]) {
+  // Enable *and* restart. `enable --now` starts a stopped unit and does nothing
+  // to a running one, so rewriting the unit to add `--proxy` would leave the old
+  // bridge running without it — the change on disk, no change in behaviour.
+  for (const args of [
+    [...flags, "daemon-reload"],
+    [...flags, "enable", UNIT_NAME],
+    [...flags, "restart", UNIT_NAME],
+  ]) {
     const result = await exec(cmd, args);
     steps.push({ step: `${cmd} ${args.join(" ")}`, ok: result.ok, error: result.error });
     if (!result.ok) return { ok: false, path, scope, steps };
@@ -160,9 +207,119 @@ export async function installService(unit, { system = false, home = homedir(), e
   return { ok: true, path, scope, steps };
 }
 
+/**
+ * The `--upstream` servers an installed unit already forwards to.
+ *
+ * Read back rather than recomputed. A supervised bridge needs upstreams to hand
+ * the clearnet to, and the machine may already be routing every lookup at that
+ * bridge — so asking the system resolver what its upstreams are can answer
+ * "this bridge", and a bridge whose upstream is itself resolves nothing at all.
+ * Whatever the unit was working with is the safe answer to keep.
+ */
+export function unitUpstreams(text) {
+  const line = String(text ?? "").split("\n").find((l) => l.startsWith("ExecStart="));
+  if (!line) return [];
+  const parts = line.trim().split(/\s+/);
+  const found = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    if (parts[i] !== "--upstream") continue;
+    const value = parts[i + 1];
+    if (!value || value.startsWith("--")) continue;
+    if (!found.includes(value)) found.push(value);
+  }
+  return found;
+}
+
+/**
+ * Re-describe the bridge unit to match the run happening now, and restart it so
+ * the description becomes the truth.
+ *
+ * This is the step that made proxy mode arrive one reboot late. A supervised
+ * bridge is not started by `enable`: it is already up under `Restart=always`,
+ * so `startDaemon` finds a live pidfile and reports "already running" — true,
+ * and useless, because what a resolver answers with is fixed when it spawns. A
+ * bridge that came up before the proxy existed goes on answering origins
+ * forever, and stopping it by hand does not help, since systemd brings the same
+ * ExecStart straight back.
+ *
+ * The only thing that changes a supervised bridge's mind is rewriting its unit
+ * and restarting it. That is all this is.
+ *
+ * With no unit installed it does nothing and says so. An unsupervised machine
+ * is `startDaemon`'s business, and writing a unit here would be `enable`
+ * quietly making the bridge outlive a reboot on a machine that never asked for
+ * that — a different decision, and one `dns service --write` exists to make.
+ */
+export async function refreshService({
+  entry,
+  port,
+  registryBase = null,
+  proxy = null,
+  system = false,
+  home = operatorHome(),
+  env = process.env,
+  exec = run,
+  exists = existsSync,
+  read = defaultRead,
+} = {}) {
+  const { path, scope } = servicePaths({ system, home, env });
+  if (!exists(path)) return { refreshed: false, reason: "no unit installed", path, scope, upstreams: [], steps: [] };
+
+  const current = await read(path);
+  const upstreams = unitUpstreams(current);
+  const unit = serviceUnit({ system, entry, port, registryBase, upstreams, proxy });
+
+  // Deliberately not short-circuited on `current === unit`. Matching text says
+  // the unit describes the right bridge, not that the bridge is running it: a
+  // unit can be installed and stopped, installed and never enabled, or running
+  // what it was spawned with before the file last changed. Since the whole
+  // point here is to make what is running match what is written, the enable and
+  // restart happen either way, and cost a moment of no resolver during a
+  // command that is already rewriting the machine's routing.
+
+  const result = await installService(unit, { system, home, env, exec });
+  return {
+    refreshed: result.ok,
+    reason: result.ok ? null : "systemctl refused the unit",
+    path,
+    scope,
+    upstreams,
+    steps: result.steps,
+  };
+}
+
+/**
+ * Stop the supervised bridge and leave the unit where it is.
+ *
+ * `stopDaemon` cannot do this. It reads the pidfile and signals that process,
+ * which is right for a bridge started by hand and useless for one systemd owns:
+ * the unit is `Restart=always`, so the pid dies and the same ExecStart is back
+ * within the second. `disable` printed "bridge stopped" and left a bridge
+ * running — on a machine whose routing had just been put back, so the bridge
+ * was still up, still answering, and no longer on anybody's path.
+ *
+ * The unit file stays. Removing it is a different decision than turning
+ * resolution off for an afternoon, and `enable` re-enables what it finds — so
+ * leaving it costs nothing and deleting it would quietly take away a unit the
+ * operator may have written themselves.
+ */
+export async function stopService({ system = false, home = operatorHome(), env = process.env, exec = run, exists = existsSync } = {}) {
+  const { path, systemctl, scope } = servicePaths({ system, home, env });
+  if (!exists(path)) return { stopped: false, reason: "no unit installed", path, scope, steps: [] };
+  const [cmd, ...flags] = systemctl;
+  const result = await exec(cmd, [...flags, "disable", "--now", UNIT_NAME]);
+  return {
+    stopped: result.ok,
+    reason: result.ok ? null : (result.error || "systemctl refused"),
+    path,
+    scope,
+    steps: [{ step: `${cmd} ${flags.join(" ")} disable --now ${UNIT_NAME}`, ok: result.ok, error: result.error }],
+  };
+}
+
 /** Stop it and take the unit away. Missing is not a failure — removal is idempotent. */
-export async function removeService({ system = false, home = homedir(), exec = run } = {}) {
-  const { path, systemctl, scope } = servicePaths({ system, home });
+export async function removeService({ system = false, home = operatorHome(), exec = run, env = process.env } = {}) {
+  const { path, systemctl, scope } = servicePaths({ system, home, env });
   const [cmd, ...flags] = systemctl;
   const steps = [];
   for (const args of [[...flags, "disable", "--now", UNIT_NAME]]) {