@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/upgrade/global-refresh.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/upgrade/global-refresh.mjs — keep the GLOBAL npm install of the SDK at
+ * the version the agent dir just upgraded to (design 2026-09-08, WP-M6 step 4).
+ *
+ * WHY. Every Claude Code session on a seat — the front-door session, a peer,
+ * a home-dir `claude` — resolves `maestro`, `cohort` and `cohort-mcp` from
+ * PATH, i.e. from `npm root -g`. autoupdate.sh installs the SDK LOCALLY in the
+ * agent dir, so without this step the global bins drift behind the agent dir
+ * on every hop. `planGlobalRefresh` is pure (version in, argv out);
+ * `refreshGlobalInstall` is the edge, and honours `MAESTRO_SKIP_GLOBAL_INSTALL=1`
+ * (every test sets it; a seat may set it to pin the global install by hand).
+ *
+ * @module lib/upgrade/global-refresh
+ */
+
+"use strict";
+
+import { spawnSync } from "node:child_process";
+
+export const SDK_PACKAGE = "@cohortapp/agent-sdk";
+export const SKIP_ENV = "MAESTRO_SKIP_GLOBAL_INSTALL";
+
+/**
+ * The version of `pkg` in `npm ls -g <pkg> --json --depth=0` output; "" when
+ * absent or unparseable. Tolerates the tree-text form as a fallback.
+ * @param {string} out
+ * @param {string} [pkg]
+ * @returns {string}
+ */
+export function parseGlobalVersion(out, pkg = SDK_PACKAGE) {
+  const s = String(out || "").trim();
+  if (!s) return "";
+  try {
+    const j = JSON.parse(s);
+    const v = j && j.dependencies && j.dependencies[pkg] && j.dependencies[pkg].version;
+    if (typeof v === "string" && v) return v;
+  } catch { /* not JSON: try the tree form below */ }
+  const m = s.match(new RegExp(`${pkg.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}@(\\d+\\.\\d+\\.\\d+[^\\s]*)`));
+  return m ? m[1] : "";
+}
+
+/**
+ * Decide whether to refresh the global install. Pure.
+ *
+ * @param {object} o
+ * @param {string} o.version         the version the agent dir now runs (target)
+ * @param {string} [o.globalVersion] what `npm ls -g` reports ("" = not installed)
+ * @param {boolean} [o.skip]         MAESTRO_SKIP_GLOBAL_INSTALL=1
+ * @param {string} [o.pkg]
+ * @returns {{action:"skip"|"none"|"install", reason:string, argv:string[]|null}}
+ */
+export function planGlobalRefresh(o = {}) {
+  const pkg = o.pkg || SDK_PACKAGE;
+  const version = String(o.version || "").trim();
+  const argv = version ? ["npm", "install", "-g", `${pkg}@${version}`, "--no-audit", "--no-fund"] : null;
+  if (o.skip) return { action: "skip", reason: `${SKIP_ENV}=1`, argv };
+  if (!version) return { action: "skip", reason: "target version unknown", argv: null };
+  const cur = String(o.globalVersion || "").trim();
+  if (cur === version) return { action: "none", reason: `global install already at ${version}`, argv };
+  return { action: "install", reason: cur ? `global install is ${cur}, agent dir is ${version}` : "not installed globally", argv };
+}
+
+/** Default exec: {status, stdout, stderr}; never throws. */
+function defaultExec(cmd, args, opts = {}) {
+  try {
+    const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 180_000, ...opts });
+    if (r.error) return { status: 127, stdout: "", stderr: String(r.error.message || r.error) };
+    return { status: r.status == null ? 1 : r.status, stdout: r.stdout || "", stderr: r.stderr || "" };
+  } catch (err) {
+    return { status: 127, stdout: "", stderr: String((err && err.message) || err) };
+  }
+}
+
+/**
+ * Read the global version through `exec`. Edge; "" on any failure.
+ * @param {{exec?:Function, pkg?:string}} [o]
+ * @returns {string}
+ */
+export function readGlobalVersion(o = {}) {
+  const exec = o.exec || defaultExec;
+  const pkg = o.pkg || SDK_PACKAGE;
+  // `npm ls -g` exits 1 when the package is absent AND still prints the JSON
+  // that says so; the stdout is the answer either way.
+  const r = exec("npm", ["ls", "-g", pkg, "--json", "--depth=0"], { timeout: 20_000 });
+  return parseGlobalVersion(r && r.stdout, pkg);
+}
+
+/**
+ * Plan + run the refresh. Edge. Never throws; the result is a step row.
+ * @param {{version:string, env?:object, exec?:Function, pkg?:string}} o
+ * @returns {{ok:boolean, action:string, detail:string, argv:string[]|null}}
+ */
+export function refreshGlobalInstall(o = {}) {
+  const env = o.env || process.env;
+  const exec = o.exec || defaultExec;
+  const skip = String(env[SKIP_ENV] || "") === "1";
+  const globalVersion = skip ? "" : readGlobalVersion({ exec, pkg: o.pkg });
+  const plan = planGlobalRefresh({ version: o.version, globalVersion, skip, pkg: o.pkg });
+  if (plan.action !== "install") {
+    return { ok: true, action: plan.action, detail: `${plan.action === "skip" ? "skipped" : "no change"} (${plan.reason})${plan.argv && plan.action === "skip" ? `: ${plan.argv.join(" ")}` : ""}`, argv: plan.argv };
+  }
+  const r = exec(plan.argv[0], plan.argv.slice(1), { timeout: 180_000 });
+  if (r.status === 0) return { ok: true, action: "install", detail: `${plan.argv.join(" ")} (${plan.reason})`, argv: plan.argv };
+  const err = String(r.stderr || "").trim().split("\n").filter(Boolean).pop() || `exit ${r.status}`;
+  return { ok: false, action: "install", detail: `${plan.argv.join(" ")} failed: ${err} — run it by hand`, argv: plan.argv };
+}
+
+export default { planGlobalRefresh, parseGlobalVersion, readGlobalVersion, refreshGlobalInstall, SDK_PACKAGE, SKIP_ENV };

