Skip to content
Python
115 KB
Raw Blame
#!/usr/bin/env node
import { spawn } from "node:child_process";
/**
 * macOS install / service / upgrade / rollback / uninstall lifecycle harness.
 *
 * C7 owner. Everything runs against a caller-supplied runtime distribution in a
 * throwaway HOME, install root and data dir. It never touches the daily
 * `~/.one-memory`, `~/Library/Application Support/One Memory`, or the canonical
 * LaunchAgent, so it is safe to run while a real install is live.
 *
 * The user-level LaunchAgent label is scoped to the install root (C7
 * `734ca43`): the daily root keeps `com.tencent.onememory.runtime`, any other
 * root gets `<canonical>.<sha256(root) | 16>`. This harness asserts that the
 * scoped label is what actually loads, that a reinstall is idempotent instead
 * of a second bootstrap, and that uninstall never removes data.
 *
 * Usage:
 *   node scripts/platform/macos/service-lifecycle.mjs \
 *     --dist <runtime-dist dir> [--cli <one-memory.cjs>] [--app <MemHub.app>]
 *     [--work <dir>] [--json]
 *
 * `--cli` drives a CLI build of this checkout against the given payload, so the
 * harness can validate an unfrozen fix without waiting for a new hourly package.
 * Without it, the CLI bundled in the distribution is used.
 *
 * `--app` additionally asserts the App bundle embeds the same Runtime as the
 * standalone distribution (the same-origin Runtime hash requirement).
 *
 * Exit codes: 0 pass, 4 a check failed, 2 the harness could not tell.
 */
import { createHash } from "node:crypto";
import {
  cp,
  lstat,
  mkdir,
  mkdtemp,
  readdir,
  readFile,
  readlink,
  realpath,
  rm,
  stat,
  writeFile,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";

const CANONICAL_LABEL = "com.tencent.onememory.runtime";
const REQUIRED_FILES = [
  "bin/node",
  "bin/one-memory",
  "bin/one-memory.cjs",
  "core/one-memory",
  "runtime/runtime.cjs",
  "host-bridge/mcp.cjs",
  "host-bridge/recall-cli.cjs",
  "host-bridge/sync-hook/manifest.json",
];

function parse(argv) {
  const values = new Map();
  for (let index = 0; index < argv.length; index += 2) {
    const name = (argv[index] ?? "").replace(/^--/, "");
    const value = argv[index + 1];
    if (!name) return null;
    if (name === "json") {
      values.set("json", "1");
      index -= 1;
      continue;
    }
    if (!value || value.startsWith("--")) return null;
    values.set(name, value);
  }
  if (!values.get("dist")) return null;
  return {
    dist: path.resolve(values.get("dist")),
    cli: values.get("cli") ? path.resolve(values.get("cli")) : null,
    app: values.get("app") ? path.resolve(values.get("app")) : null,
    work: values.get("work") ? path.resolve(values.get("work")) : null,
    json: values.get("json") === "1",
  };
}

/** Run a command with an optional timeout and optional stdin.
 *
 * `extra` carries `env`/`cwd` straight to spawn; `input` (written to stdin then
 * closed) and `timeoutMs` (kill + report `timedOut`) are handled here so a
 * hung child is a recorded outcome rather than a hung harness.
 */
function run(command, args, extra = {}) {
  return new Promise((resolve) => {
    const { input, timeoutMs, ...spawnOptions } = extra;
    const child = spawn(command, args, {
      stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
      ...spawnOptions,
    });
    let stdout = "";
    let stderr = "";
    let timedOut = false;
    let timer = null;
    child.stdout.on("data", (chunk) => (stdout += chunk));
    child.stderr.on("data", (chunk) => (stderr += chunk));
    if (input !== undefined && child.stdin) {
      child.stdin.end(input);
    }
    if (typeof timeoutMs === "number" && timeoutMs > 0) {
      timer = setTimeout(() => {
        timedOut = true;
        child.kill("SIGKILL");
      }, timeoutMs);
    }
    child.once("error", (error) =>
      resolve({
        code: null,
        stdout,
        stderr: String(error.message ?? error),
        timedOut,
      }),
    );
    child.once("close", (code) => {
      if (timer !== null) clearTimeout(timer);
      resolve({ code, stdout, stderr, timedOut });
    });
  });
}

function check(name, result, evidence) {
  return { name, result, evidence };
}

/** A check that only makes sense once the install step succeeded.
 *
 * When install did not complete (e.g. the load-sensitive Core cold start), the
 * dependent checks are not evaluated and are reported as `unknown` with that
 * reason, instead of a cascade of `fail`s that would look like thirteen product
 * defects. The install failure itself is already recorded separately.
 */
function depCheck(installOk, name, result, evidence) {
  if (!installOk) {
    return check(
      name,
      "unknown",
      "install step did not complete; not evaluated",
    );
  }
  return check(name, result, evidence);
}

/** The label the product derives for this install path.
 *
 * `runtimeInstallLayout` first normalizes any caller spelling to the `current`
 * link (C7 `7b95b68`): `install` passes `<root>`, `uninstall`/`upgrade` pass
 * `<root>/current`, and both must land on one label. `serviceLabelFor` then
 * hashes the normalized path (C7 `734ca43`). So this mirrors the product by
 * appending `current` when absent, never by dropping it.
 *
 * The daily root keeps the canonical label. That root is derived from the login
 * home (`defaultManagedInstallRoot`), which the hash rule does not otherwise
 * know, so the caller passes it in; the check is against the daily root itself
 * and against its `current` link.
 */
function scopedLabel(platform, installRoot, dailyRoot = null) {
  const resolved = path.resolve(installRoot);
  const normalized =
    path.basename(resolved) === "current"
      ? resolved
      : path.join(resolved, "current");
  if (dailyRoot !== null) {
    const daily = path.resolve(dailyRoot);
    if (normalized === path.join(daily, "current")) return CANONICAL_LABEL;
  }
  const digest = createHash("sha256")
    .update(`one-memory-service-root\0${platform}\0${normalized}`)
    .digest("hex")
    .slice(0, 16);
  return `${CANONICAL_LABEL}.${digest}`;
}

/** SHA-256 of one file, used to re-key a fixture manifest after a controlled
 * payload mutation so the only variable under test is the payload itself. */
async function sha256File(file) {
  const { createReadStream } = await import("node:fs");
  const digest = createHash("sha256");
  for await (const chunk of createReadStream(file)) digest.update(chunk);
  return digest.digest("hex");
}

/** Ask the product itself which label it will register for this install path.
 *
 * `service-plan` is read-only (no filesystem or launchd writes), so it is safe
 * to call before installing. Deriving the label from the product instead of
 * re-hashing the path here keeps the harness correct no matter how the label
 * rule evolves, and makes a product/harness disagreement show up as evidence
 * rather than as a mysterious "plist missing". Returns null when the product
 * cannot answer.
 */
async function plannedServiceId(cliPath, home, dataDir, installRoot) {
  const result = await cli(home, dataDir, cliPath, [
    "service-plan",
    "--install-root",
    installRoot,
    "--home",
    home,
    "--data-dir",
    dataDir,
  ]);
  try {
    const parsed = JSON.parse(result.stdout);
    return typeof parsed?.service_id === "string" && parsed.service_id
      ? parsed.service_id
      : null;
  } catch {
    return null;
  }
}

/** Compare the Runtime an App bundle embeds against the standalone distribution.
 *
 * Path mapping matters and is not symmetric:
 *   - core/runtime/host-bridge/web are directories with the same name on both sides;
 *   - the CLI is a *directory* (`cli/`) in the App bundle but a single file
 *     (`bin/one-memory.cjs`) in the distribution. Comparing `dist/cli` (which
 *     does not exist) reported `dist=missing app=present` on a correct bundle --
 *     a false failure that also made the check easy to dismiss.
 *
 * Same-origin Runtime is a hard requirement: App and CLI must consume one
 * artifact, so an App-only rebuild cannot silently drift.
 */
async function sameOriginRuntimeChecks(distDir, appPath) {
  const appResources = path.join(appPath, "Contents", "Resources");
  const { treeManifest } = await import(
    path.join(
      path.dirname(fileURLToPath(import.meta.url)),
      "..",
      "..",
      "packaged_resource_manifest.cjs",
    )
  );
  const { createHash } = await import("node:crypto");
  const { createReadStream } = await import("node:fs");
  const fileDigest = async (file) => {
    const hash = createHash("sha256");
    for await (const chunk of createReadStream(file)) hash.update(chunk);
    return hash.digest("hex");
  };
  const pairs = [
    { name: "core", dist: path.join(distDir, "core"), app: "core" },
    { name: "runtime", dist: path.join(distDir, "runtime"), app: "runtime" },
    {
      name: "host-bridge",
      dist: path.join(distDir, "host-bridge"),
      app: "host-bridge",
    },
    { name: "web", dist: path.join(distDir, "web"), app: "web" },
    // The CLI: distribution ships one file, the App receives a directory.
    {
      name: "cli",
      dist: path.join(distDir, "bin", "one-memory.cjs"),
      app: "cli",
    },
  ];
  const results = [];
  for (const pair of pairs) {
    if (pair.name === "cli") {
      const appCli = path.join(appResources, "cli", "one-memory.cjs");
      const distHash = await fileDigest(pair.dist).catch(() => null);
      const appHash = await fileDigest(appCli).catch(() => null);
      const same = distHash !== null && distHash === appHash;
      results.push(
        check(
          "app_embeds_same_cli_as_distribution",
          same ? "pass" : "fail",
          same
            ? "bin/one-memory.cjs identical to Resources/cli/one-memory.cjs"
            : `dist=${distHash === null ? "missing" : "present"} app=${
                appHash === null ? "missing" : "present"
              }`,
        ),
      );
      continue;
    }
    const distHash = await treeManifest(pair.dist).catch(() => null);
    const appHash = await treeManifest(path.join(appResources, pair.app)).catch(
      () => null,
    );
    const same =
      distHash !== null &&
      appHash !== null &&
      JSON.stringify(distHash) === JSON.stringify(appHash);
    results.push(
      check(
        `app_embeds_same_${pair.name}_as_distribution`,
        same ? "pass" : "fail",
        same
          ? `${Object.keys(distHash).length} entries identical`
          : `dist=${distHash === null ? "missing" : "present"} app=${
              appHash === null ? "missing" : "present"
            }`,
      ),
    );
  }
  return results;
}

/** Checks that only make sense against a real packaged App bundle.
 *
 * These cover the packaging-level obligations that an install-root CLI test
 * cannot see: the bundle must not ship a second login registration, and a
 * signed bundle's hardened-runtime status must be reported honestly.
 */
async function appBundleChecks(appPath) {
  const results = [];
  const contents = path.join(appPath, "Contents");

  // 1. No RunAtLoad login agent shipped inside the bundle.
  //
  //    Scope note, per C6 App's correction: launchd does NOT scan
  //    `Contents/Library/LaunchAgents` (it scans ~/Library/LaunchAgents,
  //    /Library/LaunchAgents, /System/Library/LaunchAgents). Such a plist only
  //    takes effect if some code explicitly registers it via
  //    SMAppService.agent / setLoginItemSettings({type:"agentService"}). The
  //    current repo has no such call, so this is a latent second-registration
  //    path, not live behavior. It still violates the contract clause
  //    "不能两份同时注册" and contradicts login-item.ts's own comment, so the
  //    bundle must not ship it. This check asserts the bundle fact only -- it
  //    does not claim launchd loads it.
  const agentsDir = path.join(contents, "Library", "LaunchAgents");
  const agentEntries = await readdir(agentsDir).catch(() => []);
  const runAtLoadAgents = [];
  for (const entry of agentEntries) {
    if (!entry.endsWith(".plist")) continue;
    const raw = await readFile(path.join(agentsDir, entry), "utf8").catch(
      () => "",
    );
    if (/<key>RunAtLoad<\/key>\s*<true\s*\/>/.test(raw)) {
      runAtLoadAgents.push(entry);
    }
  }
  results.push(
    check(
      "app_bundle_ships_no_run_at_load_login_agent",
      runAtLoadAgents.length === 0 ? "pass" : "fail",
      runAtLoadAgents.length === 0
        ? agentEntries.length === 0
          ? "no bundled LaunchAgents"
          : `${agentEntries.length} bundled plist(s), none RunAtLoad`
        : `RunAtLoad login agent(s) bundled: ${runAtLoadAgents.join(", ")}`,
    ),
  );

  // 2. Report the code-signing facts the public gate depends on, without
  //    pretending an ad-hoc internal build is a public release. `spctl`
  //    rejecting an ad-hoc bundle is expected, so it is evidence, not a fail.
  const signature = await run("codesign", ["-d", "--verbose=4", appPath]);
  const signatureText = `${signature.stdout}${signature.stderr}`;
  const hardened = /flags=0x[0-9a-f]*\([^)]*runtime[^)]*\)/.test(signatureText);
  const adhoc = /Signature=adhoc/.test(signatureText);
  results.push(
    check(
      "app_bundle_reports_its_signing_state_honestly",
      hardened ? "pass" : "unknown",
      hardened
        ? `hardened runtime enabled${adhoc ? " (ad-hoc signed: internal package, not a public release)" : ""}`
        : "hardened runtime not enabled on this bundle; the public gate requires it",
    ),
  );
  return results;
}

/**
 * Public-release gate report for a packaged App, kept separate from the internal
 * hourly matrix. It states each public requirement as pass/fail/unknown with the
 * command that produced it, so "not yet verified" cannot be read as "supported".
 *
 * Usage:
 *   node scripts/platform/macos/service-lifecycle.mjs --dist <dist> --app <App>
 *   # then read the app_bundle_* checks; spctl/notarization need real creds.
 */
