@monster-orange/den 0.2.8 → 0.3.0

package/src/shared/environment-manager/service-runner.ts

@@ -9,6 +9,7 @@
 import { hasRuntime, repoKind } from "../repo-kind.js";
 import { effectiveLocalCommands } from "../stacks/manifest-commands.js";
 import { manifestStackName } from "../stacks/config.js";
+import { claimHealthyStack } from "../stacks/owners.js";
 import fs from "fs";
 import path from "path";
 import { readManifest } from "../manifest/read-manifest.js";
@@ -72,6 +73,17 @@ import type { ChildProcess } from "child_process";
 import { getDistRoot, getStateDir } from "../paths.js";
 
 import { product } from "../product.js";
+import {
+  adoptLegacyProcess,
+  busyListenerText,
+  servicePort,
+} from "../process/legacy-adopt.js";
+import {
+  processGroupStateSync,
+  recordProcessGroup,
+  stopProcessGroup,
+  type RecordedProcessGroup,
+} from "../process/process-group.js";
 // Re-export so existing callers don't need to change their import path.
 export type { ServiceHealthResult };
 export { checkServiceHealth, checkCatalogHealth };
@@ -108,6 +120,23 @@ export interface DaemonRecord {
    * written before 0.2.7.
    */
   root?: string;
+  /**
+   * The process group a detached `up` started (its leader's pid), so `down`
+   * can stop a service that has no down command and no container
+   * (0.3.0-dev.37). Missing on records written before that.
+   */
+  pgid?: number;
+  /**
+   * The group leader's start time (`ps -o lstart=`). `down` signals the
+   * group only while the process holding `pgid` started at this time, so a
+   * reused pid is never signalled.
+   */
+  pgidStartedAt?: string;
+  /**
+   * A pid some writers before 0.3.0-dev.37 kept. Only a hint for adopting
+   * such a record (legacy-adopt.ts); never signalled on its own.
+   */
+  pid?: number;
 }
 
 /** This process's distribution root, as stamped on its daemon records. */
@@ -325,6 +354,34 @@ export function updateDaemonContainers(
   saveDaemonsFile(getDaemonsFile());
 }
 