package/lib/upgrade/global-refresh.test.mjs

@@ -0,0 +1,65 @@
+/**
+ * global-refresh.test.mjs — planGlobalRefresh is pure; refreshGlobalInstall
+ * never reaches a real npm (exec is injected AND MAESTRO_SKIP_GLOBAL_INSTALL=1
+ * is honoured).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { planGlobalRefresh, parseGlobalVersion, refreshGlobalInstall, readGlobalVersion } from "./global-refresh.mjs";
+
+const ARGV = ["npm", "install", "-g", "@cohortapp/agent-sdk@2.12.0", "--no-audit", "--no-fund"];
+
+test("planGlobalRefresh: install when absent or behind, none when equal, skip under MAESTRO_SKIP_GLOBAL_INSTALL", () => {
+  assert.deepEqual(planGlobalRefresh({ version: "2.12.0", globalVersion: "" }), { action: "install", reason: "not installed globally", argv: ARGV });
+  assert.deepEqual(planGlobalRefresh({ version: "2.12.0", globalVersion: "2.11.17" }), { action: "install", reason: "global install is 2.11.17, agent dir is 2.12.0", argv: ARGV });
+  assert.equal(planGlobalRefresh({ version: "2.12.0", globalVersion: "2.12.0" }).action, "none");
+  const s = planGlobalRefresh({ version: "2.12.0", globalVersion: "1.0.0", skip: true });
+  assert.equal(s.action, "skip");
+  assert.deepEqual(s.argv, ARGV, "the skipped command is still reported so an operator can run it by hand");
+  assert.equal(planGlobalRefresh({ version: "", globalVersion: "1.0.0" }).action, "skip");
+});
+
+test("parseGlobalVersion reads npm ls --json, tolerates the tree form and the not-installed shape", () => {
+  assert.equal(parseGlobalVersion(JSON.stringify({ dependencies: { "@cohortapp/agent-sdk": { version: "2.11.17" } } })), "2.11.17");
+  assert.equal(parseGlobalVersion(JSON.stringify({ name: "lib", dependencies: {} })), "");
+  assert.equal(parseGlobalVersion("/opt/homebrew/lib\n└── @cohortapp/agent-sdk@2.12.0\n"), "2.12.0");
+  assert.equal(parseGlobalVersion(""), "");
+  assert.equal(parseGlobalVersion("not json"), "");
+});
+
+function recorder(responses) {
+  const calls = [];
+  const exec = (cmd, args) => { calls.push([cmd, ...args]); return responses(cmd, args); };
+  exec.calls = calls;
+  return exec;
+}
+
+test("refreshGlobalInstall: with MAESTRO_SKIP_GLOBAL_INSTALL=1 nothing is executed and the row says what was skipped", () => {
+  const exec = recorder(() => ({ status: 0, stdout: "", stderr: "" }));
+  const r = refreshGlobalInstall({ version: "2.12.0", env: { MAESTRO_SKIP_GLOBAL_INSTALL: "1" }, exec });
+  assert.equal(r.ok, true);
+  assert.equal(r.action, "skip");
+  assert.match(r.detail, /npm install -g @cohortapp\/agent-sdk@2\.12\.0 --no-audit --no-fund/);
+  assert.deepEqual(exec.calls, [], "no npm call at all under the skip flag");
+});
+
+test("refreshGlobalInstall: runs the pinned install through exec when behind; reports a failure as ok:false with the tail of stderr", () => {
+  const behind = recorder((cmd, args) => (args[0] === "ls"
+    ? { status: 1, stdout: JSON.stringify({ dependencies: { "@cohortapp/agent-sdk": { version: "2.11.17" } } }), stderr: "" }
+    : { status: 0, stdout: "", stderr: "" }));
+  const r = refreshGlobalInstall({ version: "2.12.0", env: {}, exec: behind });
+  assert.equal(r.ok, true);
+  assert.deepEqual(behind.calls[1], ARGV);
+
+  const same = recorder(() => ({ status: 0, stdout: JSON.stringify({ dependencies: { "@cohortapp/agent-sdk": { version: "2.12.0" } } }), stderr: "" }));
+  const n = refreshGlobalInstall({ version: "2.12.0", env: {}, exec: same });
+  assert.equal(n.action, "none");
+  assert.equal(same.calls.length, 1, "only the read");
+
+  const fail = recorder((cmd, args) => (args[0] === "ls" ? { status: 1, stdout: "{}", stderr: "" } : { status: 243, stdout: "", stderr: "npm ERR! code EACCES\nnpm ERR! permission denied\n" }));
+  const f = refreshGlobalInstall({ version: "2.12.0", env: {}, exec: fail });
+  assert.equal(f.ok, false);
+  assert.match(f.detail, /permission denied/);
+  assert.equal(readGlobalVersion({ exec: fail }), "");
+});

package/lib/upgrade/launchd-reconcile.mjs

@@ -0,0 +1,327 @@
+/**
+ * lib/upgrade/launchd-reconcile.mjs — bring ~/Library/LaunchAgents in line with
+ * the plists generate-plists.sh just rendered (design 2026-09-08, WP-M6 step 2).
+ *
+ * WHY THIS EXISTS. On every existing seat the OLD autoupdate.sh runs the NEW
+ * package's `maestro upgrade` on the first hop. Nothing else on that seat knows
+ * the front-door session job (`ai.maestro.<first>-session`) exists, so
+ * `upgrade()` itself has to install it — and, more generally, has to make the
+ * installed job set match the generated one without an operator.
+ *
+ * `planLaunchdReconcile` is PURE: it takes the generated labels, the installed
+ * labels (a plist file present under LaunchAgents), the loaded labels (from
+ * launchd), a `sameContent(label)` predicate and an optional `hold` reason,
+ * and returns the actions. `applyLaunchdReconcile` is the edge: it copies,
+ * chmods, and drives `launchctl` through an injected `exec`, and reports per
+ * action — never throws.
+ *
+ * Invariants (pinned by launchd-reconcile.test.mjs):
+ *   · a generated label with no installed file → install (copy, chmod 600,
+ *     `launchctl bootstrap gui/<uid> <plist>`; if launchd says it is already
+ *     loaded that is success; otherwise fall back to `launchctl load`);
+ *   · an installed file whose content differs → REWRITE THE FILE ONLY. Never
+ *     `kickstart -k`: launchd keeps the definition it loaded and does not
+ *     re-read a rewritten plist until bootout + bootstrap or the next login,
+ *     so a kickstart would fire a calendar/interval job out of schedule for
+ *     nothing — and for `-autoupdate` it would SIGKILL the very job this
+ *     upgrade is running inside (autoupdate.sh → node upgrade), mid-steps.
+ *     If the job is not loaded, bootstrap it;
+ *   · same content but not loaded → bootstrap (a generated job is meant to run)
+ *     — UNLESS the seat is held: `.emergency-stop` / `state/EMERGENCY_STOP`
+ *     (scripts/emergency-stop.sh unloaded every job on purpose) or the
+ *     autoupdate kill-switch (`~/.maestro-no-autoupdate`, `.no-autoupdate`).
+ *     A held seat gets its files written and nothing bootstrapped; every
+ *     held row says why;
+ *   · installed but no longer generated → reported as an orphan, never booted
+ *     out (`launchctl bootout` is not something an upgrade does).
+ *
+ * "Loaded" is measured in the GUI domain (`launchctl print gui/<uid>`), because
+ * a domain-less `launchctl list` from ssh — the documented way to administer a
+ * mac-mini seat — does not show gui-domain agents and would plan every job as
+ * "load". `launchctl list` is only the fallback when `print` is unavailable.
+ *
+ * @module lib/upgrade/launchd-reconcile
+ */
+
+"use strict";
+
+import { copyFileSync, chmodSync, mkdirSync, readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/** Only plists with these label prefixes are ours to touch or report. */
+export const MAESTRO_LABEL_PREFIXES = Object.freeze(["ai.maestro.", "ai.adaptic."]);
+
+/** Why a replaced-while-loaded job is not restarted. Shown per row. */
+export const REWRITE_ONLY_NOTE = "file rewritten; launchd keeps the loaded definition until next login (or: launchctl bootout gui/<uid>/<label> && launchctl bootstrap gui/<uid> <plist>)";
+
+/** `ai.maestro.ivy-session.plist` → `ai.maestro.ivy-session`. */
+export function labelOf(name) {
+  return String(name || "").replace(/\.plist$/, "");
+}
+
+export function isMaestroLabel(label) {
+  const l = String(label || "");
+  return MAESTRO_LABEL_PREFIXES.some((p) => l.startsWith(p));
+}
+
+/**
+ * Parse `launchctl list` output into labels. The label is the last whitespace
+ * column of every row after the header; a job that is loaded but not running
+ * shows PID `-` and still counts as loaded.
+ * @param {string} out
+ * @returns {string[]}
+ */
+export function parseLaunchctlList(out) {
+  return String(out || "")
+    .split("\n")
+    .map((l) => l.trim().split(/\s+/).pop())
+    .filter((l) => l && l !== "Label");
+}
+
+/**
+ * Parse `launchctl print gui/<uid>` output into the labels of its
+ * `services = { … }` block (one `<pid> <status> <label>` row per service; the
+ * label is the last column). Returns null when there is no services block —
+ * the caller then falls back to `launchctl list`.
+ * @param {string} out
+ * @returns {string[]|null}
+ */
+export function parseLaunchctlPrintServices(out) {
+  const lines = String(out || "").split("\n");
+  const start = lines.findIndex((l) => /^\s*services\s*=\s*\{\s*$/.test(l));
+  if (start < 0) return null;
+  const labels = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*\}\s*$/.test(line)) break;
+    const label = line.trim().split(/\s+/).pop();
+    if (label) labels.push(label);
+  }
+  return labels;
+}
+
+/**
+ * Decide what to do for every generated and installed label. Pure.
+ *
+ * @param {object} o
+ * @param {string[]} o.generated     labels rendered into scripts/local-triggers/plists
+ * @param {string[]} o.installed     maestro labels with a file in ~/Library/LaunchAgents
+ * @param {string[]} [o.loaded]      labels launchd reports as loaded
+ * @param {(label:string)=>boolean} [o.sameContent]  generated file == installed file
+ * @param {string|null} [o.hold]     when set, nothing is bootstrapped and every held row carries this reason
+ * @returns {{actions: Array<{label:string, action:"install"|"replace"|"load"|"unchanged"|"orphan", bootstrap:boolean, held:boolean, reason:string}>, summary: {install:number, replace:number, load:number, unchanged:number, orphan:number, held:number}, hold:string|null}}
+ */
+export function planLaunchdReconcile(o = {}) {
+  const generated = uniq((o.generated || []).map(labelOf));
+  const installed = new Set((o.installed || []).map(labelOf));
+  const loaded = new Set((o.loaded || []).map(labelOf));
+  const sameContent = typeof o.sameContent === "function" ? o.sameContent : () => false;
+  const hold = o.hold ? String(o.hold) : null;
+  const actions = [];
+  const want = (label, action, reason) => {
+    // `bootstrap` is what the plan WANTS; a held seat keeps the file write and drops the bootstrap.
+    if (hold) actions.push({ label, action, bootstrap: false, held: true, reason: `${reason}; held: ${hold}` });
+    else actions.push({ label, action, bootstrap: true, held: false, reason });
+  };
+
+  for (const label of generated) {
+    const isLoaded = loaded.has(label);
+    if (!installed.has(label)) { want(label, "install", "not installed"); continue; }
+    let same = false;
+    try { same = !!sameContent(label); } catch { same = false; /* an unreadable file is treated as different: rewriting it is the safe direction */ }
+    if (!same) {
+      if (!isLoaded) want(label, "replace", "content differs; not loaded");
+      else actions.push({ label, action: "replace", bootstrap: false, held: false, reason: `content differs; ${REWRITE_ONLY_NOTE}` });
+      continue;
+    }
+    if (!isLoaded) want(label, "load", "up to date; not loaded");
+    else actions.push({ label, action: "unchanged", bootstrap: false, held: false, reason: "up to date; loaded" });
+  }
+
+  const gen = new Set(generated);
+  for (const label of uniq([...installed])) {
+    if (gen.has(label) || !isMaestroLabel(label)) continue;
+    actions.push({ label, action: "orphan", bootstrap: false, held: false, reason: "installed but no longer generated; left alone (never booted out)" });
+  }
+
+  const summary = { install: 0, replace: 0, load: 0, unchanged: 0, orphan: 0, held: 0 };
+  for (const a of actions) {
+    summary[a.action] = (summary[a.action] || 0) + 1;
+    if (a.held) summary.held++;
+  }
+  return { actions, summary, hold };
+}
+
+function uniq(arr) {
+  return [...new Set(arr.filter(Boolean))];
+}
+
+/** Default `exec`: spawnSync shaped as {status, stdout, stderr}; never throws. */
+export function defaultExec(cmd, args, opts = {}) {
+  try {
+    const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20_000, ...opts });
+    if (r.error) return { status: 127, stdout: "", stderr: String(r.error.message || r.error) };
+    return { status: r.status == null ? 1 : r.status, stdout: r.stdout || "", stderr: r.stderr || "" };
+  } catch (err) {
+    return { status: 127, stdout: "", stderr: String((err && err.message) || err) };
+  }
+}
+
+/** The uid whose gui domain the seat's agents live in. */
+export function defaultUid() {
+  return typeof process.getuid === "function" ? process.getuid() : 501;
+}
+
+/**
+ * The seat's hold marker, if any: the emergency stop or the autoupdate
+ * kill-switch. Edge (fs). Returns a short reason naming the file, or null.
+ * @param {{cwd:string, home:string}} o
+ * @returns {string|null}
+ */
+export function readHoldReason(o = {}) {
+  const candidates = [
+    [join(o.cwd, ".emergency-stop"), "emergency stop (.emergency-stop)"],
+    [join(o.cwd, "state", "EMERGENCY_STOP"), "emergency stop (state/EMERGENCY_STOP)"],
+    [join(o.home, ".maestro-no-autoupdate"), "autoupdate kill-switch (~/.maestro-no-autoupdate)"],
+    [join(o.cwd, ".no-autoupdate"), "autoupdate kill-switch (.no-autoupdate)"],
+  ];
+  for (const [p, reason] of candidates) {
+    try { if (existsSync(p)) return reason; } catch { /* unreadable → not held */ }
+  }
+  return null;
+}
+
+/**
+ * The labels launchd has loaded for this user, measured in the gui domain.
+ * Edge. `launchctl print gui/<uid>` is the truth from any context (ssh
+ * included); a domain-less `launchctl list` is the fallback.
+ * @param {{exec?:Function, uid?:number}} o
+ * @returns {{loaded:string[], ok:boolean, via:"print"|"list"|"none"}}
+ */
+export function readLoadedLabels(o = {}) {
+  const exec = o.exec || defaultExec;
+  const uid = Number.isFinite(o.uid) ? o.uid : defaultUid();
+  const p = exec("launchctl", ["print", `gui/${uid}`]);
+  if (p && p.status === 0) {
+    const labels = parseLaunchctlPrintServices(p.stdout);
+    if (labels) return { loaded: labels, ok: true, via: "print" };
+  }
+  const l = exec("launchctl", ["list"]);
+  if (l && l.status === 0) return { loaded: parseLaunchctlList(l.stdout), ok: true, via: "list" };
+  return { loaded: [], ok: false, via: "none" };
+}
+
+/**
+ * Is one label loaded in gui/<uid>? Edge. Used after a failed bootstrap to
+ * tell "already loaded" (success) from "could not load" (fall back / fail).
+ */
+export function isLabelLoaded(label, o = {}) {
+  const exec = o.exec || defaultExec;
+  const uid = Number.isFinite(o.uid) ? o.uid : defaultUid();
+  const r = exec("launchctl", ["print", `gui/${uid}/${label}`]);
+  return !!(r && r.status === 0 && !/Could not find service/i.test(`${r.stdout}\n${r.stderr}`));
+}
+
+/**
+ * Read the two label sets and the loaded set from disk / launchctl. Edge.
+ * @param {{generatedDir:string, launchAgentsDir:string, exec?:Function, uid?:number}} o
+ * @returns {{generated:string[], installed:string[], loaded:string[], sameContent:(label:string)=>boolean, launchctlOk:boolean, loadedVia:string}}
+ */
+export function readLaunchdState(o = {}) {
+  const exec = o.exec || defaultExec;
+  const list = (dir) => {
+    try { return readdirSync(dir).filter((n) => n.endsWith(".plist")); } catch { return []; /* absent dir → nothing installed/generated */ }
+  };
+  const generated = list(o.generatedDir).map(labelOf);
+  const installed = list(o.launchAgentsDir).map(labelOf).filter(isMaestroLabel);
+  const r = readLoadedLabels({ exec, uid: o.uid });
+  const sameContent = (label) => {
+    try {
+      return readFileSync(join(o.generatedDir, `${label}.plist`)).equals(readFileSync(join(o.launchAgentsDir, `${label}.plist`)));
+    } catch { return false; /* unreadable on either side → treat as different */ }
+  };
+  return { generated, installed, loaded: r.loaded, sameContent, launchctlOk: r.ok, loadedVia: r.via };
+}
+
+/**
+ * Apply a plan. Edge: copies, chmods, and calls `launchctl` through `exec`.
+ * Each action reports independently; a failure never throws or stops the rest.
+ * Never kickstarts, never boots out.
+ *
+ * @param {object} o
+ * @param {ReturnType<typeof planLaunchdReconcile>} o.plan
+ * @param {string} o.generatedDir
+ * @param {string} o.launchAgentsDir
+ * @param {number} o.uid
+ * @param {Function} [o.exec]
+ * @returns {{ok:boolean, results:Array<{label:string, action:string, ok:boolean, detail:string}>}}
+ */
+export function applyLaunchdReconcile(o = {}) {
+  const exec = o.exec || defaultExec;
+  const target = `gui/${o.uid}`;
+  const results = [];
+  let ok = true;
+
+  const copyPlist = (label) => {
+    const src = join(o.generatedDir, `${label}.plist`);
+    const dst = join(o.launchAgentsDir, `${label}.plist`);
+    mkdirSync(o.launchAgentsDir, { recursive: true });
+    copyFileSync(src, dst);
+    chmodSync(dst, 0o600);
+    return dst;
+  };
+  const bootstrap = (label, dst) => {
+    const b = exec("launchctl", ["bootstrap", target, dst]);
+    if (b.status === 0) return { ok: true, via: "bootstrap" };
+    // launchd answers 5 (EIO) both for "already loaded" and for a bad plist —
+    // ask it which before touching the domain-less `load`, which from ssh
+    // would register a second copy of the job in the wrong domain.
+    if (isLabelLoaded(label, { exec, uid: o.uid })) return { ok: true, via: `bootstrap ${b.status} but already loaded in ${target}` };
+    const l = exec("launchctl", ["load", dst]);
+    if (l.status === 0) return { ok: true, via: "load" };
+    return { ok: false, detail: `bootstrap ${b.status}${trim(b.stderr)}; load ${l.status}${trim(l.stderr)}` };
+  };
+
+  for (const a of o.plan.actions) {
+    const row = { label: a.label, action: a.action, ok: true, detail: a.reason };
+    try {
+      if (a.action === "install" || a.action === "replace" || a.action === "load") {
+        const dst = a.action === "load" ? join(o.launchAgentsDir, `${a.label}.plist`) : copyPlist(a.label);
+        if (a.bootstrap) {
+          const r = bootstrap(a.label, dst);
+          row.ok = r.ok;
+          row.detail = r.ok ? `${a.action}: loaded via launchctl ${r.via}` : `${a.action}: file written but not loaded — ${r.detail}`;
+        } else if (a.held) {
+          row.detail = `${a.action === "load" ? "left as is" : "file written"}; ${a.reason}`;
+        } else if (a.action === "replace") {
+          row.detail = `replaced (file only): ${a.reason}`;
+        }
+      }
+    } catch (err) {
+      row.ok = false;
+      row.detail = `${a.action} failed: ${(err && err.message) || err}`;
+    }
+    if (!row.ok) ok = false;
+    results.push(row);
+  }
+  return { ok, results };
+}
+
+function trim(s) {
+  const t = String(s || "").trim().split("\n")[0];
+  return t ? ` (${t})` : "";
+}
+
+/** One-line rendering of a result row for the upgrade summary. */
+export function formatReconcileRow(r) {
+  return `${r.ok ? "✓" : "✗"} ${r.label}: ${r.detail}`;
+}
+
+/** Labels present in a directory of plists (helper for verify). */
+export function listPlistLabels(dir) {
+  if (!existsSync(dir)) return [];
+  try { return readdirSync(dir).filter((n) => n.endsWith(".plist")).map((n) => labelOf(basename(n))); } catch { return []; /* unreadable dir → nothing generated/installed */ }
+}
+
+export default { planLaunchdReconcile, applyLaunchdReconcile, readLaunchdState, readLoadedLabels, readHoldReason, isLabelLoaded, parseLaunchctlList, parseLaunchctlPrintServices, labelOf, isMaestroLabel, listPlistLabels, formatReconcileRow, REWRITE_ONLY_NOTE };