@monster-orange/den 0.4.21 → 0.4.23

package/src/ui/cli/service-command.ts

@@ -14,6 +14,19 @@
  * (install.sh print), the label, the paths and whose server answers on the
  * port, and writes and loads nothing; exit 1 when that server is foreign.
  * `status` also names a foreign server on the port.
+ *
+ * D18: `install --mode login|always`. login: LaunchAgents in the desktop
+ * session, stopped at logout. always: LaunchDaemons that run as you, kept
+ * across logout (one sudo). Without --mode, the mode already installed
+ * (else login): re-running install never changes it. Both modes also
+ * install the session host as its own job, on Den's node copy
+ * (`<stateDir>/bin/<cli>-sessions-host`, the path Full Disk Access is
+ * granted to), and `<cli> sessions` then waits for that job instead of
+ * starting a host of its own.
+ *
+ * D26: "running" means the server answering on the port is the job's own
+ * process (its pid is launchd's). A plain `web up` server of this install
+ * holding the port is stopped first; `status` says when one holds it.
  */
 import {
   ownerGithubLine,
@@ -21,8 +34,15 @@ import {
   type OwnerGithubResult,
 } from "../../shared/owner-github.js";
 import { spawnSync } from "child_process";
+import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { getStateDir } from "../../shared/paths.js";
+import {
+  serviceJobState,
+  type ServiceJob,
+  type ServiceMode,
+} from "./doctor-where.js";
 import {
   readDenConfig,
   readWebServiceConfig,
@@ -31,6 +51,7 @@ import {
 import { readWebPort } from "../../shared/edge/config.js";
 import { getDistRoot, getEngineRoot } from "../../shared/paths.js";
 import { product } from "../../shared/product.js";
+import { ALWAYS_UNPROVEN } from "../../shared/launchd-session.js";
 import {
   classifyServerInfo,
   ForeignServerError,
@@ -53,7 +74,7 @@ const SUBCOMMANDS = ["install", "status", "print", "uninstall"] as const;
 
 /** The flags each subcommand takes; any other is refused before acting. */
 const SUBCOMMAND_FLAGS: Record<(typeof SUBCOMMANDS)[number], string[]> = {
-  install: ["--plan"],
+  install: ["--plan", "--mode"],
   status: [],
   print: [],
   uninstall: [],
@@ -105,6 +126,14 @@ export async function waitForServerInfo(
 
 export interface ServiceDeps {
   run?: ServiceRunner;
+  /** The state dir (default getStateDir()): Den's node copy, the host job file. */
+  stateDir?: string;
+  /** D18: the job installed for a label, if any (default: plists + launchctl). */
+  job?: (label: string) => ServiceJob | null;
+  /** D26: the pid launchd runs a job as, or null (default: launchctl print). */
+  jobPid?: (job: ServiceJob, label: string) => number | null;
+  /** D26: stop a plain server of this install (default: SIGTERM, wait). */
+  stopPlain?: (pid: number, port: number) => Promise<boolean>;
   /** D17: record web.owner_github (default: from gh, unless `run` is a test's). */
   recordOwner?: () => OwnerGithubResult;
   config?: DenConfig;
@@ -142,20 +171,108 @@ export function identityLine(port: number, id: ServerIdentity): string {
   }
 }
 
+/** D18: the session host's job label: the web label's `.web` → `.sessions`. */
+export function hostLabel(label: string): string {
+  return `${label.replace(/\.web$/, "")}.sessions`;
+}
+
+/** D18: Den's node copy for the session host, the path Full Disk Access names. */
+export function hostExePath(stateDir: string, cli: string): string {
+  return path.join(stateDir, "bin", `${cli}-sessions-host`);
+}
+
+/**
+ * D18: the file that says the session host runs as a launchd job
+ * (`<cli> sessions` waits for it instead of starting one).
+ */
+export function hostJobFile(stateDir: string): string {
+  return path.join(stateDir, "sessions-host-job.json");
+}
+
+/** `--mode <m>` / `--mode=<m>` from install's args; undefined when absent. */
+function modeArg(args: string[]): ServiceMode | undefined {
+  let v: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--mode") v = args[i + 1];
+    else if (args[i].startsWith("--mode=")) v = args[i].slice(7);
+  }
+  if (v === undefined) return undefined;
+  if (v === "login" || v === "always") return v;
+  throw new Error(`service install --mode takes login or always, not "${v}"`);
+}
+
+/** Install's args without `--mode <m>`, for the unknown-argument check. */
+function withoutMode(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--mode") i++;
+    else if (!args[i].startsWith("--mode=")) out.push(args[i]);
+  }
+  return out;
+}
+
+function defaultJobPid(job: ServiceJob, label: string): number | null {
+  const r = spawnSync("launchctl", ["print", `${job.domain}/${label}`], {
+    encoding: "utf-8",
+    timeout: 3000,
+  });
+  if (r.status !== 0) return null;
+  const m = /^\s*pid = (\d+)/m.exec(r.stdout ?? "");
+  return m ? Number(m[1]) : null;
+}
+
+async function defaultStopPlain(pid: number, port: number): Promise<boolean> {
+  const { killWebProcess } = await import("./web-command.js");
+  killWebProcess(pid, "SIGTERM");
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  void port;
+  return false;
+}
+
+/** `service help`: the subcommands and the two install modes. */
+export function serviceHelp(cli: string): string[] {
+  return [
+    `${cli} service: run the web UI and the session host as launchd jobs (macOS)`,
+    ``,
+    `  install [--mode login|always]  install (or refresh) and start them`,
+    `  install --plan                 what install would do; writes and loads nothing`,
+    `  status                         launchd's view: state, pid, last exit code`,
+    `  print                          the web plist it would install; installs nothing`,
+    `  uninstall                      stop them and remove their plists`,
+    ``,
+    `  --mode login   (default) LaunchAgents in the desktop session: stop at logout, with every agent`,
+    `  --mode always  LaunchDaemons running as you, one sudo: meant to keep agents running across logout. Opt-in, ${ALWAYS_UNPROVEN}`,
+    `  Without --mode, install keeps the mode already installed.`,
+  ];
+}
+
 /** Run `service <sub>`; returns the exit code. */
 export async function cmdService(
   args: string[],
   deps: ServiceDeps = {},
 ): Promise<number> {
-  const sub = args[0] as (typeof SUBCOMMANDS)[number] | undefined;
-  if (!(SUBCOMMANDS as readonly string[]).includes(sub ?? ""))
+  if (args[0] === undefined || ["help", "--help", "-h"].includes(args[0])) {
+    for (const l of serviceHelp(product().cli))
+      (deps.log ?? ((x: string) => console.log(x)))(l);
+    return 0;
+  }
+  const sub = args[0] as (typeof SUBCOMMANDS)[number];
+  if (!(SUBCOMMANDS as readonly string[]).includes(sub))
     throw new Error(
-      `${sub ? `Unknown service command "${sub}". ` : ""}Use: ${SUBCOMMANDS.join(" | ")}`,
+      `Unknown service command "${sub}". Use: ${SUBCOMMANDS.join(" | ")} (${product().cli} service help)`,
     );
   // A typo'd --plan must not install for real.
-  const extra = args
-    .slice(1)
-    .filter((a) => !SUBCOMMAND_FLAGS[sub!].includes(a));
+  const extra = (
+    sub === "install" ? withoutMode(args.slice(1)) : args.slice(1)
+  ).filter((a) => !SUBCOMMAND_FLAGS[sub!].includes(a));
   if (extra.length)
     throw new Error(
       `service ${sub}: unknown argument${extra.length > 1 ? "s" : ""} ${extra.join(" ")}` +
@@ -164,6 +281,7 @@ export async function cmdService(
           : ""),
     );
   const plan = sub === "install" && args.includes("--plan");
+  const askedMode = sub === "install" ? modeArg(args) : undefined;
   // print (and install --plan) only write the plist to stdout; the rest
   // talk to launchd.
   if (
@@ -185,10 +303,24 @@ export async function cmdService(
     "service",
     "install.sh",
   );
-  const env = {
+  const home = deps.home ?? os.homedir();
+  const jobOf =
+    deps.job ??
+    ((l: string) => serviceJobState(l, home, process.getuid?.() ?? 0));
+  const installed = jobOf(label);
+  // D18: without --mode, the mode it has (re-running install keeps it).
+  const mode: ServiceMode = askedMode ?? installed?.mode ?? "login";
+  const stateDir = deps.stateDir ?? getStateDir();
+  const env: Record<string, string> = {
     DEN_ROOT: distRoot,
     DEN_SERVICE_LABEL: label,
     DEN_SERVICE_LOGS: logs,
+    ...(sub === "install" || sub === "print"
+      ? {
+          DEN_SERVICE_MODE: mode,
+          DEN_SERVICE_HOST_EXE: hostExePath(stateDir, product().cli),
+        }
+      : {}),
   };
   const run = deps.run ?? defaultRunner;
   const log = deps.log ?? ((l: string) => console.log(l));
@@ -197,12 +329,20 @@ export async function cmdService(
   const identify =
     deps.identify ?? ((p: number, o: OwnServer) => identifyServer(p, o));
 
+  const jobPid = deps.jobPid ?? defaultJobPid;
   if (plan) {
-    const home = deps.home ?? os.homedir();
+    const dir =
+      mode === "always"
+        ? "/Library/LaunchDaemons"
+        : path.join(home, "Library", "LaunchAgents");
     log(`service install --plan (read-only: nothing is written or loaded)`);
+    log(
+      `  mode:    ${mode}${mode === "always" ? ` (LaunchDaemons running as you: meant to keep running across logout, ${ALWAYS_UNPROVEN}; opt-in; one sudo)` : " (LaunchAgents: stop at logout)"}`,
+    );
     log(`  label:   ${label}`);
+    log(`  plist:   ${path.join(dir, `${label}.plist`)}`);
     log(
-      `  plist:   ${path.join(home, "Library", "LaunchAgents", `${label}.plist`)}`,
+      `  host:    ${hostLabel(label)} on ${hostExePath(stateDir, product().cli)} (grant this path Full Disk Access for protected folders)`,
     );
     log(`  logs:    ${path.join(logs, "web.log")}`);
     log(`  root:    ${distRoot}`);
@@ -210,6 +350,15 @@ export async function cmdService(
     log(`  url:     http://localhost:${port}`);
     const id = await identify(port, own);
     log(`  server:  ${identityLine(port, id)}`);
+    // D26: what install does with a plain server of this install.
+    if (
+      id.kind === "ours" &&
+      id.pid &&
+      id.pid !== (installed ? jobPid(installed, label) : null)
+    )
+      log(
+        `           install stops this plain server (pid ${id.pid}) first; the service runs it then`,
+      );
     log(`  plist it would write:`);
     // install.sh print writes the plist to stdout only.
     const code = run("bash", [script, "print"], env);
@@ -221,6 +370,26 @@ export async function cmdService(
     return 0;
   }
 
+  // D26: a plain `web up` server of this install on the port would answer
+  // for the job (which then crash-loops on the taken port): stop it first.
+  if (sub === "install") {
+    const id = await identify(port, own);
+    const pid = id.kind === "ours" ? id.pid : undefined;
+    const theJob = installed ? jobPid(installed, label) : null;
+    if (pid && pid !== theJob) {
+      const stopped = await (deps.stopPlain ?? defaultStopPlain)(pid, port);
+      if (!stopped) {
+        log(
+          `✗ a plain server of this install (pid ${pid}) holds port ${port} and did not stop: ${product().cli} web down, then service install again`,
+        );
+        return 1;
+      }
+      log(
+        `… stopped the plain server of this install (pid ${pid}) on port ${port}: the service runs it now`,
+      );
+    }
+  }
+
   // D17: whoever installs it can connect their GitHub account from any
   // browser (web.owner_github, from gh), before the server reads it.
   if (sub === "install") {
@@ -229,18 +398,43 @@ export async function cmdService(
       (deps.run ? () => ({ state: "linked" as const }) : recordOwnerGithub);
     const line = ownerGithubLine(rec(), product().cli);
     if (line) log(line);
+    if (mode === "always")
+      log(`note: --mode always is opt-in and ${ALWAYS_UNPROVEN}`);
   }
   const code = run("bash", [script, sub!], {
     ...env,
     // The script then leaves saying "running" to us (after the poll below).
     ...(sub === "install" ? { DEN_SERVICE_READY_CHECK: "external" } : {}),
   });
+  if (sub === "uninstall" && code === 0)
+    fs.rmSync(hostJobFile(stateDir), { force: true });
   if (sub === "status") {
     const id = await identify(port, own);
     if (id.kind === "foreign") log(`✗ ${identityLine(port, id)}`);
+    // D26: the server on the port is the job's, or say whose it is.
+    if (id.kind === "ours" && id.pid && installed) {
+      const theJob = jobPid(installed, label);
+      if (theJob !== id.pid) {
+        log(
+          `✗ port ${port} is served by pid ${id.pid}, not the service (${theJob ? `pid ${theJob}` : "not running"}): a plain server of this install holds it. ${product().cli} web down, then ${product().cli} service install`,
+        );
+        return 1;
+      }
+    }
     return code;
   }
   if (sub !== "install" || code !== 0) return code;
+  // D18: `<cli> sessions` waits for the host job instead of starting one.
+  try {
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(
+      hostJobFile(stateDir),
+      JSON.stringify({ label: hostLabel(label), mode }) + "\n",
+      { mode: 0o600 },
+    );
+  } catch {
+    /* sessions then start a host of their own, as before */
+  }
 
   const url = `http://localhost:${port}/api/server-info`;
   const waitReady =
@@ -258,8 +452,20 @@ export async function cmdService(
     return 1;
   }
   if (ready) {
+    // D26: the answer must come from the job itself, not from another
+    // process of this install on the port (the job then crash-loops).
+    const job = jobOf(label);
+    const id = await identify(port, own);
+    const served = id.kind === "ours" ? id.pid : undefined;
+    const theJob = job ? jobPid(job, label) : null;
+    if (job && served && theJob !== served) {
+      log(
+        `✗ ${label} installed, but port ${port} is served by pid ${served}, not the job (${theJob ? `pid ${theJob}` : "not running"}): ${product().cli} web down, then ${product().cli} service install`,
+      );
+      return 1;
+    }
     log(
-      `✓ ${label} running at http://localhost:${port} (logs: ${path.join(logs, "web.log")})`,
+      `✓ ${label} running (${mode}) at http://localhost:${port} (logs: ${path.join(logs, "web.log")})`,
     );
     return 0;
   }

package/src/ui/cli/sessions-command.ts

@@ -133,6 +133,33 @@ export interface Resolved {
   stdout: NodeJS.WriteStream;
 }
 
+/**
+ * D18: the session host's launchd job, when `service install` set one up
+ * and its plist is still there: then the job starts the host (in the
+ * session its mode chose), never a process of ours, which would run in
+ * this caller's launchd session (D20: a desktop one ends at logout).
+ */
+export function hostJob(
+  stateDir: string,
+  home: string = process.env.HOME ?? "",
+  exists: (p: string) => boolean = fs.existsSync,
+): { label: string; mode: string } | null {
+  try {
+    const v = JSON.parse(
+      fs.readFileSync(path.join(stateDir, "sessions-host-job.json"), "utf-8"),
+    ) as { label?: unknown; mode?: unknown };
+    if (typeof v.label !== "string" || !/^[\w.-]+$/.test(v.label)) return null;
+    const plists = [
+      path.join("/Library/LaunchDaemons", `${v.label}.plist`),
+      path.join(home, "Library", "LaunchAgents", `${v.label}.plist`),
+    ];
+    if (!plists.some((p) => exists(p))) return null;
+    return { label: v.label, mode: String(v.mode ?? "") };
+  } catch {
+    return null;
+  }
+}
+
 /** Start `<cli> sessions host` in the background, detached, logging to the state dir. */
 function spawnHost(stateDir: string): void {
   const cmd = cliEntrypoint();
@@ -164,17 +191,17 @@ export function resolveDeps(d: SessionsDeps): Resolved {
     cli: d.cli ?? product().cli,
     connect:
       d.connect ??
-      (() =>
-        ensureHost({
+      (() => {
+        const job = hostJob(stateDir());
+        return ensureHost({
           socket: sessionPaths(stateDir()).socket,
-          spawnHost: () => spawnHost(stateDir()),
-          logHint: path.join(
-            stateDir(),
-            "logs",
-            product().cli,
-            "sessions-host.log",
-          ),
-        })),
+          // D18: launchd starts (and restarts) the host job; wait for it.
+          spawnHost: job ? () => undefined : () => spawnHost(stateDir()),
+          logHint: job
+            ? `its launchd job ${job.label} (${job.mode}): ${product().cli} service status`
+            : path.join(stateDir(), "logs", product().cli, "sessions-host.log"),
+        });
+      }),
     connectExisting:
       d.connectExisting ??
       (d.connect
@@ -314,6 +341,8 @@ export function contractInfo(s: SessionInfo): SessionInfo {
     startedAt: s.startedAt,
     ...(s.exited ? { exited: true } : {}),
     ...(s.exitCode !== undefined ? { exitCode: s.exitCode } : {}),
+    // D20: where its host ran (Aqua: it ends at logout).
+    ...(s.launchd ? { launchd: s.launchd } : {}),
   };
 }
 
@@ -677,10 +706,15 @@ function attachTerminal(
 
 async function host(args: string[], d: Resolved): Promise<number> {
   const where = "sessions host";
-  const p = parseArgs(where, args, { "--stop": false });
+  const p = parseArgs(where, args, { "--stop": false, "--stand-by": false });
   noExtra(where, p);
   if (!p.flags["--stop"])
-    return runSessionHost({ stateDir: d.stateDir(), pty: () => loadPty() });
+    return runSessionHost({
+      stateDir: d.stateDir(),
+      pty: () => loadPty(),
+      // D18: the launchd job's: wait out a host started before it.
+      standBy: Boolean(p.flags["--stand-by"]),
+    });
   const c = await d.connectExisting();
   if (!c) {
     d.out("no session host is running");

package/src/ui/cli/web-command.ts

@@ -2,6 +2,7 @@ import {
   ownerGithubLine,
   recordOwnerGithub,
 } from "../../shared/owner-github.js";
+import { launchdSession, webUpWarning } from "../../shared/launchd-session.js";
 import chalk from "chalk";
 import { execFileSync, spawn, spawnSync } from "child_process";
 import * as fs from "fs";
@@ -69,6 +70,7 @@ import {
 } from "./server-identity.js";
 
 import { product } from "../../shared/product.js";
+import { webServiceAction, type WebServiceDeps } from "./web-service.js";
 import {
   CLAIM_CODE_TTL_MS,
   claimLink,
@@ -1264,6 +1266,12 @@ export function cmdWebToken(
   return 0;
 }
 
+/** Tests: the launchd service seams (web-service.ts); never the real launchctl. */
+let webServiceDeps: WebServiceDeps | undefined;
+export function setWebServiceDepsForTest(d: WebServiceDeps | undefined): void {
+  webServiceDeps = d;
+}
+
 export async function cmdWeb(args: string[]): Promise<void> {
   // A subcommand with its own help answers its own --help (it is
   // dispatched first); the rest (up, down, restart, open) share this one.
@@ -1313,7 +1321,26 @@ export async function cmdWeb(args: string[]): Promise<void> {
   const identity = await refuseForeignServer(options.port, ownServer());
   const vouched = identity.kind === "ours" ? identity.pid : undefined;
 
-  if (options.action === "down") {
+  // With the launchd service installed, it owns the server: restart and up
+  // go through launchd, down is refused (launchd would start it again).
+  const svc = await webServiceAction(
+    options.action,
+    options.port,
+    identity.kind === "ours",
+    (p) => waitForDenWeb(p),
+    webServiceDeps,
+  );
+  if (svc.handled) {
+    if (svc.code !== 0) {
+      process.exitCode = svc.code;
+      return;
+    }
+    recordRunningDenWebServer(options.port);
+  }
+
+  if (svc.handled) {
+    /* the service runs it: on to opening the browser */
+  } else if (options.action === "down") {
     const stopped = await stopDenWebServer(options.port, vouched);
     if (stopped.stopped) {
       const mode = stopped.forced ? "force stopped" : "stopped";
@@ -1342,7 +1369,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
     if (line) console.log(chalk.dim(`\n  ${line}`));
   }
 
-  if (options.action === "restart") {
+  if (options.action === "restart" && !svc.handled) {
     const stopped = await stopDenWebServer(options.port, vouched);
     if (stopped.pids.length > 0 && !stopped.stopped) {
       throw new Error(
@@ -1368,8 +1395,9 @@ export async function cmdWeb(args: string[]): Promise<void> {
   );
   if (ignored) console.log(chalk.yellow(`\n  ⚠ ${ignored}`));
 
-  const apiRunning = await isDenWebApiRunning(options.port);
-  let running = apiRunning && (await isDenWebUiReady(options.port));
+  const apiRunning = svc.handled || (await isDenWebApiRunning(options.port));
+  let running =
+    svc.handled || (apiRunning && (await isDenWebUiReady(options.port)));
   let started: StartedServer | null = null;
 
   if (apiRunning && !running) {
@@ -1388,6 +1416,9 @@ export async function cmdWeb(args: string[]): Promise<void> {
   }
 
   if (!running) {
+    // D20: started from an ssh (Background) shell, it lives there.
+    const where = webUpWarning(launchdSession(), product().cli);
+    if (where) console.log(chalk.yellow(`\n  ⚠ ${where}`));
     console.log(chalk.cyan(`\n  Starting ${product().cli} web on ${url}...`));
     try {
       started = startDenWebServer(options);
@@ -1411,7 +1442,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
       console.log(chalk.red(`  ERROR Failed to start ${product().cli} web`));
       throw error;
     }
-  } else {
+  } else if (!svc.handled) {
     recordRunningDenWebServer(options.port);
     console.log(
       chalk.green(`\n  OK ${product().title} web is already running at ${url}`),

package/src/ui/cli/web-service.ts

@@ -0,0 +1,160 @@
+/**
+ * `web up | down | restart` when this install's web server runs as a
+ * launchd service (`<cli> service install`).
+ *
+ * Before, `web restart` stopped the job's server and started a plain one.
+ * launchd brought the job straight back (KeepAlive), it took the port, and
+ * the plain server died seconds after "OK ... started". Now, with the
+ * service installed and the command on its port:
+ *
+ *   - restart: `launchctl kickstart -k`, then the job's new pid and the
+ *     service's log;
+ *   - up: a job that is not answering is started the same way;
+ *   - down: refused, because launchd would only start it again; it names
+ *     `<cli> service uninstall`.
+ *
+ * In always mode the job is in the system domain: kickstart there needs
+ * sudo, so the command is printed for the person to run, never run here.
+ */
+import { spawnSync } from "child_process";
+import * as os from "os";
+import * as path from "path";
+import {
+  readDenConfig,
+  readWebServiceConfig,
+} from "../../shared/den-config.js";
+import { readWebPort } from "../../shared/edge/config.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import { serviceJobState, type ServiceJob } from "./doctor-where.js";
+
+export interface WebService {
+  label: string;
+  /** The service's web.log. */
+  log: string;
+  job: ServiceJob;
+}
+
+export interface WebServiceDeps {
+  /** The installed service for this install's port, or null. */
+  service?: (port: number) => WebService | null;
+  /** launchctl kickstart [-k] <domain>/<label>; its exit code. */
+  kickstart?: (target: string, kill: boolean) => number;
+  /** The pid launchd runs the job as, or null. */
+  jobPid?: (svc: WebService) => number | null;
+  /** Until the job's server answers as this install's (true) or time runs out. */
+  waitReady?: (port: number) => Promise<boolean>;
+  log?: (line: string) => void;
+  /** Between pid checks while the job comes back (default 250 ms). */
+  pollMs?: number;
+  /** How long to wait for the job's new pid (default 30 s). */
+  pidTimeoutMs?: number;
+}
+
+export type WebServiceResult =
+  | { handled: false }
+  | { handled: true; code: number; pid?: number };
+
+function defaultService(port: number): WebService | null {
+  if (process.platform !== "darwin") return null;
+  const distRoot = getDistRoot();
+  // The service serves this install's configured port only.
+  if (port !== readWebPort(distRoot)) return null;
+  const { label, logs } = readWebServiceConfig(
+    readDenConfig(),
+    distRoot,
+    os.homedir(),
+  );
+  const job = serviceJobState(label, os.homedir(), process.getuid?.() ?? 0);
+  if (!job || job.state !== "loaded") return null;
+  return { label, log: path.join(logs, "web.log"), job };
+}
+
+function defaultKickstart(target: string, kill: boolean): number {
+  return (
+    spawnSync("launchctl", ["kickstart", ...(kill ? ["-k"] : []), target], {
+      stdio: "ignore",
+      timeout: 10_000,
+    }).status ?? 1
+  );
+}
+
+function defaultJobPid(svc: WebService): number | null {
+  const r = spawnSync(
+    "launchctl",
+    ["print", `${svc.job.domain}/${svc.label}`],
+    { encoding: "utf-8", timeout: 3000 },
+  );
+  if (r.status !== 0) return null;
+  const m = /^\s*pid = (\d+)/m.exec(r.stdout ?? "");
+  return m ? Number(m[1]) : null;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * What `web <action>` does when the service is installed. `answering`:
+ * this install's server already answers on the port. Not handled: no
+ * service (or another port), and `up` while it answers.
+ */
+export async function webServiceAction(
+  action: "up" | "down" | "restart" | "open",
+  port: number,
+  answering: boolean,
+  waitReadyDefault: (port: number) => Promise<boolean>,
+  deps: WebServiceDeps = {},
+): Promise<WebServiceResult> {
+  if (action === "open") return { handled: false };
+  const svc = (deps.service ?? defaultService)(port);
+  if (!svc) return { handled: false };
+  if (action === "up" && answering) return { handled: false };
+  const log = deps.log ?? ((l: string) => console.log(l));
+  const { cli, title } = product();
+  const target = `${svc.job.domain}/${svc.label}`;
+
+  if (action === "down") {
+    log(
+      `✗ ${title} web runs as the service ${svc.label} (${svc.job.mode}): stopping it only makes launchd start it again.`,
+    );
+    log(`  To stop it for good: ${cli} service uninstall`);
+    log(`  To restart it: ${cli} web restart`);
+    return { handled: true, code: 1 };
+  }
+
+  if (svc.job.mode === "always") {
+    log(
+      `${title} web runs as the service ${svc.label} (always). Restarting it needs sudo:`,
+    );
+    log(`  sudo launchctl kickstart -k ${target}`);
+    return { handled: true, code: 1 };
+  }
+
+  const jobPid = deps.jobPid ?? defaultJobPid;
+  const before = jobPid(svc);
+  const code = (deps.kickstart ?? defaultKickstart)(target, true);
+  if (code !== 0) {
+    log(`✗ launchctl kickstart -k ${target} failed (exit ${code})`);
+    log(`  See ${svc.log}`);
+    return { handled: true, code: 1 };
+  }
+  // A new pid, then the server answering.
+  const deadline = Date.now() + (deps.pidTimeoutMs ?? 30_000);
+  let pid = jobPid(svc);
+  while ((pid === null || pid === before) && Date.now() < deadline) {
+    await sleep(deps.pollMs ?? 250);
+    pid = jobPid(svc);
+  }
+  const ready =
+    pid !== null &&
+    pid !== before &&
+    (await (deps.waitReady ?? waitReadyDefault)(port));
+  if (!ready) {
+    log(`✗ the service ${svc.label} did not come back. See ${svc.log}`);
+    return { handled: true, code: 1 };
+  }
+  log(
+    `OK ${title} web ${action === "up" ? "started" : "restarted"} by its service ${svc.label} (pid ${pid})`,
+  );
+  log(`  Log: ${svc.log}`);
+  return { handled: true, code: 0, pid: pid! };
+}