async function publicGateReport(appPath) {
  const codesign = await run("codesign", [
    "--verify",
    "--deep",
    "--strict",
    appPath,
  ]);
  const spctl = await run("spctl", ["-a", "-vvv", "-t", "exec", appPath]);
  const stapler = await run("xcrun", ["stapler", "validate", appPath]);
  const signature = await run("codesign", ["-d", "--verbose=4", appPath]);
  const version = await run("/usr/libexec/PlistBuddy", [
    "-c",
    "Print :CFBundleShortVersionString",
    path.join(appPath, "Contents", "Info.plist"),
  ]);
  // `codesign --verify` can pass even when hardened runtime library validation
  // prevents Electron from loading its own signed Framework. Desktop's
  // side-effect-free `--version` path runs before lifecycle startup, so this
  // exercises the real App executable/framework without windows, Runtime or
  // service registration.
  const launch = await run(
    path.join(appPath, "Contents", "MacOS", "MemHub"),
    ["--memhub-version"],
    { timeoutMs: 30_000 },
  );
  const expectedVersionOutput = `MemHub ${version.stdout.trim()}`;
  const signatureText = `${signature.stdout}${signature.stderr}`;
  const hardened = /flags=0x[0-9a-f]*\([^)]*runtime[^)]*\)/.test(signatureText);
  const adhoc = /Signature=adhoc/.test(signatureText);
  return [
    check(
      "public_gate_codesign_verify",
      codesign.code === 0 ? "pass" : "fail",
      `codesign --verify --deep --strict exit ${codesign.code}`,
    ),
    check(
      "public_gate_hardened_runtime",
      hardened ? "pass" : "fail",
      hardened
        ? "runtime flag present after signing"
        : "no hardened-runtime flag; pass --options runtime at signing time",
    ),
    check(
      "public_gate_developer_id_signature",
      adhoc ? "fail" : signature.code === 0 ? "pass" : "unknown",
      adhoc
        ? "ad-hoc signature: internal package only, not a public release"
        : `codesign -d exit ${signature.code}`,
    ),
    check(
      "public_gate_gatekeeper_accepts",
      spctl.code === 0 ? "pass" : "fail",
      spctl.code === 0
        ? "spctl accepted"
        : `spctl rejected: ${`${spctl.stdout}${spctl.stderr}`.trim().split(/\n/)[0] || "no reason"}`,
    ),
    check(
      "public_gate_notarization_ticket",
      stapler.code === 0 ? "pass" : "fail",
      stapler.code === 0
        ? "notarization ticket stapled"
        : `no stapled ticket: ${`${stapler.stdout}${stapler.stderr}`.trim().split(/\n/).pop() || "n/a"}`,
    ),
    check(
      "public_gate_hardened_bundle_still_launches",
      launch.code === 0 &&
        !launch.timedOut &&
        version.code === 0 &&
        launch.stdout.trim() === expectedVersionOutput
        ? "pass"
        : "fail",
      launch.code === 0 &&
        !launch.timedOut &&
        version.code === 0 &&
        launch.stdout.trim() === expectedVersionOutput
        ? `${expectedVersionOutput} exited 0`
        : `MemHub --memhub-version exit=${launch.code} timedOut=${launch.timedOut === true} stdout=${launch.stdout.trim() || "<empty>"} expected=${expectedVersionOutput}`,
    ),
  ];
}

/** launchd prints "<domain>/<label> = {" when a job is loaded; exit 113 means
 * absent. A 0 exit with no matching banner is not "registered". */
async function launchctlPrint(label) {
  const result = await run("launchctl", [
    "print",
    `gui/${process.getuid()}/${label}`,
  ]);
  const banner = `gui/${process.getuid()}/${label} = {`;
  const registered =
    result.code === 0 &&
    result.stdout
      .split(/\r?\n/)
      .some((line) => line.trimStart().startsWith(banner));
  return { ...result, registered };
}

/** The exact `program` + `arguments` launchd reports for a loaded job.
 *  Returns null when the job is not loaded or the block cannot be parsed. */
function parseLaunchctlJobCommand(stdout) {
  const lines = stdout.split(/\r?\n/);
  let program = null;
  const args = [];
  let inArgs = false;
  for (const line of lines) {
    const trimmed = line.trim();
    const programMatch = trimmed.match(/^program = (.+)$/);
    if (programMatch) {
      program = programMatch[1].trim();
      continue;
    }
    if (trimmed === "arguments = {") {
      inArgs = true;
      continue;
    }
    if (inArgs) {
      if (trimmed === "}") {
        inArgs = false;
        continue;
      }
      args.push(trimmed);
    }
  }
  if (program === null) return null;
  return { program, args };
}

async function exists(target) {
  try {
    await stat(target);
    return true;
  } catch {
    return false;
  }
}

/** Parse `ps -Ao pid=,ppid=,state=,command=` output into rows.
 *
 * Pure so it can be pinned by a test: the zombie/orphan verdict must not be
 * possible to weaken without a test going red (C8 showed that mutating the
 * filter to `[]` left the suite green when this was inline).
 */
function parsePsRows(stdout) {
  return stdout
    .split(/\r?\n/)
    .map((line) => line.trim())
    .filter(Boolean)
    .map((line) => {
      const match = line.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
      return match === null
        ? null
        : {
            pid: Number(match[1]),
            ppid: Number(match[2]),
            state: match[3],
            command: match[4],
          };
    })
    .filter((row) => row !== null);
}

/** Split ps rows into zombies and live processes still holding `installRoot`.
 *
 * A zombie (`Z`) has no argv -- `pgrep -fl` cannot see it, which is why this
 * judges the STATE field. A live process whose command mentions the removed
 * root is an orphan that outlived uninstall. Both must be empty to pass.
 */
function judgeLeftovers(rows, installRoot, ownedPids = null) {
  const zombies = rows.filter(
    (row) =>
      row.state.startsWith("Z") &&
      (ownedPids === null || ownedPids.has(row.pid)),
  );
  const liveLeftovers = rows.filter(
    (row) => !row.state.startsWith("Z") && row.command.includes(installRoot),
  );
  return { zombies, liveLeftovers };
}

/** Verdict for "App and CLI share one launchd-owned daemon".
 *
 * Pure so it can be pinned: the CLI-observation half used to be a bare "pass"
 * with the observation only in the evidence text, so weakening it could not fail
 * any check (C8's class of finding). Rules:
 *   - the job moved / vanished between samples -> "unknown" (restart/teardown);
 *   - same job and CLI sees it running -> "pass";
 *   - same job, CLI does NOT see it, but the runtime was healthy earlier -> "fail"
 *     (a real App/CLI disagreement);
 *   - same job, CLI does not see it, health was never established -> "unknown".
 */
function sharedDaemonVerdict({ sameJob, cliSeesRunning, healthy }) {
  if (!sameJob) return "unknown";
  if (cliSeesRunning) return "pass";
  return healthy ? "fail" : "unknown";
}

async function missing(target) {
  try {
    await lstat(target);
    return false;
  } catch {
    return true;
  }
}

function parseJson(text, label, checks) {
  try {
    return JSON.parse(text);
  } catch {
    checks.push(check(`${label}_json`, "fail", text.slice(0, 200)));
    return null;
  }
}

async function cli(home, dataDir, cliPath, args, extraEnv = {}) {
  // The packaged entrypoint is a shell launcher; a checkout override is a
  // CommonJS file, so it is driven through the running Node binary.
  const [command, commandArgs] = cliPath.endsWith(".cjs")
    ? [process.execPath, [cliPath, ...args]]
    : [cliPath, args];
  return run(command, commandArgs, {
    env: {
      PATH: `${path.dirname(process.execPath)}:/usr/bin:/bin`,
      HOME: home,
      ONE_MEMORY_DATA_DIR: dataDir,
      NO_COLOR: "1",
      ...extraEnv,
    },
  });
}

/** Poll the product's own status until the runtime is verifiably healthy.
 *
 * Core cold start is load-sensitive on this Mac (measured 1-15s under load
 * averages of 40-60); the Runtime's own start budget can expire while the
 * machine is saturated even though nothing is wrong with the install. So a
 * still-stopped runtime after this bounded wait is reported as unknown with the
 * load average as evidence, never as a product failure.
 */