+/** Record the process group a detached `up` just spawned. */
+export function updateDaemonProcessGroup(
+  address: string,
+  group: RecordedProcessGroup,
+): void {
+  loadDaemonsFromFile();
+  const existing = _daemonRegistry.get(address);
+  if (!existing) return;
+  _daemonRegistry.set(address, {
+    ...existing,
+    pgid: group.pgid,
+    pgidStartedAt: group.startedAt,
+  });
+  saveDaemonsFile(getDaemonsFile());
+}
+
+/** Forget a record's process group (it is gone; nothing of it to stop). */
+function clearDaemonProcessGroup(address: string): void {
+  loadDaemonsFromFile();
+  const existing = _daemonRegistry.get(address);
+  if (!existing) return;
+  const rest = { ...existing };
+  delete rest.pgid;
+  delete rest.pgidStartedAt;
+  _daemonRegistry.set(address, rest);
+  saveDaemonsFile(getDaemonsFile());
+}
+
 /**
  * This root's daemons (and unstamped legacy ones). Every root of a product
  * shares one daemons file; another root's records stay in it untouched but
@@ -573,8 +630,21 @@ export function adoptRunningContainers(
 export function claimHealthyService(
   resolved: ResolvedService,
   workspace: string,
-): "attached" | "adopted" | "untracked" {
-  const existing = findDaemonByAddress(resolved.address);
+  onLine: (line: string) => void = () => {},
+): "attached" | "adopted" | "untracked" | "conflict" | "busy" {
+  // A compose stack's primary service: its owner is recorded with the
+  // stack's project (a shared stack namespace's refcount, stacks/owners.ts).
+  // `conflict`: the running project is another checkout's; the caller runs
+  // the real up, which refuses it.
+  const stack = claimHealthyStack(resolved, workspace);
+  if (stack) return stack;
+  // A record from before 0.3.0-dev.37 is settled (adopted or dropped)
+  // before anything is decided on it (0.3.0-dev.39, a consumer's dev.38
+  // finding: the healthy-skip attached to it and it never gained a group).
+  const settled = settleDaemonRecord(resolved, workspace, onLine);
+  // Dropped with its port held from outside the repo: said by the settle.
+  if (settled.outcome === "busy") return "busy";
+  const existing = settled.record;
   if (existing) {
     if (!sameDaemonIdentity(existing, resolved.repoPath, resolved.branch)) {
       // Healthy, but the record describes a different checkout — leave the
@@ -584,9 +654,17 @@ export function claimHealthyService(
     attachDaemonOwner(resolved.address, workspace);
     return "attached";
   }
-  return adoptRunningContainers(resolved, workspace).length > 0
-    ? "adopted"
-    : "untracked";
+  if (adoptRunningContainers(resolved, workspace).length > 0) return "adopted";
+  // Healthy with no record: whose process answers on the service's port?
+  // One in the repo is the service (adopted, so `down` can stop it); one
+  // from elsewhere is not, and is said, never claimed or touched.
+  const holder = settleUntrackedListener(
+    resolved,
+    workspace,
+    onLine,
+    `${resolved.address} not started`,
+  );
+  return holder ?? "untracked";
 }
 
 /**
@@ -644,14 +722,78 @@ export function findDaemonConflict(
 }
 
 function canResolveDaemonAddress(d: DaemonRecord): boolean {
-  if (resolveService(d.address)) return true;
-  for (const w of d.workspaces ?? []) {
-    if (resolveService(d.address, w)) return true;
-  }
-  for (const w of getActiveWorkspaces()) {
-    if (resolveService(d.address, w)) return true;
-  }
-  return false;
+  return resolvedRepoPathsOf(d).length > 0;
+}
+
+/**
+ * This root's records whose address resolves in no active workspace: what
+ * `down -a` (every workspace) cannot reach, and so warns about and leaves
+ * alone (0.3.0-dev.39).
+ */
+export function daemonsOutsideWorkspaces(): DaemonRecord[] {
+  return listDaemons().filter((d) => !canResolveDaemonAddress(d));
+}
+
+/**
+ * Every checkout a daemon's address resolves to now: through the focus,
+ * each workspace that owns it, then every other active workspace (the
+ * same order canResolveDaemonAddress and the reaper use). Empty when the
+ * address no longer resolves anywhere.
+ */
+function resolvedRepoPathsOf(d: DaemonRecord): string[] {
+  const paths = new Set<string>();
+  const add = (r: ResolvedService | null) => {
+    if (r) paths.add(r.repoPath);
+  };
+  add(resolveService(d.address));
+  for (const w of new Set([...(d.workspaces ?? []), ...getActiveWorkspaces()]))
+    add(resolveService(d.address, w));
+  return [...paths];
+}
+
+/** Why a daemon record is stale whatever its address resolves to, or null. */
+export type DaemonStaleReason = "repo-path-missing" | "relocated";
+
+/**
+ * A record that describes nothing that can be running (0.3.0-dev.33, a
+ * consumer's dogfood finding): a record whose repo was relocated kept its
+ * Runs tab forever, because its address still resolved and, with no
+ * containers captured, nothing could prove it dead.
+ *
+ *  - "repo-path-missing": its repoPath is not on disk. Nothing of it can
+ *    run from a checkout that does not exist, whichever root wrote it.
+ *  - "relocated": the address resolves now, but never to its repoPath, and
+ *    nothing of it is live: none of its candidate containers (captured, or
+ *    the dev-op's at its old path) is running. The repo name is not a
+ *    candidate here: the relocated checkout's own container carries it.
+ *    Records carry no pid, so there is no process to check. Needs the
+ *    container listing when it has candidates (null: unverifiable, kept).
+ *
+ * Another root's record is never this root's call (null). A record that
+ * resolves to its own repoPath is never stale here: it may be a live
+ * non-opctl process, and isDaemonVerifiablyDead keeps that rule.
+ */
+export function daemonStaleReason(
+  d: DaemonRecord,
+  running: Set<string> | null,
+  deps: {
+    exists?: (p: string) => boolean;
+    resolvedPaths?: (d: DaemonRecord) => string[];
+    devOpNames?: (repoPath: string) => string[];
+  } = {},
+): DaemonStaleReason | null {
+  if (daemonRootOf(d) === "other") return null;
+  const exists = deps.exists ?? fs.existsSync;
+  if (!d.repoPath || !exists(d.repoPath)) return "repo-path-missing";
+  const now = (deps.resolvedPaths ?? resolvedRepoPathsOf)(d);
+  if (now.length === 0 || now.includes(d.repoPath)) return null;
+  const candidates = [
+    ...(d.containers ?? []),
+    ...(deps.devOpNames ?? devOpContainerNames)(d.repoPath),
+  ].filter(Boolean);
+  if (candidates.length === 0) return "relocated";
+  if (!running) return null;
+  return candidates.some((c) => running.has(c)) ? null : "relocated";
 }
 
 /**
@@ -691,6 +833,9 @@ export function isDaemonVerifiablyDead(
  *  - it is opctl-based (has captured containers or a discoverable dev-op) and
  *    NONE of its candidate containers are currently running.
  *
+ *  - its checkout is gone, or the service now resolves to another checkout
+ *    and nothing of the record's is running (daemonStaleReason).
+ *
  * Daemons with no discoverable opctl containers are KEPT — we can't verify them
  * via `opctl container ls`, so we err toward keeping a possibly-live process
  * (e.g. a non-opctl dev server). Health is deliberately NOT used: a service's
@@ -714,10 +859,14 @@ export function pruneDeadDaemons(): string[] {
 export async function pruneDeadDaemonsAsync(): Promise<string[]> {
   const daemons = listDaemons();
   if (daemons.length === 0) return [];
-  const running = (await isOpctlAvailableAsync())
+  return pruneAgainst(daemons, await runningContainerBasesAsync());
+}
+
+/** The running opctl containers' base names, or null without opctl. */
+export async function runningContainerBasesAsync(): Promise<Set<string> | null> {
+  return (await isOpctlAvailableAsync())
     ? new Set((await listRunningOpctlContainersAsync()).map((c) => c.base))
     : null;
-  return pruneAgainst(daemons, running);
 }
 
 function pruneAgainst(
@@ -738,6 +887,13 @@ function pruneAgainst(
         pruned.push(d.address);
         continue;
       }
+      // A checkout that is gone, or one the service has moved away from
+      // with nothing of it still running (here or unstamped).
+      if (daemonStaleReason(d, running)) {
+        unregisterDaemon(d.address);
+        pruned.push(d.address);
+        continue;
+      }
       if (isDaemonVerifiablyDead(d, running)) {
         unregisterDaemon(d.address);
         pruned.push(d.address);
@@ -1112,17 +1268,22 @@ function opctlDownBasesFromCommand(cmd: string): string[] {
   return bases;
 }
 
+/**
+ * Whether a service command runs detached (a daemon whose log is tailed)
+ * or to completion. Only the commands that start a service, up and restart
+ * (which ends with a long-running up), detach by default; a restart that
+ * finishes on its own says `detachable: false`. Every other command is
+ * one-shot unless it says `detachable: true` (0.3.0-dev.40, DOC-1: every
+ * string command but down and setup detached, so a preflight run from the
+ * Services page never finished). down and setup never detach.
+ */
 export function shouldDetachServiceCommand(
   command: string,
   cmdDef: CommandDef,
 ): boolean {
-  return command === "down" || command === "setup"
-    ? false
-    : typeof cmdDef === "string"
-      ? true
-      : // restart ends with a long-running up, so it detaches unless the
-        // command says it finishes on its own (`detachable: false`).
-        (cmdDef.detachable ?? true);
+  if (command === "down" || command === "setup") return false;
+  const starts = command === "up" || command === "restart";
+  return typeof cmdDef === "string" ? starts : (cmdDef.detachable ?? starts);
 }
 
 export function isInteractiveServiceCommand(cmdDef: CommandDef): boolean {
@@ -1175,6 +1336,356 @@ export interface RunCommandOptions {
    * declares secret_env is refused unless every key is here.
    */
   secretEnv?: Record<string, string>;
+  /**
+   * For `down`: whether the caller named this service (default true). When
+   * down cannot stop a service it knows is running it warns; an explicit
+   * down then exits non-zero, a workspace-wide one does not.
+   */
+  explicit?: boolean;
+  /** For `down`: what it found to stop (see DownOutcome). */
+  onDownOutcome?: (outcome: DownOutcome) => void;
+}
+
+/**
+ * What a `down` of a service with no down command and no container did, for
+ * callers that report it: it "stopped" the process group `up` recorded,
+ * found it "already-exited", had "nothing-recorded" to stop, or could not
+ * stop what it knows is running ("unstoppable").
+ */
+export type DownOutcome =
+  | "stopped"
+  | "already-exited"
+  | "nothing-recorded"
+  | "unstoppable";
+
+/** SIGTERM-to-SIGKILL grace for a recorded process group. */
+function downGraceMs(): number {
+  const raw = process.env.DEN_DOWN_GRACE_MS;
+  const ms = raw === undefined ? NaN : Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? ms : 3000;
+}
+
+type GroupRecord = DaemonRecord & { pgid: number; pgidStartedAt: string };
+
+/** Whether a record carries a process group `down` can verify and signal. */
+function hasProcessGroup(d: DaemonRecord | undefined): d is GroupRecord {
+  return !!d && typeof d.pgid === "number" && !!d.pgidStartedAt;
+}
+
+/**
+ * Stop the process group a detached `up` recorded for this daemon (SIGTERM,
+ * grace, SIGKILL; see process-group.ts), say what happened on `onLine`, and
+ * unregister the record once nothing of it runs.
+ */
+async function stopDaemonProcessGroup(
+  record: GroupRecord,
+  onLine: (line: string) => void,
+): Promise<DownOutcome> {
+  const result = await stopProcessGroup(
+    { pgid: record.pgid, startedAt: record.pgidStartedAt },
+    downGraceMs(),
+  );
+  switch (result.outcome) {
+    case "stopped":
+      onLine(
+        `stopped ${record.address}: process group ${record.pgid} (${result.signal})`,
+      );
+      unregisterDaemon(record.address);
+      return "stopped";
+    case "gone":
+      onLine(
+        `${record.address} had already exited (process group ${record.pgid})`,
+      );
+      unregisterDaemon(record.address);
+      return "already-exited";
+    case "reused":
+      // The recorded process exited; whatever holds its pid now is not ours.
+      onLine(
+        `${record.address} had already exited: ${result.detail}; left it alone`,
+      );
+      unregisterDaemon(record.address);
+      return "already-exited";
+    case "survived":
+      onLine(
+        `Warning: could not stop ${record.address}: process group ${record.pgid} survived SIGKILL (pids ${result.members.join(", ")})`,
+      );
+      return "unstoppable";
+    case "error":
+      onLine(`Warning: could not stop ${record.address}: ${result.detail}`);
+      return "unstoppable";
+  }
+}
+
+/**
+ * The daemon records of `repo`'s own services (`<repo>/<svc>`), this root's
+ * or unstamped, other than `except`: what a repo-level down stops.
+ */
+function repoServiceRecords(repo: string, except: string): DaemonRecord[] {
+  return listDaemons().filter(
+    (d) =>
+      d.address !== except &&
+      d.address.startsWith(`${repo}/`) &&
+      daemonRootOf(d) !== "other",
+  );
+}
+
+/** Which of two down outcomes says more: what a fanned-out down reports. */
+const DOWN_RANK: Record<DownOutcome, number> = {
+  "nothing-recorded": 0,
+  "already-exited": 1,
+  stopped: 2,
+  unstoppable: 3,
+};
+
+/**
+ * Down each address in turn (each through runServiceCommand's own path:
+ * its refcount, its down command or its recorded process group), lines to
+ * the caller's onLine. Resolves the outcome that says most and the worst
+ * exit code.
+ */
+async function downEach(
+  addresses: string[],
+  options: RunCommandOptions,
+): Promise<{ outcome: DownOutcome; exitCode: number }> {
+  let outcome: DownOutcome = "nothing-recorded";
+  let exitCode = 0;
+  for (const address of addresses) {
+    let own: DownOutcome | null = null;
+    const code = await new Promise<number>((resolve) => {
+      runServiceCommand({
+        ...options,
+        address,
+        command: "down",
+        onDownOutcome: (o) => {
+          own = o;
+        },
+        onClose: resolve,
+      });
+    });
+    // A service with a down command of its own reports no outcome: a
+    // success is a stop.
+    const o: DownOutcome = own ?? (code === 0 ? "stopped" : "unstoppable");
+    if (DOWN_RANK[o] > DOWN_RANK[outcome]) outcome = o;
+    exitCode = Math.max(exitCode, code);
+  }
+  return { outcome, exitCode };
+}
+
+/**
+ * A record `up` and `down` can't verify by its process group: none was
+ * recorded (before 0.3.0-dev.37) and it names no container of its own.
+ */
+function isLegacyRecord(d: DaemonRecord): boolean {
+  return (
+    !hasProcessGroup(d) &&
+    !(d.containers?.length ?? 0) &&
+    devOpContainerNames(d.repoPath).length === 0
+  );
+}
+
+/**
+ * The daemon record for `resolved`, settled: a record from before
+ * 0.3.0-dev.37 (no process group, nothing of its own to verify) is adopted
+ * or dropped here, before any caller decides on it (0.3.0-dev.39). Every
+ * up, restart, down and healthy-skip reads its record through this.
+ */
+export function settledDaemonRecord(
+  resolved: ResolvedService,
+  workspace: string,
+  onLine: (line: string) => void,
+): DaemonRecord | undefined {
+  return settleDaemonRecord(resolved, workspace, onLine).record;
+}
+
+/** settledDaemonRecord, with what the settle did (null: nothing to settle). */
+function settleDaemonRecord(
+  resolved: ResolvedService,
+  workspace: string,
+  onLine: (line: string) => void,
+): {
+  record: DaemonRecord | undefined;
+  outcome: "adopted" | "dropped" | "busy" | null;
+} {
+  const record = findDaemonByAddress(resolved.address);
+  if (!record || !isLegacyRecord(record)) return { record, outcome: null };
+  const outcome = settleLegacyRecord(record, resolved, workspace, onLine);
+  return { record: findDaemonByAddress(resolved.address), outcome };
+}
+
+/** The service's known port and configured up command (legacy-adopt.ts). */
+function serviceProcessFacts(
+  resolved: ResolvedService,
+  workspace: string,
+): { port: number | null; upCommand: string | null; plain: boolean } {
+  const manifest = readManifest(resolved.repoPath);
+  const svc = manifest?.services?.[resolved.subsystem] as
+    | { port?: unknown; health?: { local?: { url?: string } } }
+    | undefined;
+  const upDef = manifest
+    ? effectiveLocalCommands(
+        manifest,
+        resolved.subsystem,
+        resolved.repoName,
+        workspace,
+      )["up"]
+    : undefined;
+  const upCommand = upDef ? commandDefToString(upDef) : null;
+  const port = servicePort({
+    port: svc?.port,
+    healthUrl: svc?.health?.local?.url ?? null,
+    upCommand,
+  });
+  // A plain process: an up of its own, no compose stack and no dev op. A
+  // container's port is held by the container runtime, never by the repo.
+  const plain =
+    !!upCommand &&
+    !manifest?.compose &&
+    devOpContainerNames(resolved.repoPath).length === 0;
+  return { port, upCommand, plain };
+}
+
+/**
+ * A service with no record whose port is already taken (a plain process
+ * service only): a listener whose cwd is in the repo is the service,
+ * adopted with its process group ("adopted"); one from elsewhere is
+ * reported and left alone ("busy"). Null when the port is free or unknown.
+ */
+function settleUntrackedListener(
+  resolved: ResolvedService,
+  workspace: string,
+  onLine: (line: string) => void,
+  /** What the caller does about a busy port, said after the warning. */
+  then: string,
+): "adopted" | "busy" | null {
+  const facts = serviceProcessFacts(resolved, workspace);
+  if (!facts.plain || !facts.port) return null;
+  const verdict = adoptLegacyProcess({
+    repoPath: resolved.repoPath,
+    port: facts.port,
+    upCommand: null,
+  });
+  if (verdict.kind === "adopted") {
+    registerDaemon({
+      address: resolved.address,
+      repoName: resolved.repoName,
+      subsystem: resolved.subsystem,
+      repoPath: resolved.repoPath,
+      branch: resolved.branch,
+      workspaces: [workspace],
+      logPath: getServiceLogPath(resolved.repoName, resolved.subsystem),
+      startedAt: new Date(),
+      containers: [],
+    });
+    updateDaemonProcessGroup(resolved.address, verdict.group);
+    onLine(
+      `adopted the running process (pid ${verdict.pid}, port ${facts.port}) for ${resolved.address}: it runs in ${resolved.repoPath}`,
+    );
+    return "adopted";
+  }
+  if (!verdict.busy) return null;
+  onLine(
+    `Warning: ${busyListenerText(verdict.busy, resolved.repoPath, resolved.address)}; ${then}`,
+  );
+  return "busy";
+}
+
+/**
+ * What a record from before 0.3.0-dev.37 means now (legacy-adopt.ts), for
+ * `up` and `down` alike: "adopted" (the running process is the service; its
+ * group is written into the record, so it is `down`'s to stop) or "dropped"
+ * (stale: warned, the record removed, nothing signalled). The port is the
+ * service's known one (servicePort: `port`, its health URL, `--port` in its
+ * up command); the token match uses its configured up command.
+ */
+function settleLegacyRecord(
+  record: DaemonRecord,
+  resolved: ResolvedService,
+  workspace: string,
+  onLine: (line: string) => void,
+): "adopted" | "dropped" | "busy" {
+  const { port, upCommand } = serviceProcessFacts(resolved, workspace);
+  const verdict = adoptLegacyProcess({
+    repoPath: record.repoPath,
+    pid: typeof record.pid === "number" ? record.pid : undefined,
+    port,
+    upCommand,
+  });
+  if (verdict.kind === "adopted") {
+    updateDaemonProcessGroup(record.address, verdict.group);
+    onLine(
+      `adopted pre-dev.37 process (pid ${verdict.pid}` +
+        (verdict.port ? `, port ${verdict.port}` : "") +
+        `) for ${record.address}`,
+    );
+    return "adopted";
+  }
+  onLine(
+    `Warning: ${record.address} was recorded before 0.3.0-dev.37 and ` +
+      (verdict.busy
+        ? "its port is held by a process that is not its up"
+        : `nothing running is it (no process on its port in ${record.repoPath}` +
+          (typeof record.pid === "number"
+            ? `, pid ${record.pid} not its up`
+            : "") +
+          ")") +
+      "; dropped the record, nothing was signalled",
+  );
+  if (verdict.busy)
+    onLine(
+      `Warning: ${busyListenerText(verdict.busy, record.repoPath, record.address)}`,
+    );
+  unregisterDaemon(record.address);
+  return verdict.busy ? "busy" : "dropped";
+}
+
+/**
+ * A restart with no `restart` of its own: the service's down (its declared
+ * down, then the recorded group, as `down` does; forced, since a restart
+ * brings it back for every owner), then its up, detached, as `up` does. The
+ * returned proc stands for the up's streaming tail: killing it stops the
+ * tail (now, or as soon as the up starts), never the service.
+ */
+function restartAsDownThenUp(
+  options: RunCommandOptions,
+  logPath: string | undefined,
+): RunCommandResult {
+  let tail: ChildProcess | null = null;
+  let stopTail = false;
+  const proxy = new EventEmitter() as unknown as ChildProcess;
+  (proxy as unknown as { kill: (s?: NodeJS.Signals) => boolean }).kill = (
+    signal,
+  ) => {
+    stopTail = true;
+    try {
+      tail?.kill?.(signal);
+    } catch {
+      /* already gone */
+    }
+    return true;
+  };
+  runServiceCommand({
+    ...options,
+    command: "down",
+    force: true,
+    onDownOutcome: undefined,
+    onServiceExit: undefined,
+    onClose: (code) => {
+      if (code !== 0) {
+        options.onClose(code);
+        return;
+      }
+      const up = runServiceCommand({ ...options, command: "up" });
+      tail = up.proc;
+      if (stopTail) {
+        try {
+          tail?.kill?.("SIGTERM");
+        } catch {
+          /* already gone */
+        }
+      }
+    },
+  });
+  return { proc: proxy, detachable: true, interactive: false, logPath };
 }
 
 export interface RunCommandResult {
@@ -1216,6 +1727,18 @@ function repoStartedFallback(
   if (!repoEntry || repoEntry.subsystem === resolved.subsystem) return null;
   const manifest = readManifest(resolved.repoPath);
   if (!manifest) return null;
+  // A service with an up of its own starts itself, so its down is its own
+  // too: the process group that up recorded (0.3.0-dev.39, a consumer's
+  // dev.38 finding: `down repo/api` pointed at the repo's down instead).
+  if (
+    effectiveLocalCommands(
+      manifest,
+      resolved.subsystem,
+      resolved.repoName,
+      workspace ?? "default",
+    )["up"]
+  )
+    return null;
   const repoCommands = effectiveLocalCommands(
     manifest,
     repoEntry.subsystem,
@@ -1345,11 +1868,64 @@ export async function prepareServiceSecretEnv(
 
 /** What a run of `command` on `address` would do, without running it. */
 export type ServiceCommandPreview =
-  | { kind: "run"; address: string }
+  | { kind: "run"; address: string; note?: string }
   | { kind: "via-repo"; address: string; note: string }
   | { kind: "nothing"; address: string; note: string }
   | { kind: "error"; address: string; note: string };
 
+/**
+ * What a real `up` of a service with an up of its own does first about its
+ * record and port (settleDaemonRecord, settleUntrackedListener), said for a
+ * dry run (0.3.0-dev.40, a consumer's dev.39 nit: it said only "Would up").
+ * It only looks: nothing is signalled and the record is not written. Null
+ * when there is nothing to settle (the up just runs). Only for a dry run's
+ * words: up-targets reads previewServiceCommand, which this leaves alone.
+ */
+export function previewUpSettle(
+  address: string,
+  workspace?: string,
+): ServiceCommandPreview | null {
+  const resolved = resolveService(address, workspace);
+  if (!resolved) return null;
+  const record = findDaemonByAddress(resolved.address);
+  const legacy = !!record && isLegacyRecord(record);
+  if (record && !legacy) return null;
+  const facts = serviceProcessFacts(resolved, workspace ?? "default");
+  if (!facts.upCommand) return null;
+  if (!legacy && (!facts.plain || !facts.port)) return null;
+  const verdict = adoptLegacyProcess({
+    repoPath: resolved.repoPath,
+    pid: legacy && typeof record.pid === "number" ? record.pid : undefined,
+    port: facts.port,
+    upCommand: legacy ? facts.upCommand : null,
+  });
+  const what = legacy ? "a pre-dev.37 record" : "no record";
+  if (verdict.kind === "adopted")
+    return {
+      kind: "nothing",
+      address,
+      note:
+        `${resolved.address} (${what}): would adopt pid ${verdict.pid}` +
+        (verdict.port ? ` (port ${verdict.port})` : "") +
+        ", nothing started",
+    };
+  if (verdict.busy)
+    return {
+      kind: "error",
+      address,
+      note:
+        verdict.busy.reason === "outside"
+          ? `${resolved.address} (${what}): port ${verdict.busy.port} held outside the repo: would not start`
+          : `${resolved.address} (${what}): port ${verdict.busy.port} held by pid ${verdict.busy.pid} in Den's own process group: would not start`,
+    };
+  if (!legacy) return null;
+  return {
+    kind: "run",
+    address,
+    note: `${resolved.address} (${what}): would drop the record (nothing running), then start it`,
+  };
+}
+
 /**
  * The dry-run twin of runServiceCommand's command lookup: the same
  * resolution, own-command, restart-synthesis and repo-started rules, so a
@@ -1382,7 +1958,7 @@ export function previewServiceCommand(
         workspace ?? "default",
       )
     : {};
-  if (own[command] || (command === "restart" && own["down"] && own["up"]))
+  if (own[command] || (command === "restart" && own["up"]))
     return { kind: "run", address };
   const viaRepo = repoStartedFallback(resolved, command, workspace);
   if (viaRepo?.address)
@@ -1391,12 +1967,22 @@ export function previewServiceCommand(
     return command === "down"
       ? { kind: "nothing", address, note: viaRepo.note }
       : { kind: "error", address, note: viaRepo.note };
-  if (command === "down")
+  if (command === "down") {
+    // The real down stops the process group a detached up recorded.
+    const record = findDaemonByAddress(resolved.address);
+    if (hasProcessGroup(record)) return { kind: "run", address };
+    // A repo-level down stops its services' records.
+    if (
+      !address.includes("/") &&
+      repoServiceRecords(resolved.repoName, resolved.address).length > 0
+    )
+      return { kind: "run", address };
     return {
       kind: "nothing",
       address,
       note: "no down command: nothing to stop",
     };
+  }
   return {
     kind: "error",
     address,
@@ -1467,6 +2053,68 @@ export function runServiceCommand(
 
   const { repoPath, subsystem } = resolved;
 
+  const explicit = options.explicit ?? true;
+  const reportDown = (outcome: DownOutcome): void =>
+    options.onDownOutcome?.(outcome);
+  // A down that could not stop what it knows is running: always a warning,
+  // and a failure when the caller named this service.
+  const unstoppableExit = (): number => (explicit ? 1 : 0);
+
+  /**
+   * Down with no down command and no container to stop (0.3.0-dev.37): stop
+   * the process group a detached `up` recorded. With no record there is
+   * nothing to stop. A record without a group (written before dev.37, or by
+   * an adoption) is running as far as Den knows, and Den cannot stop it:
+   * that is said and fails an explicit down instead of reporting a success.
+   * Such a record is dropped, since Den can neither stop nor verify it.
+   */
+  const downWithoutCommand = (why: string): RunCommandResult => {
+    // A repo-level down (`down <repo>`, and `down -a`, which downs each
+    // repo) with no down of its own stops every service record of the repo
+    // through the same per-record path (0.3.0-dev.38): the mirror of `up`
+    // starting a repo's services (resolveUpTargets).
+    const serviceRecords = address.includes("/")
+      ? []
+      : repoServiceRecords(resolved.repoName, resolved.address);
+    if (serviceRecords.length > 0) {
+      void downEach(
+        serviceRecords.map((d) => d.address),
+        options,
+      ).then(({ outcome, exitCode }) => {
+        const own = findDaemonByAddress(resolved.address);
+        if (own) unregisterDaemon(own.address);
+        reportDown(outcome);
+        onClose(exitCode);
+      });
+      return dummy();
+    }
+    // A record from before 0.3.0-dev.37: adopt what runs, or drop it.
+    const record = settledDaemonRecord(resolved, workspace, onLine);
+    if (hasProcessGroup(record)) {
+      void stopDaemonProcessGroup(record, onLine).then((outcome) => {
+        reportDown(outcome);
+        onClose(outcome === "unstoppable" ? unstoppableExit() : 0);
+      });
+      return dummy();
+    }
+    if (record && !isDaemonVerifiablyDead(record)) {
+      onLine(
+        `Warning: ${record.address} is recorded as running, but ${product().cli} kept no process for it ` +
+          `(started before 0.3.0-dev.37) and it has no down command; ` +
+          `stop it yourself (${product().cli} has dropped its record)`,
+      );
+      unregisterDaemon(record.address);
+      reportDown("unstoppable");
+      closeAsync(unstoppableExit());
+      return dummy();
+    }
+    if (record) unregisterDaemon(record.address);
+    onLine(`nothing to stop (${why})`);
+    reportDown("nothing-recorded");
+    closeAsync(0);
+    return dummy();
+  };
+
   // R13: Den never runs a command on a remote service. A down stops nothing
   // here, which is a success; anything else is refused.
   const refusal = placementRefusal(
@@ -1481,6 +2129,22 @@ export function runServiceCommand(
     return dummy();
   }
 
+  // Every up decision below reads the service's record: one from before
+  // 0.3.0-dev.37 is settled (adopted or dropped, and said) first
+  // (0.3.0-dev.39, a consumer's dev.38 finding). A restart settles in its
+  // down step; a down after its ownership gate, which signals nothing.
+  const upSettle =
+    command === "up" ? settleDaemonRecord(resolved, workspace, onLine) : null;
+  // Dropped with its port held by a process Den won't adopt (said by the
+  // settle): refused before anything is spawned, as a repo-level up refuses
+  // it (0.3.0-dev.40, a consumer's dev.39 finding: the start died on
+  // EADDRINUSE first).
+  if (upSettle?.outcome === "busy") {
+    onLine(`${resolved.address} not started: its port is in use`);
+    closeAsync(1);
+    return dummy();
+  }
+
   // ── Up: share-if-identical / hard-block on conflict ─────────────────────────
   if (command === "up" || command === "restart") {
     let existing = findDaemonByAddress(resolved.address);
@@ -1541,6 +2205,25 @@ export function runServiceCommand(
           closeAsync(0);
           return dummy();
         }
+      } else if (command === "up" && !upSettle?.outcome) {
+        // Nothing recorded, but the port is taken (0.3.0-dev.39). In the
+        // repo: that is the service, adopted, already up. Elsewhere: said
+        // and left alone, and refused before anything is spawned
+        // (0.3.0-dev.40), as a repo-level up refuses it.
+        const holder = settleUntrackedListener(
+          resolved,
+          workspace,
+          onLine,
+          `${resolved.address} not started`,
+        );
+        if (holder === "adopted") {
+          closeAsync(0);
+          return dummy();
+        }
+        if (holder === "busy") {
+          closeAsync(1);
+          return dummy();
+        }
       }
     }
   }
@@ -1568,6 +2251,9 @@ export function runServiceCommand(
       return dummy();
     }
   }
+  // Past the ownership gate, a down stops what it finds: a pre-dev.37 record
+  // is settled first, so its adopted group is stopped (0.3.0-dev.39).
+  if (command === "down") settledDaemonRecord(resolved, workspace, onLine);
 
   // Down via opctl: stop the service's running containers directly, identified
   // from live `opctl container ls` ∪ docker `opctl_<base>_<hash>` names — no
@@ -1654,11 +2340,9 @@ export function runServiceCommand(
     // there is nothing to stop — success, same contract as the declared-down
     // fallthrough below.
     if (command === "down") {
-      onLine(
-        `nothing to stop (no matching opctl containers; no manifest at ${repoPath})`,
+      return downWithoutCommand(
+        `no matching opctl containers; no manifest at ${repoPath}`,
       );
-      closeAsync(0);
-      return dummy();
     }
     onLine(`Error: could not read ${product().manifestYml} in ${repoPath}`);
     closeAsync(1);
@@ -1679,6 +2363,17 @@ export function runServiceCommand(
   if (!cmdDef && command === "restart") {
     const downDef = svcCommands["down"];
     const upDef = svcCommands["up"];
+    // A daemon restart is a down step, then a detached up step, never one
+    // `sh -c "<down> && <up>"`: the up's recorded process group must hold
+    // only the up (0.3.0-dev.38). The tab runtime composes its own below.
+    // With no down of its own (0.3.0-dev.39, a consumer's dev.38 finding),
+    // the down step stops what the detached up recorded, as `down` does.
+    if (upDef && (!downDef || runtime !== "tab")) {
+      return restartAsDownThenUp(
+        options,
+        getServiceLogPath(resolved.repoName, resolved.subsystem),
+      );
+    }
     if (downDef && upDef) {
       const downCmd = rewriteLegacyOpctlKillCommand(
         "down",
@@ -1706,9 +2401,7 @@ export function runServiceCommand(
     // successful down, not an error (keeps the ⋮ menu / workspace Down safe to
     // offer on every system).
     if (command === "down") {
-      onLine("nothing to stop (no running opctl containers, no down command)");
-      closeAsync(0);
-      return dummy();
+      return downWithoutCommand("no running opctl containers, no down command");
     }
     onLine(
       `Error: command "${command}" not found for service "${address}" (subsystem "${subsystem}") in local environment`,
@@ -1964,6 +2657,17 @@ export function runServiceCommand(
       // "nothing left to stop" is an absence of evidence, not evidence the
       // teardown worked — reporting ✔ there would hide every real failure.
       const effective = exitCode === 0 || sweptClean ? 0 : exitCode;
+      // The down command ran; what the detached up started may still run
+      // (the down stopped its containers, not the process that started
+      // them). Stop the recorded group too (0.3.0-dev.37).
+      const record = findDaemonByAddress(resolved.address);
+      if (effective === 0 && hasProcessGroup(record)) {
+        void stopDaemonProcessGroup(record, onLine).then((outcome) => {
+          closeExistingTab();
+          onClose(outcome === "unstoppable" ? unstoppableExit() : 0);
+        });
+        return;
+      }
       if (effective === 0) {
         unregisterDaemon(resolved.address);
         closeExistingTab();
@@ -1983,17 +2687,59 @@ export function runServiceCommand(
     onClose(exitCode);
   };
 
-  const proc = spawnStreaming(
-    cmdString,
-    [],
-    { ...process.env, ...runEnv },
-    onLine,
-    wrappedOnClose,
-    repoPath,
-    detachable,
-    logPath,
-    onServiceExit,
-  );
+  // A detached up records its process group, so `down` can stop it.
+  let recorded: RecordedProcessGroup | null = null;
+  const recordGroup =
+    detachable && logPath && command !== "down"
+      ? (pid: number) => {
+          recorded = recordProcessGroup(pid);
+          if (recorded) updateDaemonProcessGroup(resolved.address, recorded);
+        }
+      : null;
+  // A detached up whose whole group is gone when its leader exits leaves
+  // nothing to stop: never keep its pgid (0.3.0-dev.39, a consumer's dev.38
+  // finding: a second server that died on EADDRINUSE was recorded, and a
+  // later down signalled the dead group while the real listener ran on).
+  // A failed start keeps no record at all.
+  const serviceExited = (exitCode: number): void => {
+    const rec = recorded;
+    if (rec && processGroupStateSync(rec)?.state === "gone") {
+      const now = findDaemonByAddress(resolved.address);
+      // A non-zero exit is a failed start: nothing of it runs, so no
+      // record (its containers, if any, still run: then only the group
+      // goes). A zero exit handed off (`make up`): its group stays, and
+      // down says it already exited.
+      if (now?.pgid === rec.pgid && exitCode !== 0) {
+        if (!(now.containers?.length ?? 0)) unregisterDaemon(resolved.address);
+        else clearDaemonProcessGroup(resolved.address);
+      }
+    }
+    onServiceExit?.(exitCode);
+  };
+  const proc = recordGroup
+    ? spawnStreaming(
+        cmdString,
+        [],
+        { ...process.env, ...runEnv },
+        onLine,
+        wrappedOnClose,
+        repoPath,
+        detachable,
+        logPath,
+        serviceExited,
+        recordGroup,
+      )
+    : spawnStreaming(
+        cmdString,
+        [],
+        { ...process.env, ...runEnv },
+        onLine,
+        wrappedOnClose,
+        repoPath,
+        detachable,
+        logPath,
+        onServiceExit,
+      );
   return { proc, detachable, interactive: false, logPath };
 }