omp-conductor 0.15.12 → 0.15.13

package/src/doctor.ts

@@ -27,18 +27,38 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { Stats } from "node:fs";
 import { Database } from "bun:sqlite";
 
 import { configBackupDir, configPath, findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
-import { DEFAULT_HERDR_UNIT, probeTelegramHealth, telegramStateDir, type TelegramHealth } from "./fleet.ts";
-import { planHostRuntime, STAGED_SERVICE_NAME, SYSTEMD_UNIT_DIR, totalConfiguredWorkers } from "./setup-host.ts";
+import {
+  DEFAULT_HERDR_UNIT,
+  probeTelegramHealth,
+  resolveHerdrSessionWithBridge,
+  telegramStateDir,
+  type TelegramHealth,
+} from "./fleet.ts";
+import {
+  herdrConductorPluginConfigDir,
+  planHostRuntime,
+  STAGED_SERVICE_NAME,
+  SYSTEMD_UNIT_DIR,
+  tickCwdForProject,
+  totalConfiguredWorkers,
+} from "./setup-host.ts";
 import { checkTokenScopes, type ScopeCheck } from "./setup.ts";
 import { dbPath, LIVE_STATES } from "./store.ts";
 import { telegramReportSend, type ReportSend } from "./reports.ts";
 import { fetchRateLimit, GhError, gh } from "./tracker/github.ts";
 import { repoSlugFor } from "./gitops.ts";
+import {
+  DEFAULT_FLEET_AGENT_NAME,
+  parseHerdrAgents,
+  readTickConfig,
+  type HerdrAgentList,
+} from "./orchestrator-tick.ts";
 import type { ConductorConfig, ProjectConfig, RepoTarget, RunState } from "./types.ts";
 
 /**
@@ -148,6 +168,20 @@ export interface DoctorDeps {
   telegramSend?: (project: ProjectConfig) => ReportSend;
   /** The canonical units to compare the installed units against. */
   canonicalUnits?: (project: ProjectConfig, cfg: ConductorConfig) => CanonicalUnits;
+  /** Whether herdr is installed on this host (a `herdr` on PATH). */
+  herdrInstalled?: () => boolean;
+  /** Live `herdr --session <s> agent list`, parsed through the tick's own
+   *  parser (the same "one JSON line on stdout" contract recover.sh reads). */
+  herdrAgents?: (session: string) => HerdrAgentList;
+  /** The fleet session name, for the rename fix line. */
+  herdrSession?: () => string;
+  /** The live herdr config at `~/.config/herdr/config.toml`, or undefined. */
+  herdrConfig?: () => string | undefined;
+  /** The live herdr-conductor plugin `config.env`, or undefined. */
+  herdrEnv?: () => string | undefined;
+  /** The fleet agent name the tick config of one project names, or undefined
+   *  when there is no (readable) tick — the expected live herdr pane identity. */
+  tickAgentName?: (project: ProjectConfig) => string | undefined;
   /** Clock, so a run is deterministic in tests. */
   now?: () => number;
   /** The one opt-in side effect: send one self-identified Telegram probe. */
@@ -790,7 +824,190 @@ function spendProbe(rows: RunSpendRow[], limit: number): Finding {
   return passFinding("spend-telemetry", `spend observed on the last ${window.length} completed runs ($${total.toFixed(2)} total)`);
 }
 
-// ------------------------------------------------------------- composition
+/** Live `herdr --session <session> agent list` through the project's own
+ *  parser — the published "one JSON line on stdout" interface, never the
+ *  socket. Same bound as the tick's own query so a hung herdr cannot hang
+ *  doctor. */
+function defaultHerdrAgents(session: string): HerdrAgentList {
+  try {
+    const run = spawnSync("herdr", ["--session", session, "agent", "list"], {
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (run.error !== undefined) return { kind: "unavailable", problem: run.error.message };
+    if (run.status !== 0) {
+      return {
+        kind: "unavailable",
+        problem: `herdr agent list exited ${String(run.status)}: ${(run.stderr ?? "").trim().split("\n")[0] ?? ""}`,
+      };
+    }
+    return parseHerdrAgents(run.stdout ?? "");
+  } catch (err) {
+    return { kind: "unavailable", problem: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Live herdr config, defaulting to the fleet account's own path. */
+function defaultHerdrConfig(): string | undefined {
+  try {
+    return readFileSync(join(homedir(), ".config", "herdr", "config.toml"), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Live herdr-conductor plugin `config.env`, same path setup provisions. */
+function defaultHerdrEnv(): string | undefined {
+  try {
+    return readFileSync(join(herdrConductorPluginConfigDir(homedir()), "config.env"), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * #541 check 1 — live herdr agent name equals the tick config's agentName.
+ *
+ * The paneOwnership decline the fleet actually hit names the exact fix (`herdr
+ * agent rename <pane> <name>`); doctor checks the same premise the tick does
+ * (is a pane registered under the configured agent name?) and reports drift
+ * with the one-line remedy.
+ */
+function herdrAgentNameProbe(probes: Probes, p: ProjectConfig): Finding {
+  if (!probes.herdrInstalled()) {
+    return passFinding("herdr-agent-name", `[${p.name}] herdr not installed — nothing to check`);
+  }
+  const want = probes.tickAgentName(p);
+  if (want === undefined) {
+    return passFinding("herdr-agent-name", `[${p.name}] no readable tick config — nothing to check`);
+  }
+  const session = probes.herdrSession();
+  const agents = probes.herdrAgents(session);
+  if (agents.kind !== "ok") {
+    return failFinding(
+      "herdr-agent-name",
+      `[${p.name}] could not read the live herdr agent list (${agents.problem}) — cannot verify the fleet agent name`,
+      `restore the herdr session (check \`herdr status\`), then re-run doctor`,
+    );
+  }
+  const holders = agents.agents.filter((a) => a.name === want);
+  if (holders.length > 0) {
+    return passFinding("herdr-agent-name", `[${p.name}] live pane(s) ${holders.map((a) => a.paneId).join(", ")} are agent "${want}"`);
+  }
+  // Drift: no pane carries the configured identity. Exactly one pane pinned to
+  // the shared default is the safe candidate from the decline turnover — name
+  // it when unambiguous, else give the generic command.
+  const stale = agents.agents.filter((a) => a.name === DEFAULT_FLEET_AGENT_NAME);
+  const pane = stale.length === 1 ? stale[0]!.paneId : "<pane>";
+  return failFinding(
+    "herdr-agent-name",
+    `[${p.name}] no live pane is agent "${want}" — every tick will be declined until the fleet pane carries this name (the 2026-08-15 restamp class)`,
+    `herdr --session ${session} agent rename ${pane} ${want}`,
+  );
+}
+
+/**
+ * #541 check 2 — `[session] resume_agents_on_restore` on the live herdr config.
+ *
+ * herdr's own README: the default `true` leaves a restored omp pane with a
+ * deferred resume plan and no live terminal, which is the configuration that
+ * pages instead of recovering. Absent ~ the unrecoverable default; an explicit
+ * `true` is a deliberate (desktop) choice and only warned.
+ */
+function herdrResumeProbe(probes: Probes): Finding {
+  if (!probes.herdrInstalled()) {
+    return passFinding("herdr-resume", "herdr not installed — nothing to check");
+  }
+  const live = probes.herdrConfig();
+  if (live === undefined) {
+    return failFinding(
+      "herdr-resume",
+      "no herdr config at " + join(homedir(), ".config", "herdr", "config.toml") + " — a restored omp pane gets no live terminal (herdr's own README)",
+      "run \`omp-conductor setup host\` from the fleet account (writes [session] resume_agents_on_restore = false), or add it by hand",
+    );
+  }
+  let parsed: { session?: { resume_agents_on_restore?: unknown } };
+  try {
+    parsed = Bun.TOML.parse(live) as { session?: { resume_agents_on_restore?: unknown } };
+  } catch (err) {
+    return failFinding(
+      "herdr-resume",
+      `the live herdr config does not parse (${err instanceof Error ? err.message : String(err)}) — herdr itself refuses it`,
+      "run `herdr config check` to name the line, fix, then re-run doctor",
+    );
+  }
+  const value = parsed.session?.resume_agents_on_restore;
+  if (value === false) {
+    return passFinding("herdr-resume", "resume_agents_on_restore is false — restored panes come up as shells, not deferred plans");
+  }
+  if (value === true) {
+    return warnFinding(
+      "herdr-resume",
+      "resume_agents_on_restore is explicitly true — possibly a deliberate desktop config, but a headless fleet restores panes with no live terminal",
+      "set it to false for a headless host ([session] resume_agents_on_restore = false), or run `omp-conductor setup host`",
+    );
+  }
+  return failFinding(
+    "herdr-resume",
+    "resume_agents_on_restore is absent — herdr defaults it to true, the configuration its own README calls unrecoverable",
+    "run `omp-conductor setup host` from the fleet account (writes the key), or add [session] resume_agents_on_restore = false by hand",
+  );
+}
+
+/**
+ * #541 check 3 — herdr-conductor `config.env` FLEET_CWDS vs the configured
+ * projects. Absent, a virgin host recovers against legacy `/root/fleet` paths
+ * that do not exist: recovery still runs, only the page silently goes nowhere.
+ */
+function herdrEnvProbe(probes: Probes, cfg: ConductorConfig | undefined): Finding {
+  if (!probes.herdrInstalled()) {
+    return passFinding("herdr-config-env", "herdr not installed — nothing to check");
+  }
+  if (cfg === undefined) {
+    return passFinding("herdr-config-env", "config unreadable — nothing to compare");
+  }
+  const live = probes.herdrEnv();
+  if (live === undefined) {
+    return failFinding(
+      "herdr-config-env",
+      "no herdr-conductor config.env — recovery falls back to legacy /root-based single-tenant paths this host does not use, so pages silently skip",
+      "run `omp-conductor setup host` from the fleet account (writes config.env)",
+    );
+  }
+  const expected = new Set(cfg.projects.map((p) => tickCwdForProject(p)));
+  const actual = parseFleetCwds(live);
+  const coherent =
+    actual !== undefined && actual.size === expected.size && [...actual].every((cwd) => expected.has(cwd));
+  if (coherent) {
+    return passFinding("herdr-config-env", `config.env FLEET_CWDS matches the configured fleets (${[...expected].join(":")})`);
+  }
+  return failFinding(
+    "herdr-config-env",
+    `config.env FLEET_CWDS (${actual === undefined ? "unset" : [...actual].join(":")}) does not match the configured fleets (${[...expected].join(":")})`,
+    "re-run `omp-conductor setup host`, which derives FLEET_CWDS from the configured projects",
+  );
+}
+
+/** FLEET_CWDS (colon- or space-separated, per recover.sh) or undefined. */
+function parseFleetCwds(text: string): Set<string> | undefined {
+  const value = parseEnvKey(text, "FLEET_CWDS");
+  if (value !== undefined) {
+    return new Set(value.split(/[\s:]+/).filter((w) => w.length > 0));
+  }
+  // Legacy single-fleet form, the same fallback recover.sh applies.
+  const legacy = parseEnvKey(text, "FLEET_CWD");
+  return legacy === undefined ? undefined : new Set([legacy]);
+}
+
+/** The first unquoted-or-quoted `KEY=value` on its own line, comments ignored. */
+function parseEnvKey(text: string, key: string): string | undefined {
+  for (const line of text.split("\n")) {
+    const match = new RegExp(`^[ \\t]*${key}[ \\t]*=[ \\t]*"?([^"\\n]*)"?[ \\t]*$`).exec(line);
+    if (match !== null) return match[1];
+  }
+  return undefined;
+}
 
 /**
  * Run every probe and assemble the stable report.
@@ -873,8 +1090,14 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     findings.push(
       passFinding("labels", projectProblem === undefined ? "no project resolved — nothing to check" : `labels uncheckable: ${projectProblem}`),
     );
+    findings.push(
+      passFinding("herdr-agent-name", projectProblem === undefined ? "no project resolved — nothing to check" : `agent name uncheckable: ${projectProblem}`),
+    );
   } else {
-    for (const p of projects) findings.push(await labelProbe(probes, p));
+    for (const p of projects) {
+      findings.push(await labelProbe(probes, p));
+      findings.push(herdrAgentNameProbe(probes, p));
+    }
   }
   // The installed-unit check is host-global: one shared daemon. Any project
   // renders the same canonical units (the daemon/units carry no project), so
@@ -882,6 +1105,10 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
   findings.push(unitProbe(probes, projects[0], cfg));
   findings.push(recoveryProbe(probes));
   findings.push(ownershipProbe(probes));
+  // #541 seam checks, host-global: the live herdr config and the plugin's
+  // config.env are single files on the host, not per-project facts.
+  findings.push(herdrResumeProbe(probes));
+  findings.push(herdrEnvProbe(probes, cfg));
   if (projects.length === 0) {
     findings.push(timezoneProbe(undefined));
     findings.push(await telegramProbe(probes, undefined, checkedAt));
@@ -926,6 +1153,16 @@ export function defaultProbes(): Probes {
     telegramHealth: (projectName) => probeTelegramHealth(projectName),
     telegramSend: telegramReportSend,
     canonicalUnits: defaultCanonicalUnits,
+    herdrInstalled: () => Bun.which("herdr") !== null,
+    herdrAgents: defaultHerdrAgents,
+    herdrSession: () => resolveHerdrSessionWithBridge(),
+    herdrConfig: defaultHerdrConfig,
+    herdrEnv: defaultHerdrEnv,
+    tickAgentName: (p) => {
+      const tick = readTickConfig(tickCwdForProject(p));
+      if (tick.kind !== "ok") return undefined;
+      return tick.config.agentName ?? DEFAULT_FLEET_AGENT_NAME;
+    },
     now: Date.now,
     probeTelegram: false,
   };

package/src/escalate.ts

@@ -144,6 +144,7 @@ export function createEscalator(
   orchestrator?: OrchestratorHandle,
   now: () => number = Date.now,
   deliveryAllowed: () => boolean = () => true,
+  onTier1Diverted?: (e: Escalation) => void,
 ): Escalator {
   const currentProject = typeof source === "function" ? source : (): ProjectConfig => source;
   return {
@@ -278,6 +279,13 @@ export function createEscalator(
       // Tier 1 lands here with no orchestrator, or with one that would not take
       // the injection; tier 2 lands here when omp-telegram is not installed or
       // the project never configured a chat id.
+      //
+      // A tier-1 event reaching this point was diverted from the orchestrator to
+      // an issue comment. That is the exact condition the down incident counts:
+      // the daemon hooks this to accumulate the orchestrator-down incident's
+      // diverted tally (a reader that owns its own dedupe and no-ops for a
+      // healthy or external orchestrator).
+      if (e.tier === 1) onTier1Diverted?.(e);
       if (!p.escalation.fallbackToIssueComment) {
         throw new Error(
           `no escalation transport configured for project "${p.name}": tier ${e.tier} ` +

package/src/fleet.ts

@@ -36,7 +36,7 @@ import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
 import { inspectBriefLayout } from "./brief-upgrade.ts";
 import { dbPath, openStore } from "./store.ts";
 import { renderBriefForProject } from "./setup.ts";
-import type { ProjectConfig, Store } from "./types.ts";
+import type { DaemonStop, ProjectConfig, Store } from "./types.ts";
 import { settlementFlagSummary } from "./diff-flags.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { formatDigestBacklog, formatOpenReports } from "./reports.ts";
@@ -52,6 +52,7 @@ import {
   statusSnapshot,
   type StatusSnapshot,
 } from "./daemon.ts";
+import { formatOrchestratorDown } from "./orchestrator-down.ts";
 import {
   healthCheck,
   isAlive,
@@ -1410,6 +1411,31 @@ function formatDaemonUnit(unit: UnitOwnership | undefined, recordPid: number): s
   }
 }
 
+/**
+ * The newest daemon stop/restart provenance as status lines (#378).
+ *
+ * Rendered under the daemon block whether the daemon is down or has since
+ * been restarted — the whole point is that the debrief survives the restart.
+ * An unattributed record says so explicitly: the external-signal fallback
+ * records what the receiving daemon knew (that it was unattributed, when,
+ * which projects it served with live counts) rather than guessing a caller.
+ */
+function formatLastStop(lastStop: DaemonStop | undefined): string[] {
+  if (lastStop === undefined) return [];
+  const caller = lastStop.unattributed
+    ? "unattributed — no mediated request (external signal)"
+    : `pid ${lastStop.callerPid ?? "?"}` +
+      (lastStop.callerUid === undefined ? "" : ` uid ${lastStop.callerUid}`) +
+      (lastStop.role === undefined ? "" : ` (${lastStop.role})`);
+  return [
+    `  last stop  ${new Date(lastStop.at).toISOString()}  ${lastStop.controlPath}`,
+    `  caller     ${caller}`,
+    `  scope      ${lastStop.scope}${lastStop.project === undefined ? "" : `: ${lastStop.project}`}`,
+    `  affects    ${lastStop.affected.map((a) => `${a.project} (${a.live} live)`).join(", ")}`,
+    `  reason     ${lastStop.reason}`,
+  ];
+}
+
 export function formatFleetStatus(
   s: StatusSnapshot,
   layers: FleetLayers,
@@ -1422,6 +1448,7 @@ export function formatFleetStatus(
   failureClasses: string | undefined = undefined,
   workerPhases: ReadonlyMap<number, WorkerPausePhase> = new Map(),
   intake: string | undefined = undefined,
+  lastStop: DaemonStop | undefined = undefined,
 ): string {
   const tickLine =
     layers.ticksDetail === undefined
@@ -1505,8 +1532,9 @@ export function formatFleetStatus(
     ...(intake === undefined ? [] : [intake]),
     ...(graphBlock === undefined ? [] : [graphBlock]),
     daemonBlock,
+    ...formatLastStop(lastStop),
     "",
-    formatProjectBody(s, workerPhases),
+    formatProjectBody(s, workerPhases, now),
   ].join("\n");
 }
 
@@ -1540,12 +1568,18 @@ function formatDigestScheduleStatus(s: StatusSnapshot): string[] {
 function formatProjectBody(
   s: StatusSnapshot,
   workerPhases: ReadonlyMap<number, WorkerPausePhase> = new Map(),
+  now = Date.now(),
 ): string {
   const lines = [
     `project   ${s.project}${s.paused ? "  (PAUSED)" : ""}`,
     ...(s.pauseReason === undefined ? [] : [`paused    ${s.pauseReason}`]),
     `config    ${s.configPath}`,
     `state     ${s.stateDir}`,
+    // The orchestrator-down degrade row: first-class in the body, present only
+    // while the incident is open, so recovery drops it (#288).
+    ...(s.orchestratorDown === undefined
+      ? []
+      : formatOrchestratorDown(s.orchestratorDown, now)),
     ...formatAvailabilityStatus(s),
     ...formatDigestScheduleStatus(s),
     "",
@@ -1675,6 +1709,18 @@ export async function renderStatus(projectName?: string): Promise<string> {
   const cached = codeGraphFromHealthz(healthBody, project.name);
   const codeGraph = cached ?? (await probeCodeGraph(project));
   const workerPhases = workerPhasesFromHealthz(healthBody, project.name);
+  // The newest host-wide stop/restart provenance (#378). Read here — not in
+  // `statusSnapshot`, which is synchronous and belongs to the daemon module —
+  // and rendered identically from either project: the daemon_stops table is
+  // deliberately not partitioned by project, because the daemon serves every
+  // project and the uninvolved one must see who stopped it too.
+  const store = openStore(dbPath());
+  let lastStop: DaemonStop | undefined;
+  try {
+    lastStop = store.latestDaemonStop();
+  } finally {
+    store.close();
+  }
   return formatFleetStatus(
     { ...s, planUsage, github },
     layers,
@@ -1687,6 +1733,7 @@ export async function renderStatus(projectName?: string): Promise<string> {
     failureClassBlock(project.name),
     workerPhases,
     intakeStatusLine(project.name),
+    lastStop,
   );
 }
 

package/src/lifecycle.ts

@@ -25,6 +25,10 @@ import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+// Type-only: erased at runtime, so the "free of every other module" property
+// below survives — this module still opens no store, loads no config and runs
+// no `gh`, and `stop`/`status` keep working when the config is broken.
+import type { DaemonStopDraft } from "./types.ts";
 
 /**
  * The systemd unit name operators are expected to install for a supervised
@@ -480,6 +484,58 @@ export async function startDaemon(
   );
 }
 
+/**
+ * The delivery facts a mediated stop/restart records at the exact chokepoint:
+ * the request's own provenance, how the stop is about to be delivered, and the
+ * daemon pid it targets (#378). The recorder is injected by the CLI callers
+ * (which own the store); this module stays free of it.
+ */
+export interface StopDelivery {
+  /** The request facts built by the CLI (commands/stop.ts, commands/restart.ts). */
+  provenance: DaemonStopDraft;
+  /** Whether the stop is about to go through `systemctl` or a raw signal. */
+  via: "systemctl" | "signal";
+  /** The daemon pid being stopped, when one was known. */
+  pid?: number;
+}
+
+/** The injected recorder invoked immediately before a stop/restart is signalled. */
+export type StopDeliveryFn = (stop: StopDelivery) => void;
+
+/**
+ * The honest provenance for a daemon that received a stop with no mediated
+ * request anywhere: unattributed by construction — Linux exposes no sender
+ * identity for a signal, so the record must say "unattributed" rather than
+ * guess one — plus what the receiving process actually knows: its own pid,
+ * the moment (stamped by the store), the runtime directory, and the projects
+ * it serves with their live-run counts.
+ *
+ * Storage belongs at the caller: the daemon's SIGINT/SIGTERM path writes the
+ * returned draft through the store before/while draining. This builds the
+ * facts, store-free, so a raw `kill`/out-of-band `systemctl stop` — no
+ * conductor CLI in the delivery path at all — still leaves a durable row the
+ * next `omp-conductor status` can show.
+ */
+export function externalStopProvenance(o: {
+  /** The daemon pid that received the signal, when known. */
+  daemonPid?: number;
+  /** The daemon's runtime directory (host paths only — never secrets). */
+  runtimeDir: string;
+  /** Every served project with its live-run count at signal time. */
+  affected: { project: string; live: number }[];
+  reason?: string;
+}): DaemonStopDraft {
+  return {
+    controlPath: "external signal",
+    scope: "global",
+    ...(o.daemonPid === undefined ? {} : { daemonPid: o.daemonPid }),
+    runtimeDir: o.runtimeDir,
+    affected: o.affected,
+    reason: o.reason ?? "external signal — no mediated stop request was recorded",
+    unattributed: true,
+  };
+}
+
 /**
  * How the last stop actually landed. Callers print this so an operator can
  * tell a supervised stop from a bare SIGTERM without reading the journal.
@@ -510,7 +566,35 @@ export interface RestartResult {
  * a stopped unit). The grace period is a deadline, not a clean drain: a tick
  * with a worker in flight can run for that worker's whole wall clock.
  */
-export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopResult> {
+export async function stopDaemon(
+  o: {
+    timeoutMs?: number;
+    /**
+     * The request facts for this stop, when a mediated caller carries them.
+     * With `record`, the durable row is written immediately before the signal
+     * is sent — the exact ordering "provenance precedes signalling" refers to
+     * — and only when a stop actually lands: a request that finds no daemon
+     * stops nothing and records nothing. Drain-style callers whose restart may
+     * never execute additionally record the request at entry themselves.
+     */
+    provenance?: DaemonStopDraft;
+    /** Invoked just before the daemon is signalled, with the delivery method. */
+    record?: StopDeliveryFn;
+  } = {},
+): Promise<StopResult> {
+  const recordStop = (via: "systemctl" | "signal", pid: number | undefined): void => {
+    if (o.provenance === undefined || o.record === undefined) return;
+    o.record({
+      provenance: {
+        ...o.provenance,
+        controlPath: `${o.provenance.controlPath} via ${via}`,
+        ...(pid === undefined ? {} : { daemonPid: pid }),
+      },
+      via,
+      pid,
+    });
+  };
+
   const rec = livingDaemon();
   if (rec === undefined) {
     // `livingDaemon` already cleared a stale file; this covers the unparseable
@@ -521,6 +605,7 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
       throw new Error(ownershipUnknown("stop", decision.reason));
     }
     if (decision.kind === "stop") {
+      recordStop("systemctl", decision.mainPid);
       await runSystemdStop(decision.mainPid, o.timeoutMs);
       clearRecord();
       return { kind: "stopped", pid: decision.mainPid, via: "systemctl" };
@@ -536,6 +621,7 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
     throw new Error(ownershipUnknown("stop", decision.reason));
   }
   if (decision.kind === "stop") {
+    recordStop("systemctl", rec.pid);
     await runSystemdStop(rec.pid, o.timeoutMs);
     clearRecord();
     return { kind: "stopped", pid: rec.pid, via: "systemctl" };
@@ -544,6 +630,7 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
   // decision.kind === "not-ours": confirmed no unit, inactive unit, no systemd
   // binary, or a unit whose MainPID is somebody else. Only a *confirmed*
   // negative is safe to signal.
+  recordStop("signal", rec.pid);
   const gone = await terminate(rec.pid, o.timeoutMs ?? STOP_TIMEOUT_MS);
   if (!gone) {
     // The record stays: something is still holding that pid, and forgetting
@@ -577,8 +664,29 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
  * Returns the record of the process that is now answering `/healthz`.
  */
 export async function restartDaemon(
-  o: { port?: number; project?: string; timeoutMs?: number } = {},
+  o: {
+    port?: number;
+    project?: string;
+    timeoutMs?: number;
+    /** Request facts and recorder, same semantics as {@link stopDaemon}: the
+     *  durable row is written immediately before the restarting signal. */
+    provenance?: DaemonStopDraft;
+    record?: StopDeliveryFn;
+  } = {},
 ): Promise<RestartResult> {
+  const recordStop = (via: "systemctl" | "signal", pid: number | undefined): void => {
+    if (o.provenance === undefined || o.record === undefined) return;
+    o.record({
+      provenance: {
+        ...o.provenance,
+        controlPath: `${o.provenance.controlPath} via ${via}`,
+        ...(pid === undefined ? {} : { daemonPid: pid }),
+      },
+      via,
+      pid,
+    });
+  };
+
   const previous = livingDaemon();
   const ownership = probeUnit();
   if (ownership.kind === "unknown") {
@@ -591,6 +699,7 @@ export async function restartDaemon(
     // startDaemon() — that leaves the unit failed while handing the operator
     // a healthy-looking but unmanaged pid (the 12:17Z incident in #376).
     // Any manager refusal is terminal; so is unproven ownership afterwards.
+    recordStop("systemctl", previous?.pid);
     const record = await restoreFailedUnit(o.timeoutMs, o.project);
     return { previous, record, via: "systemctl" };
   }
@@ -602,6 +711,7 @@ export async function restartDaemon(
     // Ownership is proven. A refused/timed-out restart must not fall through
     // to stopDaemon's signal path — that is the exact bounce this module exists
     // to prevent (SIGTERM → exit 143 → Restart=on-failure → new MainPID).
+    recordStop("systemctl", ownership.pid);
     const ran = systemctl(["restart", SYSTEMD_UNIT]);
     if (!ran.ok) {
       throw new Error(systemctlFailure("restart", ran));
@@ -615,6 +725,7 @@ export async function restartDaemon(
 
   // Confirmed unmanaged: no unit, an inactive unit, or a unit whose MainPID
   // is somebody else. The detached CLI daemon is the only path left.
+  recordStop("signal", previous?.pid);
   await stopDaemon({ timeoutMs: o.timeoutMs });
   const record = await startDaemon({ port: o.port ?? previous?.port, project: o.project ?? previous?.project });
   return { previous, record, via: "cli" };

package/src/omp.ts

@@ -44,6 +44,14 @@ export interface AgentSessionLike {
    * `"*"` for every event. The payload is the harness's own event union, which
    * this package cannot name without the peer dependency, so it arrives as
    * `unknown` and each caller narrows the two or three fields it reads.
+   *
+   * One event is not the harness's at all: `"session_exit"` fires when the
+   * underlying session *process* has terminated, carrying
+   * `{ type: "session_exit", code?: number | null }`. It is the single real
+   * terminal signal — a crashed or killed session is never confused with one
+   * that merely stopped streaming (`"agent_end"`). A supervisor may receive it
+   * after its own `dispose()`, and must decide what an exit means from its own
+   * state rather than assuming every exit is a crash.
    */
   on(event: string, cb: (e: unknown) => void): void;
   abort(): void;
@@ -714,8 +722,24 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     pending.clear();
   };
 
+  // The one terminal event this proxy owns outright: the session process is
+  // gone, whether by crash, kill, or a clean dispose of its own. Delivered to
+  // subscribers *before* any failure is surfaced, so a supervisor learning of
+  // the death can also read its exit code off the same event. `disposing` is
+  // the proxy's own intent (its disposer asked the child to stop), not the
+  // subscriber's, so the event is emitted in both branches and each observer
+  // decides what an exit means from its own state.
+  const emitSessionExit = (code: number | null): void => {
+    const type = "session_exit";
+    const event = { type, code };
+    for (const cb of handlers.get(type) ?? []) cb(event);
+    for (const cb of handlers.get("*") ?? []) cb(event);
+  };
+
   void child.exited.then(async (code) => {
     onExit();
+    const exitCode = typeof code === "number" ? code : null;
+    emitSessionExit(exitCode);
     // A child that cannot start writes `start-error` over the socket, not the
     // pipes — and its exit can be dispatched before the accept of a connection
     // that already completed in the kernel. Let the socket settle before the