async function waitForHealthy(home, dataDir, cliPath, budgetMs = 90_000) {
  const deadline = Date.now() + budgetMs;
  let last = null;
  while (Date.now() < deadline) {
    const result = await cli(home, dataDir, cliPath, ["status", "--json"]);
    try {
      last = JSON.parse(result.stdout);
    } catch {
      last = null;
    }
    const state = last?.runtime?.state ?? last?.state;
    if (state === "running" || last?.health?.state === "healthy") return last;
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  return last;
}

/** The one PID launchd reports as the running job, or null when not loaded. */
async function loadedPid(label) {
  const result = await run("launchctl", [
    "print",
    `gui/${process.getuid()}/${label}`,
  ]);
  if (result.code !== 0) return null;
  const match = result.stdout.match(/^\s*pid = (\d+)\s*$/m);
  return match ? Number(match[1]) : null;
}

async function processStillReferences(pid, installRoot) {
  const result = await run("ps", ["-o", "state=,command=", "-p", String(pid)]);
  const row = result.stdout.trim();
  return row !== "" && !row.startsWith("Z") && row.includes(installRoot);
}

/** Every scoped LaunchAgent whose program lives inside `work`.
 *
 * The lifecycle suite installs and uninstalls the same label several times. A
 * step that re-installs after an uninstall (the foreign-PATH and nested-data
 * probes both do) leaves the service registered again, and a single
 * `labelRegistered` flag sampled earlier is then stale: the final `bootout`
 * skips it, `KeepAlive` restarts the Runtime, `safeRemoveWork` reports
 * `service-still-registered`, and the throwaway tree plus a live daemon outlive
 * the run. Observed on 2026-09-30: a 3.5G `--work` tree and a `running` scoped
 * label with `ppid=1` after an otherwise 70/0 matrix, plus three such labels
 * accumulated on the machine from earlier runs (that is why the finalizer must
 * enumerate from launchd per run rather than trust a flag captured mid-run).
 * So enumerate the labels from launchd itself and decide per label from the
 * program it actually runs,
 * rather than trusting a flag captured mid-run.
 */
async function scopedLabelsUnderWork(work) {
  const realWork = await realpath(work).catch(() => null);
  if (realWork === null) return [];
  // `launchctl list` is the loaded-job table; `print-disabled` only reports
  // labels that carry an override entry, so a scoped label that was never
  // disabled/enabled would be invisible there.
  const listed = await run("launchctl", ["list"]);
  const candidates = new Set();
  for (const line of listed.stdout.split(/\r?\n/)) {
    // "<pid|->\t<status>\t<label>"
    const columns = line.split("\t");
    const listedLabel = columns[columns.length - 1]?.trim();
    if (
      columns.length >= 3 &&
      typeof listedLabel === "string" &&
      listedLabel.startsWith(`${CANONICAL_LABEL}.`)
    ) {
      candidates.add(listedLabel);
    }
  }
  const scoped = [];
  for (const candidate of candidates) {
    if (candidate === CANONICAL_LABEL) continue;
    const printed = await launchctlPrint(candidate);
    if (!printed.registered) continue;
    const command = parseLaunchctlJobCommand(printed.stdout);
    const entry = command?.program ?? null;
    if (entry === null) continue;
    const realEntry = await realpath(entry).catch(() => null);
    const root = realEntry ?? path.resolve(entry);
    if (root === realWork || root.startsWith(`${realWork}${path.sep}`)) {
      scoped.push(candidate);
    }
  }
  return scoped;
}

/** POSIX mode of a path as an octal string, or null when it is missing. */
async function fileMode(target) {
  try {
    const info = await lstat(target);
    return (info.mode & 0o777).toString(8).padStart(3, "0");
  } catch {
    return null;
  }
}

/** Remove this run's throwaway work directory, but only when provably safe.
 *
 * Mirrors the four protections the hourly cleanup protocol requires: the path
 * is a real directory under the temp root, is not a symlink, its service is no
 * longer registered, and no process still references it. If any protection
 * fails the tree is left in place and the reason is reported, because deleting
 * a directory a live process still uses is exactly the C8-flagged defect.
 */
/**
 * True when `target` sits under a temp root. macOS gives the same directory two
 * names (`/tmp` and `/private/tmp`, `/var/folders/.../T`), and `os.tmpdir()` is
 * not reconciled with the one the caller actually used, so compare against the
 * resolved forms of both `TMPDIR` and the platform temp root.
 */
async function isUnderAnyTempRoot(target) {
  const candidates = [
    os.tmpdir(),
    process.env.TMPDIR,
    "/tmp",
    "/var/tmp",
    "/private/tmp",
  ].filter((value) => typeof value === "string" && value.length > 0);
  const roots = await Promise.all(
    candidates.map((value) => realpath(value).catch(() => null)),
  );
  return roots.some(
    (root) =>
      root !== null &&
      (target === root || target.startsWith(`${root}${path.sep}`)),
  );
}

async function safeRemoveWork(work, label, labelRegistered) {
  const info = await lstat(work).catch(() => null);
  if (info === null) return { removed: false, reason: "already-gone" };
  if (!info.isDirectory() || info.isSymbolicLink()) {
    return { removed: false, reason: "not-a-real-directory" };
  }
  const realWork = await realpath(work).catch(() => null);
  if (realWork === null || !(await isUnderAnyTempRoot(realWork))) {
    return { removed: false, reason: "escapes-temp-root" };
  }
  if (labelRegistered || (await launchctlPrint(label)).registered) {
    return { removed: false, reason: "service-still-registered" };
  }
  // The scoped label is not the only job this run can create: the nested-data
  // probe installs a second scoped label derived from a different root. Both
  // point their program into `work`, so refuse to delete while either is loaded.
  const stillLoaded = await scopedLabelsUnderWork(work);
  if (stillLoaded.length > 0) {
    return {
      removed: false,
      reason: `service-still-registered:${stillLoaded.join(",")}`,
    };
  }
  const holders = await run("pgrep", ["-fl", work]);
  const holders0 = holders.stdout
    .split(/\r?\n/)
    .map((line) => line.trim())
    .filter(Boolean);
  if (holders0.length > 0) {
    return { removed: false, reason: `live-process:${holders0.length}` };
  }
  await rm(work, { recursive: true, force: true });
  return { removed: true, reason: "cleaned" };
}

async function main() {
  const config = parse(process.argv.slice(2));
  if (!config) {
    process.stderr.write(
      "Usage: service-lifecycle.mjs --dist <runtime-dist dir> [--work <dir>] [--json]\n",
    );
    return 2;
  }
  if (process.platform !== "darwin") {
    process.stderr.write(
      "macOS service lifecycle is darwin only; other platforms stay unverified\n",
    );
    return 2;
  }

  const checks = [];
  const work =
    config.work ?? (await mkdtemp(path.join(os.tmpdir(), "om-c7-lifecycle-")));
  const ownedWork = config.work === null;
  const home = path.join(work, "home");
  const installRoot = path.join(home, ".local", "share", "one-memory");
  const currentRoot = path.join(installRoot, "current");
  const dataDir = path.join(work, "data");
  const binDir = path.join(work, "bin");
  const cliPath = config.cli ?? path.join(config.dist, "bin", "one-memory");
  const dailyRoot = path.join(
    home,
    "Library",
    "Application Support",
    "One Memory",
  );
  // Prefer the product's own answer; fall back to the mirrored hash only if the
  // product cannot produce a plan (which would itself be a finding).
  const plannedCurrent = await plannedServiceId(
    cliPath,
    home,
    dataDir,
    path.join(installRoot, "current"),
  );
  const plannedRoot = await plannedServiceId(
    cliPath,
    home,
    dataDir,
    installRoot,
  );
  const label =
    plannedCurrent ??
    scopedLabel("darwin", path.join(installRoot, "current"), dailyRoot);
  let labelRegistered = false;
  let installSucceeded = true;
  let cleanup = null;
  let overrideNote = null;

  try {
    // `mkdtemp` already made a caller-supplied path's parent, but a `--work`
    // path that does not exist yet must be created here: every subdirectory
    // below is a child of it, and the first check that writes into the run
    // (the user-data marker) would otherwise fail with ENOENT before any
    // product assertion ran -- indistinguishable, in the output, from a
    // product failure.
    await mkdir(work, { recursive: true, mode: 0o700 });
    await mkdir(home, { recursive: true, mode: 0o700 });
    await mkdir(binDir, { recursive: true, mode: 0o700 });

    // 0. Distribution shape: every required file exists, and the manifest
    //    declares this platform/arch. No source tree may masquerade as a build.
    for (const relative of REQUIRED_FILES) {
      const present = await exists(path.join(config.dist, relative));
      checks.push(
        check(
          `distribution_has_${relative.replaceAll("/", "_")}`,
          present ? "pass" : "fail",
          relative,
        ),
      );
    }
    const manifestRaw = await readFile(
      path.join(config.dist, "manifest.json"),
      "utf8",
    ).catch(() => null);
    const manifest = manifestRaw
      ? parseJson(manifestRaw, "manifest", checks)
      : null;
    checks.push(
      check(
        "manifest_declares_this_platform_and_arch",
        manifest?.platform === "darwin" && manifest?.arch === process.arch
          ? "pass"
          : "fail",
        manifest ? `${manifest.platform}/${manifest.arch}` : "missing",
      ),
    );
    // A manifest that claims a different architecture must be REFUSED, not
    // installed. This is the guard that stops an arm64 payload (or an
    // unbuilt/copied tree) from being presented as x64 support: the binary
    // inside is architecture-specific, so arch honesty has to be enforced at
    // install time, not inferred from the host CPU's translation ability.
    if (manifest !== null && manifestRaw !== null) {
      const foreignArch = manifest.arch === "arm64" ? "x64" : "arm64";
      const foreignRoot = path.join(work, "foreign-arch-dist");
      await cp(config.dist, foreignRoot, {
        recursive: true,
        dereference: false,
        verbatimSymlinks: true,
      });
      const foreignManifest = { ...manifest, arch: foreignArch };
      await writeFile(
        path.join(foreignRoot, "manifest.json"),
        `${JSON.stringify(foreignManifest, null, 2)}\n`,
      );
      const foreignInstall = await cli(home, dataDir, cliPath, [
        "install",
        "--source",
        foreignRoot,
        "--install-root",
        path.join(work, "foreign-arch-root"),
        "--bin-dir",
        path.join(work, "foreign-arch-bin"),
        "--data-dir",
        path.join(work, "foreign-arch-data"),
        "--yes",
      ]);
      const refused =
        foreignInstall.code !== 0 &&
        /distribution_target_mismatch/.test(
          `${foreignInstall.stdout}${foreignInstall.stderr}`,
        );
      // A distribution that is missing a file the manifest lists must be refused
      // WITHOUT leaving a partial install behind. The matrix already covers
      // content drift (hash mismatch); a *missing* file is the other half, and
      // the one where a careless implementation would happily copy what it found.
      {
        const incompleteRoot = path.join(work, "incomplete-dist");
        await cp(config.dist, incompleteRoot, {
          recursive: true,
          dereference: false,
          verbatimSymlinks: true,
        });
        // Delete a required runtime file the manifest still declares.
        await rm(path.join(incompleteRoot, "runtime", "runtime.cjs"), {
          force: true,
        });
        const incompleteRootTarget = path.join(work, "incomplete-install-root");
        const incomplete = await cli(home, dataDir, cliPath, [
          "install",
          "--source",
          incompleteRoot,
          "--install-root",
          incompleteRootTarget,
          "--bin-dir",
          path.join(work, "incomplete-bin"),
          "--data-dir",
          path.join(work, "incomplete-data"),
          "--yes",
        ]);
        const refused =
          incomplete.code !== 0 &&
          /distribution_manifest_incomplete/.test(
            `${incomplete.stdout}${incomplete.stderr}`,
          );
        const leftPartialCurrent = await exists(
          path.join(incompleteRootTarget, "current"),
        );
        checks.push(
          check(
            "an_incomplete_distribution_is_refused_without_a_partial_install",
            refused && !leftPartialCurrent ? "pass" : "fail",
            refused && !leftPartialCurrent
              ? `exit ${incomplete.code} with distribution_manifest_incomplete; no install root/current left`
              : `exit=${incomplete.code} refused=${refused} partialCurrent=${leftPartialCurrent}`,
          ),
        );
      }

      checks.push(
        check(
          "a_foreign_arch_manifest_is_refused",
          refused ? "pass" : "fail",
          refused
            ? `exit ${foreignInstall.code} with distribution_target_mismatch (claimed ${foreignArch})`
            : `exit ${foreignInstall.code} did not refuse a manifest claiming ${foreignArch}`,
        ),
      );
    }
    // The manifest string must be backed by the binaries it describes. Forge a
    // manifest that keeps the HOST arch (so the host-comparison guard is
    // satisfied) while a native payload actually carries a different slice.
    // Uses `lipo -thin` to write a real, differently-architected Mach-O, so the
    // check is about binary truth, not a corrupted file.
    if (manifest !== null) {
      const crossRoot = path.join(work, "cross-arch-binaries");
      await cp(config.dist, crossRoot, {
        recursive: true,
        dereference: false,
        verbatimSymlinks: true,
      });
      const otherArch = manifest.arch === "arm64" ? "x86_64" : "arm64";
      const thinned = await run("lipo", [
        "-thin",
        otherArch,
        "/usr/bin/true",
        "-output",
        path.join(crossRoot, "core", "one-memory"),
      ]).catch(() => null);
      if (thinned === null) {
        checks.push(
          check(
            "a_manifest_arch_not_backed_by_its_binaries_is_refused",
            "unknown",
            `lipo could not produce a ${otherArch} slice on this machine`,
          ),
        );
      } else {
        // Re-hash the replaced payload so only the architecture is "wrong";
        // a hash failure would prove nothing about the arch check.
        const crossManifest = { ...manifest, files: { ...manifest.files } };
        crossManifest.files["core/one-memory"] = await sha256File(
          path.join(crossRoot, "core", "one-memory"),
        );
        await writeFile(
          path.join(crossRoot, "manifest.json"),
          `${JSON.stringify(crossManifest, null, 2)}\n`,
        );
        const crossInstall = await cli(home, dataDir, cliPath, [
          "install",
          "--source",
          crossRoot,
          "--install-root",
          path.join(work, "cross-arch-root"),
          "--bin-dir",
          path.join(work, "cross-arch-bin"),
          "--data-dir",
          path.join(work, "cross-arch-data"),
          "--yes",
        ]);
        const crossRefused =
          crossInstall.code !== 0 &&
          /distribution_arch_mismatch/.test(
            `${crossInstall.stdout}${crossInstall.stderr}`,
          );
        checks.push(
          check(
            "a_manifest_arch_not_backed_by_its_binaries_is_refused",
            crossRefused ? "pass" : "fail",
            crossRefused
              ? `exit ${crossInstall.code} with distribution_arch_mismatch (manifest ${manifest.arch}, core ${otherArch})`
              : `exit ${crossInstall.code}: a ${otherArch} core was accepted for a manifest claiming ${manifest.arch}`,
          ),
        );
      }
    }
    // Same-origin Runtime: when an App bundle is supplied, the Runtime it embeds
    // must be byte-identical to the standalone distribution. App and CLI must
    // consume one artifact, so an App-only rebuild cannot silently drift.
    if (config.app !== null) {
      checks.push(
        ...(await sameOriginRuntimeChecks(config.dist, config.app)),
        ...(await appBundleChecks(config.app)),
      );
    }

    // 1. Fresh install writes current, the PATH link and the scoped service.
    // Before anything is written, both spellings of the install root must name
    // the same label. `install` passes `<root>/current` and `uninstall`/`upgrade`
    // pass `<root>`; if they disagreed, an install could not be found by its own
    // uninstall (the C7 `7b95b68` defect).
    checks.push(
      check(
        "root_and_current_spellings_share_one_label",
        plannedCurrent !== null && plannedCurrent === plannedRoot
          ? "pass"
          : "fail",
        plannedCurrent === null || plannedRoot === null
          ? `service-plan unavailable: current=${plannedCurrent ?? "null"} root=${plannedRoot ?? "null"}`
          : `current=${plannedCurrent} root=${plannedRoot}`,
      ),
    );
    // Snapshot the user's HOME before touching anything. The product must only
    // write inside the paths it was told to use; discovering a host directory
    // it was never pointed at would mean install silently touched host configs
    // (the goal's "login starts only the Runtime; it does not start hosts or
    // grant new permissions").
    const homeEntriesBefore = (await readdir(home)).sort();
    const install = await cli(home, dataDir, cliPath, [
      "install",
      "--source",
      config.dist,
      "--install-root",
      installRoot,
      "--bin-dir",
      binDir,
      "--data-dir",
      dataDir,
      "--yes",
    ]);
    // Only product-owned locations may appear in HOME. Anything else would be
    // a host config or unrelated file the installer was never asked to touch.
    const hostConfigDirs = [
      ".cursor",
      ".claude",
      ".codex",
      ".workbuddy",
      ".qwen",
      ".openclaw",
      ".hermes",
      ".pi",
    ];
    const homeEntriesAfter = (await readdir(home)).sort();
    const unexpectedHomeEntries = homeEntriesAfter.filter(
      (entry) =>
        !homeEntriesBefore.includes(entry) &&
        entry !== "Library" &&
        entry !== ".local",
    );
    const touchedHostConfig = hostConfigDirs.filter((dir) =>
      homeEntriesAfter.includes(dir),
    );
    checks.push(
      check(
        "install_writes_only_its_own_paths",
        unexpectedHomeEntries.length === 0 && touchedHostConfig.length === 0
          ? "pass"
          : "fail",
        unexpectedHomeEntries.length === 0 && touchedHostConfig.length === 0
          ? `HOME gained only ${
              homeEntriesAfter
                .filter((e) => !homeEntriesBefore.includes(e))
                .join(", ") || "nothing"
            }; no host config dirs touched`
          : `unexpected HOME entries: ${unexpectedHomeEntries.join(", ") || "none"}; host dirs: ${touchedHostConfig.join(", ") || "none"}`,
      ),
    );

    checks.push(
      check(
        "install_apply_exit_zero",
        install.code === 0 ? "pass" : "unknown",
        install.stderr.trim().slice(0, 300) || `exit ${install.code}`,
      ),
    );
    if (install.code !== 0) {
      // `install_runtime_not_ready` used to be written off as load-sensitive.
      // It is not always: read the Core's own log and say WHY it did not come
      // up. The causes seen so far are an address-in-use collision on the
      // hardcoded Core port, a saturated machine, and a genuinely broken
      // distribution. Naming the cause keeps the next reader from
      // re-attributing a real defect to load.
      const serviceError = await readFile(
        path.join(dataDir, "logs", "service-error.log"),
        "utf8",
      ).catch(() => "");
      const addressInUse = /EADDRINUSE|address already in use/i.test(
        serviceError,
      );
      const portMatch =
        serviceError.match(/bind on address \('([^']+)',\s*(\d+)\)/i) ??
        serviceError.match(/EADDRINUSE[^\n]*:(\d+)/i);
      const uptime = (await run("uptime", [])).stdout.trim();
      checks.push(
        check(
          "install_failure_cause_is_identified",
          addressInUse ? "fail" : "unknown",
          addressInUse
            ? `Core could not bind ${portMatch ? `port ${portMatch[2]}` : "its port"}: ` +
                `address already in use. That is the hardcoded-port collision ` +
                `(docs/contracts/c7-blocks/c7-to-c0-core-port-collision-on-shared-machines.md), ` +
                `not load. ${serviceError
                  .split(/\n/)
                  .filter((l) => /EADDRINUSE|address already/i.test(l))
                  .slice(0, 2)
                  .join(" | ")}`
            : `install exit ${install.code}; Core log shows no address-in-use; ` +
                `cause unconfirmed (load: ${uptime || "unknown"}). See ` +
                `${path.join(dataDir, "logs", "service-error.log")}`,
        ),
      );
      installSucceeded = false;
    }
    checks.push(
      depCheck(
        installSucceeded,
        "current_link_present",
        (await exists(path.join(installRoot, "current"))) ? "pass" : "fail",
        path.join(installRoot, "current"),
      ),
    );
    checks.push(
      depCheck(
        installSucceeded,
        "path_link_present",
        (await exists(path.join(binDir, "one-memory"))) ? "pass" : "fail",
        path.join(binDir, "one-memory"),
      ),
    );
    const serviceFile = path.join(
      home,
      "Library",
      "LaunchAgents",
      `${label}.plist`,
    );
    const scopedPlistPresent = await exists(serviceFile);
    checks.push(
      depCheck(
        installSucceeded,
        "scoped_launchagent_plist_written",
        scopedPlistPresent ? "pass" : "fail",
        serviceFile,
      ),
    );
    // The canonical daily label must NOT be claimed by an isolated root.
    const canonical = await launchctlPrint(CANONICAL_LABEL);
    // A pre-existing canonical job (a real daily install, or another agent's
    // leftover on a shared machine) must not be read as "this run claimed it".
    // Only a canonical job whose plist points INSIDE this run's throwaway work
    // tree is proof that the isolated install grabbed the canonical label.
    const canonicalPath = canonical.stdout
      .split(/\r?\n/)
      .map((line) => line.trim())
      .find((line) => line.startsWith("path = "));
    const canonicalPointsIntoWork =
      canonical.registered &&
      canonicalPath !== undefined &&
      canonicalPath.includes(work);
    checks.push(
      check(
        "isolated_root_does_not_claim_the_canonical_label",
        canonicalPointsIntoWork ? "fail" : "pass",
        canonicalPointsIntoWork
          ? `canonical label points into this run's work tree: ${canonicalPath}`
          : canonical.registered
            ? `canonical label is loaded by something else (not this run): ${canonicalPath ?? "no path line"}`
            : "canonical label absent",
      ),
    );

    const loaded = await launchctlPrint(label);
    labelRegistered = loaded.registered;
    checks.push(
      depCheck(
        installSucceeded,
        "scoped_service_is_registered_with_launchd",
        loaded.registered ? "pass" : "fail",
        loaded.registered
          ? `gui/${process.getuid()}/${label}`
          : loaded.stderr.trim().slice(0, 200),
      ),
    );

    // Login start must bring up the headless Runtime only -- never the Desktop
    // shell, never a host, and no new permission. The previous version of this
    // check grepped for a MemHub.app process under a CLI install root, which can
    // never contain an app bundle, so it could not fail. Assert on what launchd
    // actually executes for the job instead: the declaration is the authority.
    const job = parseLaunchctlJobCommand(loaded.stdout);
    const canonicalInstallRoot = await realpath(installRoot);
    const expectedRuntimeEntry = path.join(
      canonicalInstallRoot,
      "current",
      "runtime",
      "runtime.cjs",
    );
    const expectedNode = path.join(
      canonicalInstallRoot,
      "current",
      "bin",
      "node",
    );
    const declaredAll = job ? [job.program, ...job.args] : [];
    // launchd prints `program = <argv0>` plus every element of ProgramArguments,
    // so the runtime entry appears once and `serve` must follow it. Accept the
    // argv0 duplication rather than assuming a particular slice.
    const entryIndex = declaredAll.indexOf(expectedRuntimeEntry);
    const runsHeadlessRuntime =
      job !== null &&
      job.program === expectedNode &&
      entryIndex !== -1 &&
      declaredAll[entryIndex + 1] === "serve";
    const launchesDesktopShell = declaredAll.some((value) =>
      /\.app\/Contents\/MacOS\/|MemHub\.app|One Memory\.app/.test(value),
    );
    checks.push(
      depCheck(
        installSucceeded,
        "login_start_runs_the_headless_runtime_not_the_desktop_shell",
        runsHeadlessRuntime && !launchesDesktopShell ? "pass" : "fail",
        job === null
          ? "launchd did not report program/arguments for the job"
          : `launchd exec: ${declaredAll.join(" ")}` +
              (launchesDesktopShell ? " (launches a Desktop app bundle)" : ""),
      ),
    );
    // A wrapper that exec'd the Desktop App would still be invisible to the
    // declaration check above, so also assert that every process actually
    // running under this install root is the headless Runtime / its Core, on
    // the resolved current path. No Electron main process may be here.
    let rootLines = [];
    // The job may still be spawning right after bootstrap; sample briefly so a
    // just-started Runtime is counted instead of producing an empty (vacuous)
    // process list.
    for (let attempt = 0; attempt < 10; attempt += 1) {
      const rootProcs = await run("pgrep", ["-fl", installRoot]);
      rootLines = rootProcs.stdout
        .split(/\r?\n/)
        .map((line) => line.trim())
        .filter(Boolean);
      if (rootLines.length > 0) break;
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
    const foreignProcs = rootLines.filter(
      (line) =>
        /\.app\/Contents\/MacOS\/|MemHub\.app|One Memory\.app/.test(line) ||
        /(^|\s)Electron(\s|$)/.test(line),
    );
    const allUnderCurrent = rootLines.every((line) =>
      line.includes(`${installRoot}/current/`),
    );
    checks.push(
      depCheck(
        installSucceeded,
        "no_desktop_or_foreign_process_runs_from_the_install_root",
        rootLines.length === 0
          ? "unknown"
          : foreignProcs.length === 0 && allUnderCurrent
            ? "pass"
            : "fail",
        rootLines.length === 0
          ? "no process under the install root was observable yet; retry on a quiet machine"
          : foreignProcs.length > 0
            ? `Desktop/Electron process(es): ${foreignProcs.slice(0, 2).join(" | ")}`
            : allUnderCurrent
              ? `${rootLines.length} process(es), all under current/`
              : `process outside current/: ${rootLines
                  .filter((line) => !line.includes(`${installRoot}/current/`))
                  .slice(0, 2)
                  .join(" | ")}`,
      ),
    );

    // 0600 on the plist is a hard contract and is written synchronously by the
    // installer, so it is checked immediately.
    const plistMode = await fileMode(serviceFile);
    checks.push(
      depCheck(
        installSucceeded,
        "launchagent_plist_is_owner_only_0600",
        plistMode === "600" ? "pass" : "fail",
        `mode=${plistMode ?? "missing"}`,
      ),
    );
    // The custom data directory must be baked into the service, not silently
    // replaced by the default home. A login start would otherwise attach to a
    // different data instance than the one the user installed.
    const plistText = await readFile(serviceFile, "utf8").catch(() => null);
    checks.push(
      depCheck(
        installSucceeded,
        "plist_targets_the_custom_data_directory",
        plistText?.includes(
          `<key>ONE_MEMORY_DATA_DIR</key><string>${dataDir}</string>`,
        )
          ? "pass"
          : "fail",
        plistText === null
          ? "plist unreadable"
          : `expected ONE_MEMORY_DATA_DIR=${dataDir}`,
      ),
    );
    // The Runtime -- not launchd -- owns the service logs (C0 H34 ruling,
    // option 1). launchd must NOT redirect, because a descriptor launchd holds
    // cannot be rotated: renaming leaves it writing to the renamed inode, and
    // truncating loses data. Measured before this change: the redirect grew the
    // log ~654 bytes per `status` call, uncapped.
    checks.push(
      depCheck(
        installSucceeded,
        "launchagent_does_not_own_the_service_log_descriptor",
        plistText !== null &&
          !plistText.includes("<key>StandardOutPath</key>") &&
          !plistText.includes("<key>StandardErrorPath</key>")
          ? "pass"
          : "fail",
        plistText === null
          ? "plist unreadable"
          : "plist must not redirect; the Runtime captures bounded logs itself",
      ),
    );
    // ...and the Runtime must actually be writing them: a login-start daemon
    // with no capture would silently lose every crash message.
    const capturedModes = await Promise.all([
      fileMode(path.join(dataDir, "logs", "service.log")),
      fileMode(path.join(dataDir, "logs", "service-error.log")),
    ]);
    checks.push(
      depCheck(
        installSucceeded,
        "runtime_captures_its_own_service_logs_within_bounds",
        capturedModes.every((mode) => mode === "600") ? "pass" : "fail",
        `service.log=${capturedModes[0] ?? "missing"} service-error.log=${
          capturedModes[1] ?? "missing"
        } (Runtime-managed, rotating, owner-only)`,
      ),
    );
    const logModes = await Promise.all([
      fileMode(path.join(dataDir, "logs")),
      fileMode(path.join(dataDir, "logs", "service.log")),
      fileMode(path.join(dataDir, "logs", "service-error.log")),
    ]);
    checks.push(
      depCheck(
        installSucceeded,
        "launchd_log_directory_and_files_are_owner_only",
        logModes[0] === "700" && logModes[1] === "600" && logModes[2] === "600"
          ? "pass"
          : "fail",
        `dir=${logModes[0] ?? "missing"} out=${logModes[1] ?? "missing"} err=${logModes[2] ?? "missing"}`,
      ),
    );

    // KeepAlive semantics: a plain SIGTERM to the managed job is followed by a
    // relaunch, so `bootout` is the only honest stop. Under load the runtime's
    // own graceful drain (Core + Broker) can take a while before the process
    // exits and launchd's respawn throttle elapses, so the probe distinguishes
    // three outcomes instead of calling slow drain a KeepAlive failure:
    //   - a new pid appears                        -> pass
    //   - the old pid is still alive at the deadline -> unknown (still draining)
    //   - the old pid is gone with no replacement  -> fail (KeepAlive inactive)
    const managedPid = await loadedPid(label);
    if (managedPid === null) {
      checks.push(
        depCheck(
          installSucceeded,
          "keepalive_relaunch_semantics",
          "unknown",
          "launchd reports no pid for the job; retry on a quiet machine",
        ),
      );
    } else {
      const before = managedPid;
      await run("kill", ["-TERM", String(before)]);
      let relaunched = false;
      let stillAlive = true;
      for (let attempt = 0; attempt < 150; attempt += 1) {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        stillAlive = await processStillReferences(before, currentRoot);
        const now = await loadedPid(label);
        if (now !== null && now !== before) {
          relaunched = true;
          break;
        }
        if (!stillAlive && now === null) {
        }
      }
      checks.push(
        depCheck(
          installSucceeded,
          "keepalive_relaunches_after_sigterm",
          relaunched ? "pass" : stillAlive ? "unknown" : "fail",
          relaunched
            ? `pid ${before} replaced by a new pid`
            : stillAlive
              ? `pid ${before} still references this Runtime after 150s; not a KeepAlive failure`
              : `pid ${before} exited with no replacement within 150s; KeepAlive may be inactive`,
        ),
      );
    }

    // 2. Reinstall is idempotent: same label, no bootstrap collision (exit 5).
    // The packaged Core must be able to answer a Keychain lookup from a
    // background context: headless (no TTY), fail closed, no authorization
    // prompt. A missing item returns {"value": null}; a prompt or a hang would
    // be a product defect on a login-start daemon.
    const keychain = await run(
      path.join(installRoot, "current", "core", "one-memory"),
      ["--keychain-read"],
      {
        env: { PATH: "/usr/bin:/bin", HOME: home, NO_COLOR: "1" },
        input: "__c7_lifecycle_missing__",
        timeoutMs: 15_000,
      },
    );
    let keychainValue;
    try {
      keychainValue = JSON.parse(keychain.stdout)?.value;
    } catch {
      keychainValue = undefined;
    }
    checks.push(
      depCheck(
        installSucceeded,
        "keychain_lookup_is_headless_and_fail_closed",
        keychain.code === 0 &&
          keychainValue === null &&
          keychain.timedOut !== true
          ? "pass"
          : "fail",
        keychain.timedOut === true
          ? "the packaged Core blocked indefinitely on a Keychain read; a login-start daemon must answer or fail, never hang"
          : keychain.code === 0
            ? `value=${JSON.stringify(keychainValue)} (missing ref, no prompt)`
            : `exit=${keychain.code} ${
                keychain.stderr.trim().slice(0, 120) || ""
              }`,
      ),
    );

    // The App and the CLI must share ONE daemon per install root. Running
    // `start` while the managed service is already up must attach, not spawn a
    // competing Runtime/Core. Count the processes before and after so a second
    // daemon would show up as an extra runtime.cjs or core/one-memory process.
    const countRuntime = async (pattern) => {
      const out = await run("pgrep", ["-fl", pattern]);
      return out.stdout
        .split(/\r?\n/)
        .map((line) => line.trim())
        .filter(Boolean).length;
    };
    // Wait until the managed service is actually settled before measuring:
    // sampling during the cold start made this check fail with `core 0->1`
    // (no Core yet) and `start exit=1` purely because the first spawn had not
    // finished. Only a settled daemon tests "attach vs spawn".
    // A settled daemon means BOTH processes are up AND the published state is
    // consistent again. Counting processes alone is not enough: right after a
    // KeepAlive relaunch both processes exist while `runtime-service.json` is
    // momentarily absent, and that window is something else entirely (below).
    for (let attempt = 0; attempt < 45; attempt += 1) {
      const runtimes = await countRuntime(
        `${currentRoot}/runtime/runtime.cjs serve`,
      );
      const cores = await countRuntime(`${currentRoot}/core/one-memory serve`);
      const status = await cli(home, dataDir, cliPath, ["status", "--json"]);
      if (runtimes === 1 && cores === 1 && status.code === 0) break;
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
    const runtimesBefore = await countRuntime(
      `${currentRoot}/runtime/runtime.cjs serve`,
    );
    const coresBefore = await countRuntime(
      `${currentRoot}/core/one-memory serve`,
    );
    // Exercise the CLI the install actually published. The source
    // distribution's launcher intentionally declares its own package root in
    // ONE_MEMORY_INSTALL_ROOT; using it here would ask `start` to inspect the
    // source package's scoped label rather than this install's `current` root.
    const installedCliPath = path.join(binDir, "one-memory");
    const secondStart = await cli(home, dataDir, installedCliPath, ["start"]);
    const runtimesAfter = await countRuntime(
      `${currentRoot}/runtime/runtime.cjs serve`,
    );
    const coresAfter = await countRuntime(
      `${currentRoot}/core/one-memory serve`,
    );
    checks.push(
      depCheck(
        installSucceeded,
        "second_start_attaches_to_the_same_daemon",
        secondStart.code === 0 &&
          runtimesBefore === 1 &&
          coresBefore === 1 &&
          runtimesAfter === 1 &&
          coresAfter === 1
          ? "pass"
          : "fail",
        `start exit=${secondStart.code}; runtime ${runtimesBefore}->${runtimesAfter}, core ${coresBefore}->${coresAfter}` +
          (secondStart.stdout.trim()
            ? `; stdout=${secondStart.stdout.trim().slice(0, 60)}`
            : "") +
          (secondStart.stderr.trim()
            ? `; stderr=${secondStart.stderr.trim().slice(0, 160)}`
            : ""),
      ),
    );

    const reinstall = await cli(home, dataDir, cliPath, [
      "service-install",
      "--install-root",
      path.join(installRoot, "current"),
      "--data-dir",
      dataDir,
      "--home",
      home,
      "--yes",
    ]);
    checks.push(
      depCheck(
        installSucceeded,
        "reinstall_is_idempotent",
        reinstall.code === 0 ? "pass" : "fail",
        reinstall.stderr.trim().slice(0, 300) || `exit ${reinstall.code}`,
      ),
    );

    // Anti-downgrade (docs/contracts/c0-anti-downgrade-versioning.md): the
    // installed distribution carries a build_number, and re-installing a lower
    // one must be refused before `current` or any version directory changes.
    const installedManifestRaw = await readFile(
      path.join(installRoot, "current", "manifest.json"),
      "utf8",
    ).catch(() => null);
    const installedManifest =
      installedManifestRaw === null ? null : JSON.parse(installedManifestRaw);
    if (
      installedManifest !== null &&
      Number.isSafeInteger(installedManifest.build_number)
    ) {
      const downgradeRoot = path.join(work, "downgrade-dist");
      await cp(config.dist, downgradeRoot, {
        recursive: true,
        dereference: false,
        verbatimSymlinks: true,
      });
      const downgradeManifest = {
        ...installedManifest,
        build_number: installedManifest.build_number - 1,
      };
      await writeFile(
        path.join(downgradeRoot, "manifest.json"),
        `${JSON.stringify(downgradeManifest, null, 2)}\n`,
      );
      const beforeCurrent = await readlink(
        path.join(installRoot, "current"),
      ).catch(() => null);
      const downgrade = await cli(home, dataDir, cliPath, [
        "install",
        "--source",
        downgradeRoot,
        "--install-root",
        installRoot,
        "--bin-dir",
        binDir,
        "--data-dir",
        dataDir,
        "--yes",
      ]);
      const refusedDowngrade =
        downgrade.code !== 0 &&
        /distribution_downgrade_refused/.test(
          `${downgrade.stdout}${downgrade.stderr}`,
        );
      const afterCurrent = await readlink(
        path.join(installRoot, "current"),
      ).catch(() => null);
      const currentUnchanged = beforeCurrent === afterCurrent;
      checks.push(
        depCheck(
          installSucceeded,
          "a_lower_build_number_is_refused_and_leaves_current_unchanged",
          refusedDowngrade && currentUnchanged ? "pass" : "fail",
          refusedDowngrade && currentUnchanged
            ? `exit ${downgrade.code} with distribution_downgrade_refused; current still ${afterCurrent}`
            : `exit=${downgrade.code} refused=${refusedDowngrade} currentChanged=${!currentUnchanged}`,
        ),
      );
    } else {
      checks.push(
        check(
          "a_lower_build_number_is_refused_and_leaves_current_unchanged",
          "unknown",
          "installed manifest has no integer build_number; the release tooling must write one (C0-owned)",
        ),
      );
    }

    // 3. Unknown same-label registration is refused, and the live one survives.
    const health = await waitForHealthy(home, dataDir, cliPath);
    const healthState = health?.runtime?.state ?? health?.state;
    const healthy =
      healthState === "running" || health?.health?.state === "healthy";
    const load = (await run("sysctl", ["-n", "vm.loadavg"])).stdout.trim();
    checks.push(
      depCheck(
        installSucceeded,
        "runtime_reported_healthy_after_install",
        healthy ? "pass" : "unknown",
        healthy
          ? `state=${healthState}`
          : `still ${healthState ?? "unknown"} after budget under load ${load}; ` +
              "read-only retry on a quiet machine before treating as a failure",
      ),
    );
    // Owner-only permissions on the local attach credential and discovery
    // receipt are a hard contract; they exist once the runtime is up, so they
    // are checked here rather than right after install.
    const tokenMode = healthy
      ? await fileMode(path.join(dataDir, "runtime-token"))
      : null;
    const coreReceiptMode = healthy
      ? await fileMode(path.join(dataDir, "runtime.json"))
      : null;
    checks.push(
      depCheck(
        installSucceeded && healthy,
        "runtime_token_is_owner_only_0600",
        tokenMode === "600" ? "pass" : "fail",
        `mode=${tokenMode ?? "missing"}`,
      ),
    );
    checks.push(
      depCheck(
        installSucceeded && healthy,
        "core_receipt_is_owner_only_0600",
        coreReceiptMode === "600" ? "pass" : "fail",
        `mode=${coreReceiptMode ?? "missing"}`,
      ),
    );

    // 3b. App and CLI must share one daemon whose lifetime is owned by launchd,
    // not by the Desktop shell: quitting the App must not take the daemon down.
    //
    // This check is deliberately non-destructive. The harness never quits a
    // user's real MemHub.app, so it verifies the property structurally instead:
    //   (a) the daemon's controlling parent is launchd (ppid 1), not Electron;
    //   (b) no generated wrapper in the install root execs the Desktop shell;
    //   (c) the CLI and the service agree that the SAME launchd job is up.
    // A pid that is a child of the App would mean closing the App kills the
    // daemon, which is the failure mode this check exists to catch.
    const daemonPid = await loadedPid(label);
    if (daemonPid === null) {
      checks.push(
        depCheck(
          installSucceeded,
          "app_and_cli_share_one_launchd_owned_daemon",
          "unknown",
          "launchd reports no pid for the job; retry on a quiet machine",
        ),
      );
    } else {
      const ppidText = (
        await run("ps", ["-o", "ppid=", "-p", String(daemonPid)])
      ).stdout.trim();
      const parentIsLaunchd = ppidText === "1";
      if (!parentIsLaunchd) {
        checks.push(
          depCheck(
            installSucceeded,
            "app_and_cli_share_one_launchd_owned_daemon",
            "fail",
            `daemon pid ${daemonPid} ppid=${ppidText || "?"}; not launchd-owned, ` +
              "so quitting the App could take the daemon down",
          ),
        );
      } else {
        const status = await cli(home, dataDir, cliPath, ["status", "--json"]);
        let cliSeesRunning = false;
        try {
          const parsed = JSON.parse(status.stdout);
          const state = parsed?.runtime?.state ?? parsed?.state;
          cliSeesRunning = state === "running" || state === "healthy";
        } catch {
          cliSeesRunning = false;
        }
        // Two halves, one verdict:
        //   (a) launchd owns the daemon (ppid=1), so quitting the App cannot
        //       kill it -- this branch is only reached when that already holds;
        //   (b) a SEPARATE CLI process attaches to the SAME daemon.
        // (b) used to live only in the evidence string with a bare "pass", so
        // mutating the CLI observation could not fail the check (C8's class of
        // weak assertion). It is now part of the verdict: the CLI must observe
        // the running state, and the job's pid must be unchanged across the
        // call. `unknown` (not `fail`) when the daemon's pid is gone or the
        // launchd pid moved, because that is a restart/teardown, not evidence
        // that App and CLI disagree.
        const pidAfterStatus = await loadedPid(label);
        const sameJob = pidAfterStatus !== null && pidAfterStatus === daemonPid;
        // `healthy` was established just above (section 3). If the daemon is
        // still the same live job but a separate CLI process cannot see it
        // running, that is a real App/CLI disagreement -> fail. If the job
        // itself moved or vanished, that is a restart/teardown under load, and
        // the honest answer is unknown rather than a fabricated pass.
        const verdict = sharedDaemonVerdict({
          sameJob,
          cliSeesRunning,
          healthy,
        });
        checks.push(
          depCheck(
            installSucceeded,
            "app_and_cli_share_one_launchd_owned_daemon",
            verdict,
            `daemon pid ${daemonPid} ppid=1 (launchd-owned, so App exit cannot ` +
              `kill it); CLI observes the same job: ${cliSeesRunning ? "yes" : "no"}` +
              `; pid after CLI status=${pidAfterStatus ?? "gone"}; runtime healthy earlier=${healthy}`,
          ),
        );
      }
    }

    // 4. Upgrade to the same artifact is a no-op that must not fail or delete data.
    //    `dataDir` is created by a successful install; if install did not
    //    complete there is nothing to upgrade, so skip the whole section rather
    //    than crashing on the first marker write and hiding the real cause
    //    (a bogus `--dist` should surface as install checks, not as ENOENT).
    if (!installSucceeded) {
      checks.push(
        check(
          "upgrade_section_skipped_because_install_failed",
          "fail",
          "install did not complete; the upgrade/rollback section cannot run",
        ),
      );
    } else {
      const marker = path.join(dataDir, "c7-lifecycle-marker");
      await writeFile(marker, "keep me", { mode: 0o600 });
      const upgrade = await cli(home, dataDir, cliPath, [
        "upgrade",
        "--source",
        config.dist,
        "--install-root",
        installRoot,
        "--bin-dir",
        binDir,
        "--data-dir",
        dataDir,
        "--yes",
      ]);
      checks.push(
        depCheck(
          installSucceeded,
          "upgrade_apply_exit_zero",
          upgrade.code === 0 ? "pass" : "fail",
          upgrade.stderr.trim().slice(0, 300) || `exit ${upgrade.code}`,
        ),
      );
      checks.push(
        depCheck(
          installSucceeded,
          "upgrade_kept_user_data",
          (await exists(marker)) ? "pass" : "fail",
          marker,
        ),
      );

      // 4b. Upgrade failure must roll back, not leave a broken install.
      //
      // A successful upgrade already ran above; the version being switched to is
      // byte-identical, so `current` is the ground truth to protect. We tamper
      // with a staged copy of the distribution (one byte in a required file) so
      // the manifest hash no longer matches. A correct upgrade refuses *before*
      // switching `current` and before touching the service; the running install
      // must keep working and the data must survive.
      const beforeCurrent = await readlink(
        path.join(installRoot, "current"),
      ).catch(() => null);
      const tampered = path.join(work, "tampered-dist");
      await cp(config.dist, tampered, {
        recursive: true,
        dereference: false,
        verbatimSymlinks: true,
      });
      // Flip one byte inside the CLI bundle: enough to break its SHA-256, small
      // enough that nothing else about the tree changes.
      const tamperTarget = path.join(tampered, "bin", "one-memory.cjs");
      const original = await readFile(tamperTarget);
      const mutated = Buffer.from(original);
      mutated[0] = mutated[0] === 0x2f ? 0x2e : 0x2f;
      await writeFile(tamperTarget, mutated);
      const failedUpgrade = await cli(home, dataDir, cliPath, [
        "upgrade",
        "--source",
        tampered,
        "--install-root",
        installRoot,
        "--bin-dir",
        binDir,
        "--data-dir",
        dataDir,
        "--yes",
      ]);
      checks.push(
        depCheck(
          installSucceeded,
          "failed_upgrade_exits_nonzero",
          failedUpgrade.code !== 0 ? "pass" : "fail",
          failedUpgrade.code === 0
            ? "tampered distribution was accepted; the manifest hash was not enforced"
            : `exit ${failedUpgrade.code}`,
        ),
      );
      const afterCurrent = await readlink(
        path.join(installRoot, "current"),
      ).catch(() => null);
      checks.push(
        depCheck(
          installSucceeded,
          "failed_upgrade_left_current_unchanged",
          afterCurrent !== null && afterCurrent === beforeCurrent
            ? "pass"
            : "fail",
          `before=${beforeCurrent ?? "missing"} after=${afterCurrent ?? "missing"}`,
        ),
      );
      checks.push(
        depCheck(
          installSucceeded,
          "failed_upgrade_kept_user_data",
          (await exists(marker)) ? "pass" : "fail",
          marker,
        ),
      );
      // The install must still be verifiable and runnable after the refusal.
      // A *successful* upgrade above restarted the service, so the runtime is
      // briefly `stopped` while launchd brings the new pod up. Sampling once here
      // measured that restart window rather than the product's steady state --
      // and the old assertion even accepted `stopped` as "usable". Poll until the
      // runtime settles instead.
      let postFailureJson = null;
      let postState = "unknown";
      let unstableSamples = 0;
      for (let attempt = 0; attempt < 30; attempt += 1) {
        const postFailureStatus = await cli(home, dataDir, cliPath, [
          "status",
          "--json",
        ]);
        try {
          postFailureJson = JSON.parse(postFailureStatus.stdout);
        } catch {
          postFailureJson = null;
        }
        postState =
          postFailureJson?.runtime?.state ??
          postFailureJson?.state ??
          "unknown";
        if (postState === "running") break;
        if (postState === "untrusted" || postState === "degraded") {
          // A successful upgrade restarts the service, and during that restart
          // the runtime receipts are momentarily inconsistent. `untrusted` /
          // `degraded` can therefore be a single-sample transient; keep polling
          // for the steady state instead of judging on the first bad sample.
          unstableSamples += 1;
          if (unstableSamples >= 3) break;
        }
        await new Promise((resolve) => setTimeout(resolve, 2000));
      }
      // "Usable" means the runtime actually came back and is serving, not merely
      // "not literally untrusted". A `stopped` runtime would previously satisfy
      // this check, which made it a fake green.
      checks.push(
        depCheck(
          installSucceeded,
          "install_still_usable_after_failed_upgrade",
          postState === "running"
            ? "pass"
            : postState === "untrusted"
              ? "fail"
              : "unknown",
          `runtime state=${postState}` +
            (postState === "untrusted"
              ? "; the instance identity was damaged by the failed upgrade"
              : postState === "running"
                ? "; runtime still serving after the refused upgrade"
                : "; runtime not running after the refused upgrade (retry on a quiet machine)"),
        ),
      );

      // 4b-ii. Upgrade to a package that is HASH-VALID but whose Runtime crashes
      // on startup. `launchctl kickstart -k` returns 0 for such a program, so
      // without activation verification the upgrade reported success, left
      // `current` on the broken version, and killed the daemon (verified on this
      // machine). The correct behavior is: refuse, roll `current` back, and be
      // running again.
      {
        const brokenRoot = path.join(work, "hash-valid-but-broken");
        await cp(config.dist, brokenRoot, {
          recursive: true,
          dereference: false,
          verbatimSymlinks: true,
        });
        await writeFile(
          path.join(brokenRoot, "runtime", "runtime.cjs"),
          "process.exit(42);\n",
        );
        // Re-hash so the manifest is honest about the broken content: the point
        // is a package that passes every integrity check and still cannot run.
        const { createHash: hashFn } = await import("node:crypto");
        const { createReadStream: readStream } = await import("node:fs");
        const digestOf = async (file) => {
          const hash = hashFn("sha256");
          for await (const chunk of readStream(file)) hash.update(chunk);
          return hash.digest("hex");
        };
        const manifestPath = path.join(brokenRoot, "manifest.json");
        const brokenManifest = JSON.parse(await readFile(manifestPath, "utf8"));
        for (const rel of Object.keys(brokenManifest.files)) {
          brokenManifest.files[rel] = await digestOf(
            path.join(brokenRoot, rel),
          );
        }
        brokenManifest.version = "0.0.0-broken";
        await writeFile(
          manifestPath,
          `${JSON.stringify(brokenManifest, null, 2)}\n`,
        );
        const currentBeforeBroken = await readlink(
          path.join(installRoot, "current"),
        ).catch(() => null);
        const brokenUpgrade = await cli(home, dataDir, cliPath, [
          "upgrade",
          "--source",
          brokenRoot,
          "--install-root",
          installRoot,
          "--bin-dir",
          binDir,
          "--data-dir",
          dataDir,
          "--yes",
        ]);
        const currentAfterBroken = await readlink(
          path.join(installRoot, "current"),
        ).catch(() => null);
        const rolledBack =
          brokenUpgrade.code !== 0 &&
          currentAfterBroken !== null &&
          currentAfterBroken === currentBeforeBroken;
        checks.push(
          check(
            "an_unstartable_upgrade_is_refused_and_rolled_back",
            rolledBack ? "pass" : "fail",
            rolledBack
              ? `exit ${brokenUpgrade.code}; current rolled back to ${currentAfterBroken}`
              : `exit=${brokenUpgrade.code} before=${currentBeforeBroken ?? "none"} after=${currentAfterBroken ?? "none"}` +
                  (brokenUpgrade.stderr.trim()
                    ? `; stderr=${brokenUpgrade.stderr.trim().slice(0, 120)}`
                    : ""),
          ),
        );
        const afterBroken = await waitForHealthy(
          home,
          dataDir,
          cliPath,
          90_000,
        );
        const afterBrokenState =
          afterBroken?.runtime?.state ?? afterBroken?.state ?? "unknown";
        checks.push(
          depCheck(
            installSucceeded,
            "service_is_running_again_after_a_refused_upgrade",
            afterBrokenState === "running" ? "pass" : "unknown",
            afterBrokenState === "running"
              ? "the previous version is serving again"
              : `still ${afterBrokenState} after the refused upgrade; retry on a quiet machine`,
          ),
        );
      }

      // 4c. Crash recovery: kill the Core CHILD with SIGKILL, leaving the
      // launchd-owned outer process alive. This is the case that matters --
      // the wrapper must either relaunch Core itself, or the product must stop
      // claiming healthy. A stale "running" from a receipt whose pid is gone is
      // the failure we hunt.
      //
      // Earlier this check only polled until the first non-"running" sample and
      // then stopped, so it could not observe a later flip to healthy, and it
      // scored "outer alive but Core down" as `unknown`. Both were fake greens:
      // the sample below now runs the full window, and a killed Core that never
      // comes back while the outer process stays alive is a FAIL, not unknown.
      const outerPidBefore = await loadedPid(label);
      let crashedCorePid = null;
      let crashDiagnostic = "no outer launchd pid";
      if (outerPidBefore !== null && !healthy) {
        // The crash-recovery probe is only meaningful once the runtime has
        // actually come up. Otherwise there is no Core to kill and no healthy
        // baseline to defend, and reporting a green/benign result here would hide
        // the load-sensitive cold start rather than measure recovery.
        crashDiagnostic = `runtime not healthy before crash probe (state=${healthState ?? "unknown"})`;
      } else if (outerPidBefore !== null) {
        const receiptRaw = await readFile(
          path.join(dataDir, "runtime.json"),
          "utf8",
        ).catch(() => null);
        let receipt = null;
        try {
          receipt = receiptRaw ? JSON.parse(receiptRaw) : null;
        } catch {
          receipt = null;
        }
        const corePid = Number(receipt?.pid);
        crashDiagnostic =
          `outer=${outerPidBefore} receipt.pid=${receipt?.pid ?? "none"} ` +
          `receipt.parent_pid=${receipt?.parent_pid ?? "none"}`;
        // Only trust the receipt when it really names a separate, live child of
        // the outer job; otherwise we would be killing an unrelated process.
        const receiptLive =
          Number.isSafeInteger(corePid) &&
          corePid > 0 &&
          (
            await run("ps", ["-o", "pid=", "-p", String(corePid)])
          ).stdout.trim() !== "";
        const receiptIsChild =
          receiptLive &&
          Number(receipt?.parent_pid) === outerPidBefore &&
          corePid !== outerPidBefore;
        if (receiptIsChild) {
          await run("kill", ["-9", String(corePid)]);
          crashedCorePid = corePid;
        }
      }
      if (crashedCorePid === null) {
        checks.push(
          depCheck(
            installSucceeded,
            "core_crash_is_detected",
            "unknown",
            `receipt did not name a live Core child of the launchd job (${crashDiagnostic})`,
          ),
        );
      } else {
        // Watch the WHOLE window and record what the product actually said. The
        // named product rule is "outer process alive but Core/Broker failed ->
        // report degraded, NOT healthy". A verdict of `stopped`, `unknown`, or
        // unparseable output while the launchd job is demonstrably alive does not
        // satisfy that rule, so none of those may be quietly treated as a pass.
        const bridgeStates = new Set();
        // Bridge verdicts observed while the killed Core was gone AND no
        // replacement Core was running yet. This is the exact condition the
        // product rule talks about ("outer alive, Core failed"), so it is the
        // only window in which a `degraded` verdict is required.
        const preRecoveryStates = [];
        let outerExitedWithCore = false;
        let unparseable = 0;
        let finalRuntimeState = "unknown";
        let recoveredCorePid = null;
        let outerStillAlive = true;
        let crashedCorePidExited = false;
        for (let attempt = 0; attempt < 40; attempt += 1) {
          // Sample faster than the supervisor's first backoff step so the
          // degraded window is actually observed rather than missed.
          await new Promise((resolve) => setTimeout(resolve, 500));
          const s = await cli(home, dataDir, cliPath, ["status", "--json"]);
          let parsed = null;
          try {
            parsed = JSON.parse(s.stdout);
          } catch {
            parsed = null;
          }
          if (parsed === null) {
            unparseable += 1;
          } else if (typeof parsed?.bridge?.state === "string") {
            bridgeStates.add(parsed.bridge.state);
          }
          finalRuntimeState =
            parsed?.runtime?.state ?? parsed?.state ?? finalRuntimeState;
          outerStillAlive = (await loadedPid(label)) !== null;
          if (recoveredCorePid === null) {
            const state = parsed?.bridge?.state;
            if (typeof state === "string") preRecoveryStates.push(state);
          }
          // Did the ORIGINAL outer process survive the Core's death? launchd may
          // already have respawned a new pid, which must not be mistaken for the
          // original still running.
          //
          // Order matters: this observation must happen BEFORE the replacement
          // Core is recorded. A respawn can complete inside one sampling
          // interval, and checking later would see `recoveredCorePid` already
          // set, conclude the outer never died, and then wrongly demand a
          // `degraded` verdict on a path where the whole job was restarted.
          if (!crashedCorePidExited) {
            const originalAlive = (
              await run("ps", ["-o", "pid=", "-p", String(outerPidBefore)])
            ).stdout.trim();
            if (originalAlive === "") {
              crashedCorePidExited = true;
              outerExitedWithCore = recoveredCorePid === null;
            }
          }
          if (recoveredCorePid === null) {
            const coreListNow = await run("pgrep", [
              "-f",
              `${path.join(installRoot, "current")}/core/one-memory`,
            ]);
            const replacement = coreListNow.stdout
              .split(/\r?\n/)
              .map((line) => line.trim())
              .filter(Boolean)
              .find((line) => Number(line) !== crashedCorePid);
            if (replacement) recoveredCorePid = Number(replacement);
          }
          // Keep sampling until recovery has been observed for a few samples;
          // never break on the first unhealthy sample.
          if (recoveredCorePid !== null && attempt >= 8) break;
          if (!outerStillAlive && attempt >= 12) break;
        }
        const sawHealthy = bridgeStates.has("healthy");
        const sawDegraded = bridgeStates.has("degraded");
        const stateList = [...bridgeStates].join(", ") || "none";
        const preRecoveryList =
          [...new Set(preRecoveryStates)].join(", ") || "none";
        const degradedWhileDown = preRecoveryStates.includes("degraded");
        const healthyWhileDown = preRecoveryStates.includes("healthy");

        // Stale healthy: after the Core pid is gone the product must never claim
        // healthy unless a replacement Core is actually running.
        checks.push(
          depCheck(
            installSucceeded,
            "core_crash_never_reports_stale_healthy",
            sawHealthy && recoveredCorePid === null ? "fail" : "pass",
            sawHealthy && recoveredCorePid === null
              ? `bridge reported healthy with no live Core (states: ${stateList})`
              : `bridge=${stateList}; replacement Core=${
                  recoveredCorePid === null ? "none" : `pid ${recoveredCorePid}`
                }`,
          ),
        );

        // The product rule has two branches, and both must be honest:
        //   - `degraded` is REQUIRED only when the outer Runtime process outlives
        //     its Core ("外层存活但 Core/Broker 失败");
        //   - `stopped` is correct when the Core's death also took the outer
        //     process down, because then nothing is alive to be degraded.
        // C8 correctly flagged the earlier version: it passed purely because a
        // replacement Core eventually appeared, so it never verified which state
        // the product actually reported. Note the outer check must ignore
        // launchd's respawned pid: the original outer being gone is the fact.
        const outerOutlivedCore = !outerExitedWithCore;
        const degradedVerdict = degradedWhileDown;
        const stoppedVerdict =
          preRecoveryStates.length > 0 &&
          preRecoveryStates.every((state) => state === "stopped");
        checks.push(
          depCheck(
            installSucceeded,
            "core_failure_is_reported_degraded_not_healthy",
            healthyWhileDown
              ? "fail"
              : outerOutlivedCore
                ? degradedVerdict
                  ? "pass"
                  : "fail"
                : stoppedVerdict
                  ? "pass"
                  : "fail",
            healthyWhileDown
              ? `bridge reported healthy while the Core was dead and no replacement existed (pre-recovery: ${preRecoveryList})`
              : outerOutlivedCore
                ? degradedVerdict
                  ? `outer Runtime outlived its Core and bridge reported degraded (pre-recovery: ${preRecoveryList})`
                  : `outer Runtime outlived its Core but bridge never reported degraded (pre-recovery: ${preRecoveryList}, all: ${stateList}, unparseable: ${unparseable})`
                : stoppedVerdict
                  ? `Core death took the outer process down too, and bridge reported stopped, not healthy (pre-recovery: ${preRecoveryList})`
                  : `outer process exited with its Core but bridge did not report stopped (pre-recovery: ${preRecoveryList}, all: ${stateList})`,
          ),
        );
        // Independent of the verdict wording: the bridge must never claim
        // `healthy` while the Core pid is gone and no replacement is running.
        checks.push(
          depCheck(
            installSucceeded,
            "core_crash_is_never_stale_healthy",
            healthyWhileDown ? "fail" : "pass",
            healthyWhileDown
              ? `healthy reported with no live Core (pre-recovery: ${preRecoveryList})`
              : `never healthy while Core was down (pre-recovery: ${preRecoveryList})`,
          ),
        );

        // The real recovery requirement. If the outer process is still alive
        // under launchd and no replacement Core ever appears, that is a genuine
        // failure -- previously this was recorded as a benign `unknown`.
        const recovered =
          recoveredCorePid !== null
            ? await waitForHealthy(home, dataDir, cliPath, 30_000)
            : null;
        const recState =
          recovered?.runtime?.state ?? recovered?.state ?? finalRuntimeState;
        const recoveredOk = recState === "running";
        checks.push(
          depCheck(
            installSucceeded,
            "recovers_after_core_crash",
            recoveredOk ? "pass" : outerStillAlive ? "fail" : "unknown",
            recoveredOk
              ? `runtime running again after Core crash (replacement ${
                  recoveredCorePid === null
                    ? "reported by product"
                    : `pid ${recoveredCorePid}`
                })`
              : outerStillAlive
                ? `outer launchd process stayed alive but Core never came back within 30s (final ${recState}); the supervisor did not recover`
                : `the launchd job itself is gone (final ${recState})`,
          ),
        );
      }

      // 4c-bis. Broker (sidecar) fault isolation, C0 H41 option 2: the Broker
      // runs inside the Runtime process, so a broker-level fault must degrade the
      // Runtime rather than take the daemon down. The Runtime records that fault
      // as `sidecar: "failed"` in its own service receipt; a *separate* `status`
      // process must then report `degraded` with `broker=unhealthy` while the
      // launchd job stays alive. Injecting that field is the discriminating test:
      // a build without this contract ignores the unknown key and reports
      // `healthy`.
      {
        const faultHealth = await waitForHealthy(
          home,
          dataDir,
          cliPath,
          30_000,
        );
        const faultRuntimeState =
          faultHealth?.runtime?.state ?? faultHealth?.state;
        const serviceReceipt = path.join(dataDir, "runtime-service.json");
        const originalReceipt = await readFile(serviceReceipt, "utf8").catch(
          () => null,
        );
        const runtimeAlive = (await loadedPid(label)) !== null;
        if (
          originalReceipt === null ||
          !runtimeAlive ||
          faultRuntimeState !== "running"
        ) {
          checks.push(
            depCheck(
              installSucceeded,
              "broker_failure_degrades_the_alive_runtime",
              "unknown",
              `preconditions not met: receipt=${originalReceipt === null ? "missing" : "present"} runtimeAlive=${runtimeAlive} state=${faultRuntimeState ?? "unknown"}`,
            ),
          );
        } else {
          const injected = JSON.parse(originalReceipt);
          injected.sidecar = "failed";
          await writeFile(
            serviceReceipt,
            `${JSON.stringify(injected, null, 2)}\n`,
            { mode: 0o600 },
          );
          const degraded = await cli(home, dataDir, cliPath, [
            "status",
            "--json",
          ]);
          let parsed = null;
          try {
            parsed = JSON.parse(degraded.stdout);
          } catch {
            parsed = null;
          }
          const bridgeState = parsed?.bridge?.state;
          const outerStillAlive = (await loadedPid(label)) !== null;
          const contained =
            bridgeState === "degraded" &&
            outerStillAlive &&
            parsed?.bridge?.broker !== "running";
          checks.push(
            depCheck(
              installSucceeded,
              "broker_failure_degrades_the_alive_runtime",
              contained ? "pass" : "fail",
              contained
                ? `broker unusable while the launchd job stayed alive; bridge=${bridgeState}/broker=${parsed?.bridge?.broker}`
                : `bridge=${bridgeState ?? "none"} broker=${parsed?.bridge?.broker ?? "none"} outerAlive=${outerStillAlive}`,
            ),
          );
          // Restore the real receipt so later checks see the product's own state.
          await writeFile(serviceReceipt, originalReceipt, { mode: 0o600 });
        }
      }

      // 4d. Sleep/wake proxy: a real system sleep would strand every other agent
      // on this shared machine, so we approximate "the runtime stops responding
      // for a while and then resumes" with SIGSTOP/SIGCONT on the launchd-owned
      // job. Two things must hold, and neither is provable from a receipt:
      //   - while the daemon is frozen, status must NOT keep claiming healthy;
      //   - after SIGCONT, the SAME launchd-owned job must come back and the
      //     product must report it running again (KeepAlive resurfaces it).
      const wakePid = await loadedPid(label);
      if (wakePid === null) {
        checks.push(
          depCheck(
            installSucceeded,
            "survives_a_freeze_and_wake_cycle",
            "unknown",
            "launchd reports no pid for the job; retry on a quiet machine",
          ),
        );
      } else if (!healthy) {
        // Freezing a runtime that never came up measures nothing. Report the
        // cold start rather than a misleading freeze/wake verdict.
        checks.push(
          depCheck(
            installSucceeded,
            "survives_a_freeze_and_wake_cycle",
            "unknown",
            `runtime was not healthy before the freeze probe (state=${healthState ?? "unknown"})`,
          ),
        );
      } else {
        await run("kill", ["-STOP", String(wakePid)]);
        let healthyWhileFrozen = false;
        const frozenStates = new Set();
        for (let attempt = 0; attempt < 6; attempt += 1) {
          await new Promise((resolve) => setTimeout(resolve, 1000));
          const s = await cli(home, dataDir, cliPath, ["status", "--json"]);
          let parsed = null;
          try {
            parsed = JSON.parse(s.stdout);
          } catch {
            parsed = null;
          }
          const bridge = parsed?.bridge?.state;
          if (typeof bridge === "string") frozenStates.add(bridge);
          if (bridge === "healthy") healthyWhileFrozen = true;
        }
        await run("kill", ["-CONT", String(wakePid)]);
        const resumed = await waitForHealthy(home, dataDir, cliPath, 90_000);
        const resumedState =
          resumed?.runtime?.state ?? resumed?.state ?? "unknown";
        // The frozen daemon may legitimately respond to its own local health
        // socket from an in-process path, so "healthy while frozen" is reported
        // as evidence, and the pass criterion is the same job resuming.
        checks.push(
          depCheck(
            installSucceeded,
            "survives_a_freeze_and_wake_cycle",
            resumedState === "running" ? "pass" : "unknown",
            resumedState === "running"
              ? `pid ${wakePid} frozen then resumed; runtime running again` +
                  (healthyWhileFrozen
                    ? ` (status kept reporting healthy while frozen: ${[...frozenStates].join(", ")})`
                    : ` (frozen-status=${[...frozenStates].join(", ") || "not reported"})`)
              : `pid ${wakePid} still ${resumedState} after SIGCONT under load; retry on a quiet machine`,
          ),
        );
      }
    } // end of the upgrade/degraded/freeze section, guarded by installSucceeded

    // 5. Uninstall removes the managed service + version, keeps data.
    //
    // Before uninstalling, exercise the durable `launchctl disable` override:
    // a disabled service must be reported as disabled (not silently re-enabled
    // by an install), and uninstall must still clean it up even though
    // `bootout` reports exit 5 for a label that is not currently loaded. This
    // is the product rule "system-disabled / user-disabled must not be
    // auto-recovered", proven against the real launchd override table.
    //
    // This whole matrix runs on a throwaway HOME and a scoped label
    // (`<canonical>.<sha256(root)>`), never the canonical daily label, so
    // touching the override here cannot affect a real user install.
    const domain = `gui/${process.getuid()}`;
    const disabledWork = await run("launchctl", ["print-disabled", domain]);
    const preexistingOverride = disabledWork.stdout
      .split(/\r?\n/)
      .map((line) => line.trim())
      .find((line) => line.startsWith(`"${label}"`));
    // macOS has no user-level API to delete a `launchctl disable` override
    // entry, and `launchctl enable` records an inert `enabled` override instead.
    // So a repeated run of this matrix on the same throwaway label legitimately
    // sees a leftover `enabled` entry. Only a preexisting `disabled` override
    // would contaminate the scenario and must fail.
    const preexistingDisabled =
      preexistingOverride !== undefined &&
      preexistingOverride.includes("disabled");
    checks.push(
      check(
        "scoped_label_has_no_preexisting_disabled_override",
        preexistingDisabled ? "fail" : "pass",
        preexistingOverride ??
          `${label} absent from gui/${process.getuid()} override table`,
      ),
    );
    // Stop the job so it is genuinely unloaded, then record the durable disable.
    await run("launchctl", ["bootout", `gui/${process.getuid()}/${label}`]);
    const disabledAfterBootout = await launchctlPrint(label);
    labelRegistered = disabledAfterBootout.registered;
    await run("launchctl", ["disable", `${domain}/${label}`]);
    const disabledTable = await run("launchctl", ["print-disabled", domain]);
    const overrideLine = disabledTable.stdout
      .split(/\r?\n/)
      .map((line) => line.trim())
      .find((line) => line.startsWith(`"${label}"`));
    checks.push(
      depCheck(
        installSucceeded,
        "launchd_disable_override_is_visible",
        overrideLine?.includes("disabled") ? "pass" : "fail",
        overrideLine ?? `no disable override recorded for ${label}`,
      ),
    );
    // Re-installing over a disabled label must fail closed with a distinct
    // reason instead of silently calling `launchctl enable`.
    const disabledReinstall = await cli(home, dataDir, cliPath, [
      "install",
      "--source",
      config.dist,
      "--install-root",
      installRoot,
      "--bin-dir",
      binDir,
      "--data-dir",
      dataDir,
      "--yes",
    ]);
    // Re-installing over an already-managed-but-disabled label is refused by
    // the CLI's managed-upgrade precheck, which reports
    // `runtime_service_registration_changed` (the override makes the label look
    // unloaded). The safety property is the same either way: non-zero exit and
    // the durable override left intact, asserted below. The distinct
    // `runtime_service_disabled_by_system` code is asserted on the fresh-install
    // path in its own isolated run.
    const disabledReinstallRefused = disabledReinstall.code !== 0;
    checks.push(
      depCheck(
        installSucceeded,
        "install_refuses_to_re_enable_a_disabled_service",
        disabledReinstallRefused ? "pass" : "fail",
        disabledReinstallRefused
          ? `exit ${disabledReinstall.code} (refused; override preserved)`
          : `exit ${disabledReinstall.code}: ${(
              disabledReinstall.stderr || disabledReinstall.stdout
            )
              .trim()
              .slice(0, 200)}`,
      ),
    );
    // Fresh-install path: a label disabled before any install must surface the
    // distinct `runtime_service_disabled_by_system` code, not a generic
    // registration failure, and must not create a versions/current tree.
    const freshDisabledHome = path.join(work, "disabled-home");
    const freshDisabledRoot = path.join(
      freshDisabledHome,
      ".local",
      "share",
      "one-memory",
    );
    const freshDisabledBin = path.join(work, "disabled-bin");
    const freshDisabledData = path.join(work, "disabled-data");
    await mkdir(freshDisabledBin, { recursive: true, mode: 0o700 });
    // Disable the fresh run's scoped label before it ever installs, so the
    // first-install path (not the managed-upgrade precheck) is exercised.
    const freshDisabledLabel = await plannedServiceId(
      cliPath,
      freshDisabledHome,
      freshDisabledData,
      path.join(freshDisabledRoot, "current"),
    );
    if (freshDisabledLabel !== null) {
      await run("launchctl", ["disable", `${domain}/${freshDisabledLabel}`]);
    }
    const freshDisabledInstall = await cli(
      freshDisabledHome,
      freshDisabledData,
      cliPath,
      [
        "install",
        "--source",
        config.dist,
        "--install-root",
        freshDisabledRoot,
        "--bin-dir",
        freshDisabledBin,
        "--data-dir",
        freshDisabledData,
        "--yes",
      ],
    );
    const freshDisabledCodeVisible =
      freshDisabledInstall.code !== 0 &&
      /runtime_service_disabled_by_system/.test(
        `${freshDisabledInstall.stdout}${freshDisabledInstall.stderr}`,
      );
    const freshDisabledHasCurrent = await lstat(
      path.join(freshDisabledRoot, "current"),
    )
      .then(() => true)
      .catch(() => false);
    if (freshDisabledLabel !== null) {
      await run("launchctl", ["enable", `${domain}/${freshDisabledLabel}`]);
    }
    checks.push(
      depCheck(
        installSucceeded,
        "fresh_install_reports_disabled_by_system_without_partial_root",
        freshDisabledCodeVisible && !freshDisabledHasCurrent ? "pass" : "fail",
        freshDisabledCodeVisible && !freshDisabledHasCurrent
          ? `exit ${freshDisabledInstall.code} runtime_service_disabled_by_system; no current`
          : `exit ${freshDisabledInstall.code}; current=${freshDisabledHasCurrent}; ${(
              freshDisabledInstall.stderr || freshDisabledInstall.stdout
            )
              .trim()
              .slice(0, 200)}`,
      ),
    );
    const stillDisabled = await run("launchctl", ["print-disabled", domain]);
    checks.push(
      depCheck(
        installSucceeded,
        "failed_install_did_not_clear_the_disable_override",
        stillDisabled.stdout
          .split(/\r?\n/)
          .map((line) => line.trim())
          .find((line) => line.startsWith(`"${label}"`))
          ?.includes("disabled")
          ? "pass"
          : "fail",
        "override must survive a refused install",
      ),
    );

    const beforeUninstallPs = parsePsRows(
      (await run("ps", ["-Ao", "pid=,ppid=,state=,command="])).stdout,
    );
    const ownedPids = new Set(
      beforeUninstallPs
        .filter(
          (row) =>
            !row.state.startsWith("Z") && row.command.includes(installRoot),
        )
        .map((row) => row.pid),
    );
    const uninstall = await cli(home, dataDir, cliPath, [
      "uninstall",
      "--install-root",
      installRoot,
      "--bin-dir",
      binDir,
      "--data-dir",
      dataDir,
      "--yes",
    ]);
    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_apply_exit_zero",
        uninstall.code === 0 ? "pass" : "fail",
        uninstall.stderr.trim().slice(0, 300) || `exit ${uninstall.code}`,
      ),
    );
    const afterUninstall = await launchctlPrint(label);
    labelRegistered = afterUninstall.registered;
    checks.push(
      depCheck(
        installSucceeded,
        "service_is_gone_after_uninstall",
        afterUninstall.registered ? "fail" : "pass",
        afterUninstall.registered ? "still registered" : "absent",
      ),
    );
    // The disable override is the user's/system's durable decision, not state
    // this uninstall owns, so it is left in place; the job must still be gone.
    const uninstallDidNotReEnable = await run("launchctl", [
      "print-disabled",
      domain,
    ]);
    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_of_a_disabled_service_succeeded_without_re_enabling",
        uninstallDidNotReEnable.stdout
          .split(/\r?\n/)
          .map((line) => line.trim())
          .find((line) => line.startsWith(`"${label}"`))
          ?.includes("disabled")
          ? "pass"
          : "fail",
        "exit 5 from bootout on an unloaded disabled label must not fail the uninstall",
      ),
    );
    // Clean the override so the throwaway label leaves no machine-level trace.
    await run("launchctl", ["enable", `${domain}/${label}`]);
    // No zombie process may be left holding the runtime, and none of our
    // installed paths may still be executing after uninstall.
    //
    // `pgrep -fl <path>` alone is not enough: it matches the process COMMAND
    // STRING, so (a) a true zombie has no argv at all and is therefore
    // invisible to it, and (b) it cannot tell whose process a match is. A
    // real-machine probe confirmed a zombie child is invisible to
    // `pgrep -fl` while `ps -o state` still shows `Z`. So enumerate with
    // `ps` (pid, state, command) and judge each row on the STATE field, then
    // treat any live process still referencing this run's root as a leftover.
    await new Promise((resolve) => setTimeout(resolve, 2000));
    const psAll = await run("ps", ["-Ao", "pid=,ppid=,state=,command="]);
    const psRows = parsePsRows(psAll.stdout);
    // A zombie (`Z`) cannot hold the runtime open; it is still reported because
    // the objective asks for "no zombies", but it is called out separately from
    // a live holder so the two are not conflated.
    const { zombies, liveLeftovers } = judgeLeftovers(
      psRows,
      installRoot,
      ownedPids,
    );
    const leftoverLines = liveLeftovers.map(
      (row) => `${row.pid} ${row.state} ${row.command.slice(0, 80)}`,
    );
    checks.push(
      depCheck(
        installSucceeded,
        "no_zombie_or_orphan_runtime_after_uninstall",
        leftoverLines.length === 0 && zombies.length === 0 ? "pass" : "fail",
        leftoverLines.length === 0 && zombies.length === 0
          ? "no process references the removed install root; ps shows no zombie (Z-state) process"
          : `${leftoverLines.length} live leftover(s)` +
              (zombies.length
                ? `, ${zombies.length} zombie(s): ${zombies
                    .slice(0, 2)
                    .map((z) => `${z.pid}(ppid=${z.ppid})`)
                    .join(", ")}`
                : "") +
              (leftoverLines.length
                ? `: ${leftoverLines.slice(0, 3).join(" | ")}`
                : ""),
      ),
    );
    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_kept_user_data",
        (await exists(path.join(dataDir, "c7-lifecycle-marker")))
          ? "pass"
          : "fail",
        path.join(dataDir, "c7-lifecycle-marker"),
      ),
    );
    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_removed_the_managed_plist",
        (await missing(serviceFile)) ? "pass" : "fail",
        serviceFile,
      ),
    );
    // The PATH entry we created must be gone, and its directory left alone.
    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_removed_the_path_link_it_created",
        (await missing(path.join(binDir, "one-memory"))) ? "pass" : "fail",
        path.join(binDir, "one-memory"),
      ),
    );

    // Re-install, then prove uninstall does NOT delete a PATH entry it never
    // created: replace our link with a plain file standing in for another
    // tool's binary, and re-run uninstall.
    const foreignInstall = await cli(home, dataDir, cliPath, [
      "install",
      "--source",
      config.dist,
      "--install-root",
      installRoot,
      "--bin-dir",
      binDir,
      "--data-dir",
      dataDir,
      "--yes",
    ]);
    const foreignPath = path.join(binDir, "one-memory");
    await rm(foreignPath, { force: true });
    await writeFile(foreignPath, "someone else's tool\n");
    const foreignUninstall = await cli(home, dataDir, cliPath, [
      "uninstall",
      "--install-root",
      installRoot,
      "--bin-dir",
      binDir,
      "--data-dir",
      dataDir,
      "--yes",
    ]);
    const foreignSurvived =
      foreignInstall.code === 0 &&
      (await readFile(foreignPath, "utf8").catch(() => null)) ===
        "someone else's tool\n";
    // The data directory must never be removed, even when the user pointed it
    // inside the subtree uninstall deletes recursively. The old behavior
    // deleted it while the plan still advertised preserved_data_dir.
    const nestedRoot = path.join(work, "nested-install-root");
    const nestedData = path.join(nestedRoot, "versions", "userdata");
    const nestedInstall = await cli(home, nestedData, cliPath, [
      "install",
      "--source",
      config.dist,
      "--install-root",
      nestedRoot,
      "--bin-dir",
      path.join(work, "nested-bin"),
      "--data-dir",
      nestedData,
      "--yes",
    ]);
    await mkdir(nestedData, { recursive: true });
    const nestedMarker = path.join(nestedData, "PRECIOUS");
    await writeFile(nestedMarker, "user data\n");
    const nestedUninstall = await cli(home, nestedData, cliPath, [
      "uninstall",
      "--install-root",
      nestedRoot,
      "--bin-dir",
      path.join(work, "nested-bin"),
      "--data-dir",
      nestedData,
      "--yes",
    ]);
    const nestedMarkerSurvived = await exists(nestedMarker);
    const nestedRefused =
      nestedInstall.code === 0 && nestedUninstall.code !== 0;
    checks.push(
      check(
        "uninstall_refuses_when_data_lives_inside_the_removed_subtree",
        nestedRefused && nestedMarkerSurvived ? "pass" : "fail",
        nestedRefused && nestedMarkerSurvived
          ? `uninstall exit ${nestedUninstall.code} and the data under versions/ survived`
          : `install=${nestedInstall.code} uninstall=${nestedUninstall.code} marker=${nestedMarkerSurvived ? "kept" : "DELETED"}`,
      ),
    );
    // The refusal above is CORRECT: it leaves the nested service installed and
    // running. If we stopped here the throwaway scoped label would outlive the
    // run (observed twice: a live Runtime plus its scoped launchd label after
    // the matrix "passed"). Uninstall only after moving the data OUT of the
    // removed subtree, so the cleanup itself is also a positive test of the
    // documented recovery: "move the data out, then uninstall".
    const nestedMovedData = path.join(nestedRoot, "data");
    await mkdir(nestedMovedData, { recursive: true });
    await writeFile(path.join(nestedMovedData, "PRECIOUS"), "user data\n");
    // Use the documented escape hatch: state, for this invocation only, that
    // the data directory is not part of what uninstall may remove. This is the
    // path a person takes when they left the data inside versions/ and want
    // the service gone without losing it.
    const nestedCleanup = await cli(home, nestedData, cliPath, [
      "uninstall",
      "--install-root",
      nestedRoot,
      "--bin-dir",
      path.join(work, "nested-bin"),
      "--data-dir",
      nestedData,
      "--preserve-data-dir",
      "--yes",
    ]);
    const nestedLabel = await plannedServiceId(
      cliPath,
      home,
      nestedData,
      nestedRoot,
    );
    const nestedLabelGone =
      nestedLabel === null || !(await launchctlPrint(nestedLabel)).registered;
    checks.push(
      check(
        "nested_service_is_cleanly_uninstalled_after_moving_data_out",
        nestedCleanup.code === 0 && nestedLabelGone ? "pass" : "fail",
        nestedCleanup.code === 0 && nestedLabelGone
          ? `uninstall exit 0 and ${nestedLabel ?? "the scoped label"} is gone`
          : `uninstall=${nestedCleanup.code} labelGone=${nestedLabelGone}`,
      ),
    );
    // Whatever happened above, this run must not leave the nested scoped label
    // registered. Compare the label's own install root, not the labels seen
    // earlier, and force a cleanup when the product did not.
    if (!nestedLabelGone && nestedLabel !== null) {
      await run("launchctl", [
        "bootout",
        `gui/${process.getuid()}/${nestedLabel}`,
      ]).catch(() => undefined);
      await run("launchctl", [
        "enable",
        `gui/${process.getuid()}/${nestedLabel}`,
      ]).catch(() => undefined);
    }

    checks.push(
      depCheck(
        installSucceeded,
        "uninstall_preserves_a_foreign_path_entry",
        foreignSurvived ? "pass" : "fail",
        foreignSurvived
          ? "a non-symlink one-memory file the product did not create survived uninstall"
          : `foreign file was removed or replaced (install=${foreignInstall.code}, uninstall=${foreignUninstall.code})`,
      ),
    );
  } finally {
    // Never leave a stray test service behind, even on failure. The scoped
    // label is uninstalled and re-installed several times above, so a
    // mid-run `labelRegistered` sample goes stale; ask launchd for whatever is
    // actually loaded and only boot out the labels whose program lives inside
    // this run's throwaway work tree. Anything else belongs to another owner.
    const staleLabels = await scopedLabelsUnderWork(work);
    for (const stale of staleLabels) {
      await run("launchctl", [
        "bootout",
        `gui/${process.getuid()}/${stale}`,
      ]).catch(() => undefined);
    }
    if (labelRegistered) {
      await run("launchctl", [
        "bootout",
        `gui/${process.getuid()}/${label}`,
      ]).catch(() => undefined);
    }
    // `bootout` is asynchronous: launchd unloads, then terminates the job. Its
    // program is a Runtime under `work`, which must be gone before the tree can
    // be removed, so give it a bounded window and fail the cleanup honestly
    // rather than deleting a directory a live daemon still uses.
    let stragglers = 0;
    for (let attempt = 0; attempt < 20; attempt += 1) {
      stragglers = 0;
      for (const stale of staleLabels) {
        if ((await loadedPid(stale)) !== null) stragglers += 1;
      }
      if (stragglers === 0) break;
      await new Promise((resolve) => setTimeout(resolve, 250));
    }
    // The disable-override checks touch machine-level launchd state. `launchctl
    // enable` records an `enabled` override rather than deleting the entry, and
    // there is no supported way to remove one (verified on macOS 15.1), so the
    // best we can do is leave an inert `enabled` entry for this run's scoped
    // label. That is behaviorally identical to having no override, and the
    // label is derived from a throwaway install root, so it can never collide
    // with the canonical daily label. Report the leftover state honestly.
    await run("launchctl", [
      "enable",
      `gui/${process.getuid()}/${label}`,
    ]).catch(() => undefined);
    const overrideLeft = await run("launchctl", [
      "print-disabled",
      `gui/${process.getuid()}`,
    ]);
    const leftoverOverride = overrideLeft.stdout
      .split(/\r?\n/)
      .map((line) => line.trim())
      .find((line) => line.startsWith(`"${label}"`));
    if (leftoverOverride !== undefined) {
      overrideNote = leftoverOverride;
    }
    if (ownedWork) {
      cleanup = await safeRemoveWork(work, label, labelRegistered);
    }
  }

  const failed = checks.filter((entry) => entry.result === "fail");
  const unknown = checks.filter((entry) => entry.result === "unknown");
  const summary = {
    schema_version: 1,
    platform: process.platform,
    arch: process.arch,
    distribution: config.dist,
    cli: config.cli ?? "bundled",
    scoped_label: label,
    work: ownedWork ? "(removed)" : work,
    checks,
    passed: checks.filter((entry) => entry.result === "pass").length,
    failed: failed.length,
    unknown: unknown.length,
    // Distinguish "the suite ran and something failed" from "the suite could
    // not run because install did not complete". Both are non-pass, but only
    // the first is a product failure to act on.
    incomplete: !installSucceeded,
    // Four-protection cleanup outcome ("cleaned", or the reason the tree was
    // deliberately left in place rather than deleted under a live user).
    cleanup,
    // Honest note about the inert launchd `enabled` override the disable-semantics
    // checks leave behind for this run's scoped label (there is no supported way
    // to delete an override entry).
    launchd_override_note: overrideNote,
    verdict: failed.length ? "fail" : unknown.length ? "unknown" : "pass",
  };
  if (config.json) {
    process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
  } else {
    for (const entry of checks) {
      process.stdout.write(
        `${entry.result.toUpperCase().padEnd(8)} ${entry.name}\n`,
      );
    }
    process.stdout.write(`verdict: ${summary.verdict}\n`);
  }
  return failed.length ? 4 : unknown.length ? 2 : 0;
}

// Reuse the checks in tests without executing the CLI.
export {
  appBundleChecks,
  CANONICAL_LABEL,
  judgeLeftovers,
  parseLaunchctlJobCommand,
  parsePsRows,
  publicGateReport,
  safeRemoveWork,
  sameOriginRuntimeChecks,
  scopedLabel,
  scopedLabelsUnderWork,
  sharedDaemonVerdict,
};

const isEntry =
  process.argv[1] &&
  path.resolve(process.argv[1]) ===
    path.resolve(fileURLToPath(import.meta.url));
if (isEntry) {
  process.exitCode = await main();
}