@monster-orange/den 0.4.21 → 0.4.22

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

@@ -0,0 +1,203 @@
+/**
+ * D18/D20: doctor's "where it runs" rows (macOS only).
+ *
+ *   server        the web server's launchd session (/api/server-info)
+ *   session host  the session host's (its hello), where every agent runs
+ *   full disk access  whether the host (and so every agent) has it, and
+ *                 the executable to grant it to: Den's node copy, never the
+ *                 shared node
+ *   service       the installed launchd job: always (a LaunchDaemon, kept
+ *                 across logout) or login (a LaunchAgent in the desktop
+ *                 session), and "plist present, job not loaded" with the
+ *                 bootstrap that loads it
+ *
+ * A process in the desktop session (Aqua) stops at logout: a warning with
+ * the fix. None of these fails doctor.
+ */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  ALWAYS_UNPROVEN,
+  endsAtLogout,
+  sessionWarning,
+} from "../../shared/launchd-session.js";
+
+export type ServiceMode = "always" | "login";
+
+export interface ServiceJob {
+  /** unknown: launchctl could not be asked. */
+  state: "loaded" | "not-loaded" | "unknown";
+  mode: ServiceMode;
+  plist: string;
+  domain: string;
+}
+
+export interface WhereDeps {
+  cli: string;
+  platform: NodeJS.Platform;
+  /** The web server's launchd session; null when it does not answer. */
+  server: () => Promise<{ launchd?: string | null } | null>;
+  /** The running session host's; null when none runs. */
+  host: () => Promise<{
+    launchd: string | null;
+    access?: { exe: string; fullDiskAccess: boolean | null } | null;
+  } | null>;
+  service: () => ServiceJob | null;
+}
+
+export interface WhereRow {
+  what: "server" | "session host" | "full disk access" | "service";
+  session: string;
+  status: "ok" | "warn";
+  detail?: string;
+}
+
+function sessionRow(
+  what: "server" | "session host",
+  launchd: string | null | undefined,
+  cli: string,
+): WhereRow {
+  const session = launchd || "unknown";
+  return {
+    what,
+    session,
+    status: endsAtLogout(launchd) ? "warn" : "ok",
+    ...(sessionWarning(launchd, cli, what)
+      ? { detail: sessionWarning(launchd, cli, what)! }
+      : {}),
+  };
+}
+
+export async function whereRows(d: WhereDeps): Promise<WhereRow[]> {
+  if (d.platform !== "darwin") return [];
+  const rows: WhereRow[] = [];
+  const server = await d.server().catch(() => null);
+  rows.push(
+    server
+      ? sessionRow("server", server.launchd, d.cli)
+      : {
+          // Not started yet is not a problem (a fresh install).
+          what: "server",
+          session: "not running",
+          status: "ok",
+          detail: `start it: ${d.cli} web up, or ${d.cli} service install`,
+        },
+  );
+  const host = await d.host().catch(() => null);
+  rows.push(
+    host
+      ? sessionRow("session host", host.launchd, d.cli)
+      : {
+          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) {
+    const own = /-sessions-host$/.test(fda.exe);
+    rows.push(
+      fda.fullDiskAccess
+        ? {
+            what: "full disk access",
+            session: "granted",
+            status: "ok",
+            detail: `to ${fda.exe}`,
+          }
+        : {
+            what: "full disk access",
+            session: "not granted",
+            status: "warn",
+            detail: own
+              ? `agents can't open protected folders (other volumes, Desktop, Documents): System Settings → Privacy & Security → Full Disk Access → + → ${fda.exe}, then ${d.cli} sessions host --stop (it restarts with the grant)`
+              : `agents can't open protected folders. The host runs the shared node (${fda.exe}): ${d.cli} service install gives it its own copy to grant, so the grant never goes to every node program`,
+          },
+    );
+  }
+  const svc = d.service();
+  if (!svc)
+    rows.push({
+      what: "service",
+      session: "not installed",
+      status: "ok",
+      detail: `${d.cli} service install (login, the default; --mode always is opt-in and ${ALWAYS_UNPROVEN})`,
+    });
+  else if (svc.state === "not-loaded")
+    rows.push({
+      what: "service",
+      session: `${svc.mode} (${svc.domain})`,
+      status: "warn",
+      detail: `plist present, job not loaded: ${svc.domain === "system" ? "sudo " : ""}launchctl bootstrap ${svc.domain} ${svc.plist}`,
+    });
+  else
+    rows.push({
+      what: "service",
+      session: `${svc.mode} (${svc.domain})`,
+      status: "ok",
+      ...(svc.state === "unknown"
+        ? { detail: "launchctl could not be asked whether it is loaded" }
+        : svc.mode === "always"
+          ? { detail: `opt-in: ${ALWAYS_UNPROVEN}` }
+          : {}),
+    });
+  return rows;
+}
+
+export interface JobProbe {
+  exists: (p: string) => boolean;
+  /** `launchctl print <domain>/<label>`'s exit status (127: no launchctl). */
+  print: (target: string) => number | null;
+}
+
+const realProbe: JobProbe = {
+  exists: (p) => fs.existsSync(p),
+  print: (target) =>
+    spawnSync("launchctl", ["print", target], {
+      stdio: "ignore",
+      timeout: 3000,
+    }).status,
+};
+
+/**
+ * The installed service job for `label`: the LaunchDaemon (always) when
+ * its plist exists, else the LaunchAgent (login); null when neither does.
+ */
+export function serviceJobState(
+  label: string,
+  home: string,
+  uid: number,
+  probe: JobProbe = realProbe,
+): ServiceJob | null {
+  const daemon = path.join("/Library/LaunchDaemons", `${label}.plist`);
+  const agent = path.join(home, "Library", "LaunchAgents", `${label}.plist`);
+  const found: [ServiceMode, string, string] | null = probe.exists(daemon)
+    ? ["always", daemon, "system"]
+    : probe.exists(agent)
+      ? ["login", agent, `gui/${uid}`]
+      : null;
+  if (!found) return null;
+  const [mode, plist, domain] = found;
+  const code = probe.print(`${domain}/${label}`);
+  const state =
+    code === 0
+      ? "loaded"
+      : code === null || code === 127
+        ? "unknown"
+        : "not-loaded";
+  return { state, mode, plist, domain };
+}
+
+/** The rows as doctor prints them, under a heading. */
+export function formatWhere(rows: WhereRow[], title: string): string[] {
+  if (!rows.length) return [];
+  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" ? "✓" : "⚠";
+    lines.push(`  ${r.what.padEnd(16)}  ${r.session.padEnd(w)}  ${mark}`);
+    if (r.detail) lines.push(`    ${r.status === "ok" ? "" : "⚠ "}${r.detail}`);
+  }
+  return lines;
+}

