@monster-orange/den 0.4.22 → 0.4.24

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

@@ -70,6 +70,10 @@ import { HostError } from "../../shared/sessions/client.js";
 import { checkHandback } from "../../shared/agents/handback.js";
 import { checkHandoff } from "../../shared/agents/handoff.js";
 import { handoffFile, reasonText } from "../../shared/agents/rotation.js";
+import {
+  parseRotateValue,
+  type OverrideScope,
+} from "../../shared/agents/rotate-settings.js";
 import {
   agentFilesDir,
   listRecords,
@@ -85,11 +89,15 @@ import {
   listRuntimes,
   loadAgentWorkspaces,
   relaunchAgent,
+  resumeOrRelaunch,
+  keepAgentConversation,
+  askForHandoff,
+  rotationSettings,
+  setRotationSetting,
   removeAgent,
   removeStopped,
   renameAgent,
   resolveAgentsDeps,
-  resumeAgent,
   resumeInterrupted,
   startAgent,
   stopAgent,
@@ -121,7 +129,7 @@ export {
 
 export const AGENTS_HELP = {
   usage:
-    "agents <list|start|stop|resume|relaunch|import|persona|rename|rm|personas|doctor|handback-check|handoff-check> ...",
+    "agents <list|start|stop|resume|relaunch|rotate|keep|handoff|import|persona|rename|rm|personas|doctor|handback-check|handoff-check> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -146,6 +154,19 @@ export const AGENTS_HELP = {
     "    compactions (default 3) or its pull request merged, and its handoff.md",
     "    passes the check, a fresh conversation (same persona, workspace, folder,",
     "    grants) whose first prompt is the handoff",
+    "{cli} agents rotate [--agent|--persona|--workspace|--service <x>] [-w <ws>] <key> <value>",
+    "{cli} agents rotate [scope] --unset <key>   ·   {cli} agents rotate   ·   {cli} agents rotate <id> --show",
+    "    rotation settings: after_compactions <n>|never (default 3), on_due",
+    "    auto|ask|off (default auto: Den asks for the handoff at idle and",
+    "    relaunches by itself), on_pr_merged true|false. No scope: this install.",
+    "    --persona <p> -w <ws>: the persona in that workspace. The most specific",
+    "    wins: agent, persona in a workspace, persona, workspace, service,",
+    "    install, org config. --show: an agent's values and where each comes from",
+    "{cli} agents keep <id> [-w <ws>] [--never]",
+    "    keep its conversation: the compaction count starts again; --never: this",
+    "    agent never rotates. A person's only",
+    "{cli} agents handoff <id> [-w <ws>]",
+    "    ask a running agent, at idle, to write its handoff",
     "{cli} agents import -w <ws> [--runtime <r>] [--json]",
     "{cli} agents import -w <ws> --session <id> --persona <p> [--runtime <r>] [--id <id>] [--model <m>]",
     "    bring in a conversation started outside Den: the first lists the runtime's",
@@ -477,7 +498,15 @@ async function stop(args: string[], d: AgentsResolved): Promise<number> {
 async function resume(args: string[], d: AgentsResolved): Promise<number> {
   if (args.includes("--all-interrupted")) return resumeAll(args, d);
   const { id, ws } = idAndWorkspace("agents resume", args);
-  const s = await resumeAgent(d, id, ws);
+  // D28: a due agent under auto relaunches from its handoff instead.
+  const r = await resumeOrRelaunch(d, id, ws);
+  if (r.kind === "relaunched")
+    return report(
+      d,
+      r.s,
+      `relaunched agent ${r.s.rec.id} from its handoff (the last session ended after ${r.s.why}) as ${r.s.rec.sessionName} in ${r.s.rec.cwd}`,
+    );
+  const s = r.s;
   if (s.fresh) d.out(`agent ${s.rec.id}: ${FRESH_NOTE}`);
   return report(
     d,
@@ -487,6 +516,135 @@ async function resume(args: string[], d: AgentsResolved): Promise<number> {
 }
 
 /** `agents relaunch <id> [-w <ws>]` (den#4). */
+/** D28: refused in an agent's session (an agent could stop its own rotation). */
+function personOnly(where: string, d: AgentsResolved): void {
+  if (d.env[ACTOR_TOKEN_ENV] !== undefined)
+    throw new AgentError(
+      `${where}: only a person can change rotation (this is an agent's session)`,
+    );
+}
+
+const ROTATE_SCOPE_FLAGS: Record<string, OverrideScope> = {
+  "--agent": "agent",
+  "--persona": "persona",
+  "--workspace": "workspace",
+  "--service": "service",
+};
+
+/**
+ * `agents rotate` (D28): with no arguments, the settings and overrides;
+ * `[--agent|--persona|--workspace|--service <x>] [-w <ws>] <key> <value>`
+ * sets one (no scope flag: this install's), `--unset` clears it. `--persona
+ * <p> -w <ws>`: the persona in that workspace. `agents rotate <id> --show`:
+ * that agent's effective values and where each comes from.
+ */
+async function rotate(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents rotate";
+  if (args.includes("--show")) {
+    const { id, ws } = idAndWorkspace(
+      where,
+      args.filter((a) => a !== "--show"),
+    );
+    const r = rotationSettings(d, id, ws);
+    if (!r.effective) {
+      d.err(`✗ ${where}: ${id}'s persona or the config can't be read`);
+      return 1;
+    }
+    const e = r.effective;
+    d.out(`agent ${e.agent}:`);
+    d.out(
+      `  after_compactions  ${e.afterCompactions === 0 ? "never" : e.afterCompactions}  (from ${e.from?.after_compactions})`,
+    );
+    d.out(`  on_due             ${e.onDue}  (from ${e.from?.on_due})`);
+    d.out(
+      `  on_pr_merged       ${e.onPrMerged}  (from ${e.from?.on_pr_merged})`,
+    );
+    return 0;
+  }
+  if (!args.length) {
+    const r = rotationSettings(d);
+    const vals = (v: object) =>
+      Object.entries(v)
+        .map(([k, x]) => `${k}=${String(x)}`)
+        .join(" ") || "(none)";
+    d.out(`default: ${vals(r.defaults)}`);
+    d.out(`org config: ${vals(r.org)}`);
+    d.out(`this install: ${vals(r.install)}`);
+    for (const [scope, byTarget] of Object.entries(r.overrides))
+      for (const [target, v] of Object.entries(byTarget ?? {}))
+        d.out(`${scope} ${target}: ${vals(v)}`);
+    return 0;
+  }
+  personOnly(where, d);
+  const unset = args.includes("--unset");
+  const rest = args.filter((a) => a !== "--unset");
+  let scope: OverrideScope | "install" = "install";
+  let target: string | undefined;
+  let ws: string | undefined;
+  const pos: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "-w" || a === "--ws") {
+      ws = rest[++i];
+      if (!ws) throw new UsageError(`${where}: ${a} needs a workspace`);
+    } else if (a in ROTATE_SCOPE_FLAGS) {
+      if (scope !== "install")
+        throw new UsageError(`${where}: one scope at a time`);
+      scope = ROTATE_SCOPE_FLAGS[a];
+      target = rest[++i];
+      if (!target) throw new UsageError(`${where}: ${a} needs a name`);
+    } else if (a.startsWith("--"))
+      throw new UsageError(`${where}: unknown flag ${a}`);
+    else pos.push(a);
+  }
+  if (ws) {
+    if (scope !== "persona")
+      throw new UsageError(
+        `${where}: -w goes with --persona (the persona in that workspace); use --workspace <ws> for a workspace`,
+      );
+    scope = "persona-workspace";
+    target = `${target}@${ws}`;
+  }
+  const [key, raw] = pos;
+  if (!key || (unset ? pos.length !== 1 : pos.length !== 2))
+    throw new UsageError(
+      `${where} [--agent|--persona|--workspace|--service <x>] <key> <value> (or --unset <key>)`,
+    );
+  setRotationSetting(d, {
+    scope,
+    ...(target !== undefined ? { target } : {}),
+    key,
+    value: unset ? null : parseRotateValue(key, raw!),
+  });
+  const at = scope === "install" ? "this install" : `${scope} ${target}`;
+  d.out(unset ? `${key} cleared at ${at}` : `${key} = ${raw} at ${at}`);
+  return 0;
+}
+
+/** `agents keep <id> [-w <ws>] [--never]` (D28 Keep this conversation). */
+function keep(args: string[], d: AgentsResolved): number {
+  const where = "agents keep";
+  personOnly(where, d);
+  const never = args.includes("--never");
+  const { id, ws } = idAndWorkspace(
+    where,
+    args.filter((a) => a !== "--never"),
+  );
+  const rec = keepAgentConversation(d, id, ws, { never });
+  d.out(
+    `kept ${rec.id}'s conversation: its compaction count starts again${never ? "; it never rotates (agents rotate --agent " + rec.id + " --unset after_compactions to undo)" : ""}`,
+  );
+  return 0;
+}
+
+/** `agents handoff <id> [-w <ws>]` (D28 Write handoff). */
+async function handoff(args: string[], d: AgentsResolved): Promise<number> {
+  const { id, ws } = idAndWorkspace("agents handoff", args);
+  const rec = await askForHandoff(d, id, ws);
+  d.out(`asked ${rec.id} to write its handoff; Den relaunches it from it`);
+  return 0;
+}
+
 async function relaunch(args: string[], d: AgentsResolved): Promise<number> {
   const { id, ws } = idAndWorkspace("agents relaunch", args);
   const s = await relaunchAgent(d, id, ws);
@@ -790,6 +948,14 @@ export async function cmdAgents(
         case "relaunch":
           await loadAgentWorkspaces(deps);
           return await relaunch(rest, d);
+        case "rotate":
+          await loadAgentWorkspaces(deps);
+          return await rotate(rest, d);
+        case "keep":
+          return keep(rest, d);
+        case "handoff":
+          await loadAgentWorkspaces(deps);
+          return await handoff(rest, d);
         case "import":
           await loadAgentWorkspaces(deps);
           return await bringIn(rest, d);

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

@@ -69,11 +69,13 @@ import { printJson } from "./json-out.js";
 import { ownerCheck, ownerLine } from "./doctor-owner.js";
 import {
   formatWhere,
+  launchdJobPid,
   serviceJobState,
   whereRows,
   type WhereDeps,
   type WhereRow,
 } from "./doctor-where.js";
+import { hostLabel } from "./service-command.js";
 
 export interface DoctorRow {
   kind: string;
@@ -420,6 +422,8 @@ export async function defaultWhereDeps(): Promise<WhereDeps> {
       try {
         return {
           launchd: c.hostLaunchd,
+          pid: c.hostPid,
+          startedAt: c.hostStartedAt || undefined,
           access: await c.access().catch(() => null),
         };
       } finally {
@@ -438,6 +442,24 @@ export async function defaultWhereDeps(): Promise<WhereDeps> {
         return null;
       }
     },
+    hostJob: () => {
+      try {
+        const { label } = readWebServiceConfig(
+          cfg(),
+          getDistRoot(),
+          os.homedir(),
+        );
+        const host = hostLabel(label);
+        const job = serviceJobState(
+          host,
+          os.homedir(),
+          process.getuid?.() ?? 0,
+        );
+        return job?.state === "loaded" ? launchdJobPid(job.domain, host) : null;
+      } catch {
+        return null;
+      }
+    },
   };
 }
 
@@ -445,7 +467,8 @@ export async function defaultWhereDeps(): Promise<WhereDeps> {
 export function whereCheck(r: WhereRow): OnboardCheck {
   return {
     id: `where:${r.what.replace(" ", "-")}`,
-    status: r.status,
+    // info is as chosen: not a problem.
+    status: r.status === "info" ? "ok" : r.status,
     detail: `${r.session}${r.detail ? `: ${r.detail}` : ""}`,
   };
 }

package/src/ui/cli/doctor-where.ts

@@ -41,15 +41,22 @@ export interface WhereDeps {
   /** The running session host's; null when none runs. */
   host: () => Promise<{
     launchd: string | null;
+    /** The pid that answers on the socket. */
+    pid?: number;
+    /** When it started (ISO). */
+    startedAt?: string;
     access?: { exe: string; fullDiskAccess: boolean | null } | null;
   } | null>;
   service: () => ServiceJob | null;
+  /** The service's own host job's pid (it may stand by), or null. */
+  hostJob?: () => number | null;
 }
 
 export interface WhereRow {
   what: "server" | "session host" | "full disk access" | "service";
   session: string;
-  status: "ok" | "warn";
+  /** info: as chosen, worth knowing (login mode ends at logout). */
+  status: "ok" | "info" | "warn";
   detail?: string;
 }
 
@@ -57,12 +64,15 @@ function sessionRow(
   what: "server" | "session host",
   launchd: string | null | undefined,
   cli: string,
+  loginChosen = false,
 ): WhereRow {
   const session = launchd || "unknown";
   return {
     what,
     session,
-    status: endsAtLogout(launchd) ? "warn" : "ok",
+    // The service installed in login mode: ending at logout is what was
+    // chosen (the default), so it is said, not warned about.
+    status: endsAtLogout(launchd) ? (loginChosen ? "info" : "warn") : "ok",
     ...(sessionWarning(launchd, cli, what)
       ? { detail: sessionWarning(launchd, cli, what)! }
       : {}),
@@ -72,10 +82,12 @@ function sessionRow(
 export async function whereRows(d: WhereDeps): Promise<WhereRow[]> {
   if (d.platform !== "darwin") return [];
   const rows: WhereRow[] = [];
+  const svc = d.service();
+  const loginChosen = svc?.mode === "login" && svc.state !== "not-loaded";
   const server = await d.server().catch(() => null);
   rows.push(
     server
-      ? sessionRow("server", server.launchd, d.cli)
+      ? sessionRow("server", server.launchd, d.cli, loginChosen)
       : {
           // Not started yet is not a problem (a fresh install).
           what: "server",
@@ -85,15 +97,38 @@ export async function whereRows(d: WhereDeps): Promise<WhereRow[]> {
         },
   );
   const host = await d.host().catch(() => null);
+  const jobPid = host ? (d.hostJob?.() ?? null) : null;
+  // The service's host stands by while another host holds the socket, and
+  // takes over when that one exits: nothing to do.
+  const standsBy =
+    jobPid !== null && host?.pid !== undefined && jobPid !== host.pid;
+  const since = host?.startedAt ? `, since ${host.startedAt.slice(0, 10)}` : "";
+  const older = `an older session host (pid ${host?.pid ?? "?"}${since})`;
+  const switchNow = `To switch now (ends running terminals and agents): ${d.cli} sessions host --stop`;
   rows.push(
-    host
-      ? sessionRow("session host", host.launchd, d.cli)
-      : {
+    host && standsBy
+      ? {
           what: "session host",
-          session: "not running",
-          status: "ok",
-          detail: "it starts when the first terminal or agent does",
-        },
+          session: host.launchd || `older host (pid ${host.pid})`,
+          status: "info",
+          detail: `${older} is serving; the service's host (pid ${jobPid}) takes over when it exits. Nothing to do. ${switchNow}`,
+        }
+      : host && !host.launchd
+        ? {
+            // An older host and no service host behind it: what it lacks.
+            what: "session host",
+            session: `unknown (older host${host.pid ? `, pid ${host.pid}` : ""})`,
+            status: "warn",
+            detail: `${older} can't say where it runs, so whether its terminals and agents stop at logout is unknown. It is replaced the next time it exits. ${switchNow}`,
+          }
+        : host
+          ? sessionRow("session host", host.launchd, d.cli, loginChosen)
+          : {
+              what: "session host",
+              session: "not running",
+              status: "ok",
+              detail: "it starts when the first terminal or agent does",
+            },
   );
   const fda = host?.access;
   if (fda && fda.fullDiskAccess !== null) {
@@ -116,7 +151,6 @@ export async function whereRows(d: WhereDeps): Promise<WhereRow[]> {
           },
     );
   }
-  const svc = d.service();
   if (!svc)
     rows.push({
       what: "service",
@@ -145,6 +179,17 @@ export async function whereRows(d: WhereDeps): Promise<WhereRow[]> {
   return rows;
 }
 
+/** The pid launchd runs `<domain>/<label>` as, or null (launchctl print). */
+export function launchdJobPid(domain: string, label: string): number | null {
+  const r = spawnSync("launchctl", ["print", `${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;
+}
+
 export interface JobProbe {
   exists: (p: string) => boolean;
   /** `launchctl print <domain>/<label>`'s exit status (127: no launchctl). */
@@ -195,9 +240,10 @@ export function formatWhere(rows: WhereRow[], title: string): string[] {
   const lines = ["", `${title} doctor: where it runs`, ""];
   const w = Math.max(...rows.map((r) => r.session.length));
   for (const r of rows) {
-    const mark = r.status === "ok" ? "✓" : "⚠";
+    const mark = r.status === "ok" ? "✓" : r.status === "info" ? "ℹ" : "⚠";
     lines.push(`  ${r.what.padEnd(16)}  ${r.session.padEnd(w)}  ${mark}`);
-    if (r.detail) lines.push(`    ${r.status === "ok" ? "" : "⚠ "}${r.detail}`);
+    if (r.detail)
+      lines.push(`    ${r.status === "warn" ? "⚠ " : ""}${r.detail}`);
   }
   return lines;
 }

package/src/ui/cli/server-agent-ops.ts

@@ -25,9 +25,9 @@ import {
   type AgentsResolved,
   type RuntimeChoice,
   type Started,
+  rotationOf,
 } from "./agent-ops.js";
 import { readRecord } from "../../shared/agents/records.js";
-import { rotationInfo } from "../../shared/agents/rotation.js";
 import {
   SERVER_AGENT_ID,
   SERVER_PERSONA_ID,
@@ -355,7 +355,7 @@ export async function startServerAgent(
     rec.runtime === runtime &&
     rec.model === model
   ) {
-    if (rotationInfo(d.stateDir(), rec)?.ready)
+    if (rotationOf(d, rec)?.ready)
       return done("relaunched", await relaunchAgent(d, rec.id));
     if (resumeRefusal(rec) === null)
       return done("resumed", await resumeAgent(d, rec.id, SERVER_SCOPE));

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

@@ -70,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,
@@ -1265,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.
@@ -1314,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";
@@ -1343,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(
@@ -1369,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) {
@@ -1415,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! };
+}