package/src/ui/cli/index.ts

@@ -5317,7 +5317,7 @@ class DenCLI {
       "  mcp --call <tool>    Call one MCP tool and print its result (--list: tool names)",
     );
     console.log(
-      "  service install      Run the web UI as a launchd service (status, print, uninstall)",
+      "  service install      Run the web UI as a launchd service (status, print, uninstall, help)",
     );
     console.log(
       "  theme add <repo>@<ref> Install a web UI theme (list, validate, remove)",

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";
@@ -1388,6 +1389,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);

package/src/ui/server/index.ts

@@ -918,6 +918,7 @@ import {
 
 import { product } from "../../shared/product.js";
 import { readBrand } from "../../shared/brand.js";
+import { launchdSession } from "../../shared/launchd-session.js";
 /** config `web.port` (user > team), falling back to the built-in default. */
 function readWebPortSafe(): number {
   try {
@@ -4422,6 +4423,9 @@ async function handleRequest(
       // another distribution's server (see cli/server-identity.ts).
       root: ROOT,
       product: product().name,
+      // D20: the launchd session it runs in (Aqua ends at logout); doctor
+      // shows it. null off macOS.
+      launchd: launchdSession(),
       startedAt: new Date(SERVER_STARTED_AT).toISOString(),
       uptimeMs: Date.now() - SERVER_STARTED_AT,
       stale,