@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/dist/cli.js

@@ -19,13 +19,14 @@ import { Cron } from "croner";
 import { existsSync, readFileSync, writeFileSync, appendFileSync, unlinkSync, mkdirSync, chmodSync, readdirSync, rmSync, statSync, realpathSync, } from "node:fs";
 import { homedir, totalmem, freemem, userInfo } from "node:os";
 import { fileURLToPath } from "node:url";
-import { spawn, execSync, execFileSync } from "node:child_process";
+import { spawn, spawnSync, execSync, execFileSync } from "node:child_process";
 import { getAgendHome, getTmuxSocketName } from "./paths.js";
 import { hasPausedMarker } from "./pause-marker.js";
 import { COMPLETION_SHELLS, completionScript } from "./completion.js";
 import { getUpdateSelector, isExactVersion, isUnrequestedDowngrade, lookupTargetVersion, reportUpdateRestart, shouldSkipUpdate, runningFleetPredatesInstall, processStartMs, } from "./update-check.js";
 import { clearUpdateMarker, markUpdateInProgress, setUpdateProgressStage } from "./update-marker.js";
-import { describeSignalSource, gateFleetControl, recordInstanceControl, withOrigin } from "./fleet-control-audit.js";
+import { describeSignalSource, forceAllowed, gateFleetControl, recordInstanceControl, withOrigin } from "./fleet-control-audit.js";
+import { FLEET_STOP_TIMEOUT_MS, stopDetachedOwner, systemdStopTimeoutMs, detachedProcessStart, detachedProcessExited } from "./fleet-stop-budget.js";
 import { acquireFleetLock, isFleetStartCommandLine, readProcessCommandLine, releaseProcessFleetLock, setProcessFleetLock } from "./fleet-lock.js";
 import { limitFleetCoreDumps } from "./coredump-filter.js";
 import { SYSTEMD_RESTART_TIMEOUT_MS } from "./service-installer.js";
@@ -36,6 +37,7 @@ import { DeliveryOutbox, deliveryStatusSelector } from "./delivery-outbox.js";
 import { DeliveryStatusArgs } from "./outbound-schemas.js";
 import { requestCpuProfile } from "./profile-control.js";
 import { requestSettingsConfirmation } from "./settings-control.js";
+import { canonicalCliEntry, selfCommand } from "./cli-entry.js";
 /** Prefix tmux args with -L when socket isolation is active. */
 function tmuxArgs(args) {
     const socket = getTmuxSocketName();
@@ -44,6 +46,39 @@ function tmuxArgs(args) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const DATA_DIR = getAgendHome();
+/** Real-filesystem, real-process deps for the launchd plan (service-plan.ts) and its activation. */
+function planDeps() {
+    return {
+        run: (command, args) => {
+            const r = spawnSync(command, args, { encoding: "utf-8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"] });
+            return { status: r.status, signal: r.signal, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+        },
+        readFile: (path) => { try {
+            return readFileSync(path, "utf-8");
+        }
+        catch {
+            return null;
+        } },
+        writeFile: (path, content) => writeFileSync(path, content),
+        removeFile: (path) => { try {
+            unlinkSync(path);
+        }
+        catch { /* absent */ } },
+        realpath: (path) => { try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        } },
+        isExecutable: (path) => { try {
+            return statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+        }
+        catch {
+            return false;
+        } },
+        now: () => new Date(),
+    };
+}
 const FLEET_CONFIG_PATH = join(DATA_DIR, "fleet.yaml");
 // CLI commands run outside FleetManager. Honor an explicit fleet locale while
 // keeping the historical English CLI default when config is missing/unset.
@@ -1007,13 +1042,20 @@ backend
         const svcPath = join(homedir(), ".config/systemd/user/com.agend.fleet.service");
         if (existsSync(svcPath)) {
             const svc = readFileSync(svcPath, "utf-8");
-            const match = svc.match(/ExecStart=(\S+)/);
-            const svcBin = match?.[1] ?? "";
-            const currentBin = es("which agend", { stdio: "pipe" }).toString().trim();
-            if (svcBin === currentBin)
+            // The CLI the unit starts — `<entry> fleet start`, or `<node> <entry> fleet start` — against this CLI's own
+            // canonical entry (#1450: `agend` on PATH is the sh launcher, never what a unit records).
+            const { unitCliEntry } = await import("./service-installer.js");
+            const svcEntry = unitCliEntry(svc);
+            let svcReal = svcEntry;
+            try {
+                svcReal = realpathSync(svcEntry);
+            }
+            catch { /* reported as is */ }
+            const current = canonicalCliEntry();
+            if (svcReal === current)
                 ok(`service ExecStart${" ".repeat(3)} matches current binary`);
             else
-                fail(`service ExecStart${" ".repeat(3)} ${svcBin} ≠ ${currentBin}`);
+                fail(`service ExecStart${" ".repeat(3)} ${svcEntry || "(none)"} ≠ ${current}`);
             // Check Restart=on-failure
             if (svc.includes("Restart=on-failure")) {
                 ok(`service restart${" ".repeat(5)} Restart=on-failure configured`);
@@ -1438,6 +1480,9 @@ program
             }
             process.exitCode = 1;
         }
+        if (restartOutcome === "pending")
+            process.exitCode = 75;
+        return restartOutcome;
     };
     const nvmSh = join(homedir(), ".nvm", "nvm.sh");
     /**
@@ -1447,7 +1492,9 @@ program
      * (process.argv[1] may be another checkout). A failed target check leaves the running fleet alone.
      */
     const activateVerified = async (verified, viaNvm) => {
-        const { newAgendInvocation } = await import("./update-install.js");
+        const { newAgendInvocation, retireSystemCopy, activationSettled } = await import("./update-install.js");
+        // What the restart came to — carried, never inferred from the exit code (pending ≠ restarted).
+        let restartResult = null;
         const { activateService } = await import("./service-activation.js");
         const { getServicePath, getSystemServicePath, detectPlatform } = await import("./service-installer.js");
         const { accessSync, constants } = await import("node:fs");
@@ -1455,10 +1502,18 @@ program
         // The authoritative manager, chosen as `agend restart` chooses: system unit > user unit / launchd plist > none.
         const systemUnit = getSystemServicePath();
         const ownService = systemUnit ? null : getServicePath();
-        const manager = systemUnit ? { kind: "systemd", unit: "agend", user: false }
+        const manager = systemUnit ? { kind: "systemd", unit: "agend", user: false, unitPath: systemUnit }
             : ownService && detectPlatform() === "macos" ? { kind: "launchd", label: "com.agend.fleet", plistPath: ownService, domain: `gui/${process.getuid?.() ?? 501}` }
-                : ownService ? { kind: "systemd", unit: "com.agend.fleet", user: true }
+                : ownService ? { kind: "systemd", unit: "com.agend.fleet", user: true, unitPath: ownService }
                     : { kind: "detached" };
+        // C6: a failure before the fleet runs the new install puts the previous package back too (taken before npm).
+        const { restorePackagePreimage, prunePreimages } = await import("./package-preimage.js");
+        const rollback = verified.rollback;
+        const restoreChecked = rollback?.preimage ? () => {
+            const back = restorePackagePreimage(rollback.root, rollback.prefix, rollback.preimage);
+            return { ok: back.ok, message: back.ok ? `The previous package (v${rollback.preimage.version}) is back in place` : `The previous package could NOT be put back: ${back.reason}` };
+        } : undefined;
+        const restorePackage = restoreChecked ? () => restoreChecked().message : undefined;
         const capture = (command, args) => {
             const result = spawnSync(command, args, { encoding: "utf-8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"] });
             return { status: result.status, signal: result.signal, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
@@ -1505,16 +1560,47 @@ program
                     spawnSync(newAgend.command, [...newAgend.args, "completion", "install", "--refresh"], { encoding: "utf-8", timeout: 15_000, stdio: "ignore" });
                 }
                 catch { /* cosmetic */ }
-                restartFleetForUpdate(newAgend.command, newAgend.args, verified.version);
+                restartResult = restartFleetForUpdate(newAgend.command, newAgend.args, verified.version);
+                return restartResult;
             },
             log: message => console.log(message),
+            restorePackage,
+            systemdRecovery: restoreChecked ? { restorePackage: restoreChecked } : undefined,
         });
+        // Settled: after a success only this transition's preimage is kept (for a repair); a failure consumed it.
+        if (activationSettled(outcome, restartResult) && rollback)
+            prunePreimages(rollback.prefix, rollback.preimage);
+        // nvm transition: the old system copy is what the previous service ran. Only once the fleet POSITIVELY runs the
+        // new install (activationSettled) is it removed; pending, failed or refused, it stays, so the old unit still starts.
+        if (verified.retireSystemCopy) {
+            if (activationSettled(outcome, restartResult)) {
+                const retireResult = retireSystemCopy({ run: (command, args) => capture(command, args), log: message => console.log(message) }, verified.npmPath);
+                if (!retireResult.ok) {
+                    console.error(`  ✗ Old system install was not removed: ${retireResult.reason}`);
+                    process.exitCode = 1;
+                }
+            }
+            else {
+                console.log("  Note: the old system install was kept, since the new one is not running yet.");
+            }
+        }
+        // The refresh above (`install --no-activate`) records a launchd plan; this activation consumed it, whatever it
+        // came to — never leave one for a later `agend restart` to act on.
+        if (manager.kind === "launchd") {
+            const { planPath } = await import("./service-plan.js");
+            planDeps().removeFile(planPath(DATA_DIR));
+        }
         if (outcome.ok && outcome.via === "launchd-activation") {
             console.log("  ✓ Service restarted (launchd loaded the verified job)");
             // The new fleet clears the update marker once it is up.
             return;
         }
         if (!outcome.ok) {
+            if (outcome.pending) {
+                console.log(outcome.message);
+                process.exitCode = 75;
+                return;
+            }
             console.error(outcome.message);
             if (!setUpdateProgressStage(DATA_DIR, "failed", { error: outcome.message.trim() }))
                 clearUpdateMarker(DATA_DIR);
@@ -1625,8 +1711,34 @@ program
         console.log("  Using nvm to install Node 22...");
     }
     // ── Install, then verify, then clean up (#1446): nothing is removed before the new install is proven ──
+    // #1450 C6: npm replaces THIS package in place. Everything the rest of the update runs — verification, rollback,
+    // service work — is loaded now, before npm; a later import would load the NEW package's files into this process.
+    await Promise.all([
+        import("./service-activation.js"), import("./service-installer.js"), import("./service-plan.js"),
+        import("./restart-guard.js"), import("./package-preimage.js"), import("./install-lock.js"), import("./update-check.js"),
+    ]);
     const { runUpdateInstall } = await import("./update-install.js");
-    const installed = runUpdateInstall({ pkg, targetVersion, viaNvm: needsSudo, nvmSh }, {
+    // #1450 C1: this update owns the npm prefix from before npm runs until it settles (verify, service, restart) —
+    // released when this process exits, however it exits; a crash leaves a lock the next update reclaims.
+    const { acquireInstallLock } = await import("./install-lock.js");
+    const { randomBytes } = await import("node:crypto");
+    const { createRequire } = await import("node:module");
+    const admission = createRequire(import.meta.url)("../launcher/install-admission.cjs");
+    let releaseLock = () => { };
+    process.once("exit", () => releaseLock());
+    const installed = runUpdateInstall({
+        pkg, targetVersion, viaNvm: needsSudo, nvmSh, rollback: true,
+        lock: prefix => {
+            const lock = acquireInstallLock(prefix, { spec: pkg, agendHome: DATA_DIR }, {
+                pid: process.pid, processStart: admission.processStart, newToken: () => randomBytes(16).toString("hex"),
+                now: () => new Date(), log: message => console.log(message),
+            });
+            if (!lock.ok)
+                return lock;
+            releaseLock = lock.release;
+            return { ok: true, token: lock.token };
+        },
+    }, {
         run: (command, args, options = {}) => {
             if (options.inherit)
                 console.log("");
@@ -1634,6 +1746,7 @@ program
                 encoding: "utf-8",
                 timeout: options.timeoutMs,
                 stdio: options.inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+                ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
             });
             return { status: result.status, signal: result.signal, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
         },
@@ -1673,15 +1786,45 @@ program
     .option("--activate", "Deprecated; service activation is now the default")
     .option("--no-activate", "Write the service file without activating it")
     .action(async (opts) => {
-    const { installService, activateService, detectPlatform } = await import("./service-installer.js");
-    const execPath = process.argv[1];
-    const svcPath = installService({
+    const { installService, activateService, detectPlatform, renderLaunchdPlist, launchdPlistPath } = await import("./service-installer.js");
+    const execPath = canonicalCliEntry();
+    const serviceVars = {
         label: "com.agend.fleet",
         execPath,
         path: process.env.PATH,
         workingDirectory: DATA_DIR,
         logPath: join(DATA_DIR, "fleet.log"),
-    });
+    };
+    // #1450 C6: on launchd, writing a new plist without activating is a PLANNED activation — proven, recorded, and
+    // left for `agend restart` (a reload there would itself start the job). See service-plan.ts.
+    if (opts.activate === false && detectPlatform() === "macos") {
+        const { refreshLaunchdWithoutActivating, planPath } = await import("./service-plan.js");
+        // A refresh revokes any earlier plan first, whatever it comes to (a failed refresh leaves nothing to activate).
+        planDeps().removeFile(planPath(DATA_DIR));
+        const { expectedTuple } = await import("./restart-guard.js");
+        const expectation = expectedTuple();
+        if (!expectation.ok) {
+            console.error(`  ✗ ${expectation.reason}`);
+            process.exitCode = 1;
+            return;
+        }
+        const uid = process.getuid?.() ?? 501;
+        const plistPath = launchdPlistPath(serviceVars.label);
+        mkdirSync(dirname(plistPath), { recursive: true });
+        const outcome = refreshLaunchdWithoutActivating({
+            label: serviceVars.label, target: `gui/${uid}/${serviceVars.label}`, plistPath, newPlist: renderLaunchdPlist(serviceVars),
+            expected: expectation.expected, pkgDir: dirname(dirname(execPath)), agendHome: DATA_DIR,
+        }, planDeps());
+        if (!outcome.ok) {
+            console.error(`  ✗ ${outcome.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(t("install.path", plistPath));
+        console.log(`  ${outcome.message}`);
+        return;
+    }
+    const svcPath = installService(serviceVars);
     console.log(t("install.path", svcPath));
     if (opts.activate !== false) {
         const pidPath = join(DATA_DIR, "fleet.pid");
@@ -1816,7 +1959,9 @@ program
     if (!userServicePath && !systemServicePath) {
         console.log("No service installed. Starting fleet directly...");
         const { spawn } = await import("node:child_process");
-        const child = spawn("sh", ["-c", "agend fleet start"], { detached: true, stdio: "ignore" });
+        // This Node on this CLI, not `sh -c "agend fleet start"` through PATH (#1450 C5).
+        const start = selfCommand(["fleet", "start"]);
+        const child = spawn(start.command, start.args, { detached: true, stdio: "ignore" });
         child.unref();
         console.log("Fleet starting in background.");
         return;
@@ -1837,9 +1982,52 @@ program
     .command("restart")
     .description("Restart the AgEnD service (auto-detects systemd/launchd/detached)")
     .option("-y, --yes", "Confirm when run from a fleet agent session (this affects every instance)")
+    .option("--force", "Restart even when the loaded service does not start this install on its selected Node (operators only)")
     .action(async (opts) => {
+    // --force overrides the C6 guard: an operator's own decision, never a fleet agent's or a fleet-internal spawn's.
+    if (opts.force && !forceAllowed()) {
+        console.error("  ✗ Not restarting: --force is for an operator's own shell, not a fleet agent session or the fleet's own commands. Nothing was stopped.");
+        process.exit(1);
+    }
     if (!gateFleetControl(DATA_DIR, "restart", { yes: opts.yes }))
         process.exit(1);
+    // #1450 C6: what the restarted fleet must run, by this package's own selection (C2) — decided before anything stops.
+    const guard = await import("./restart-guard.js");
+    const guardDeps = {
+        realpath: (path) => { try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        } },
+        isExecutable: (path) => { try {
+            return statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+        }
+        catch {
+            return false;
+        } },
+    };
+    const captureRun = (command, args) => {
+        const r = spawnSync(command, args, { encoding: "utf-8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"] });
+        return { status: r.status, signal: r.signal, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    };
+    const expectation = guard.expectedTuple();
+    /** Refuse (nothing stopped) unless the definition about to run is proven; `--force` overrides for an operator. */
+    const refuses = (judged) => {
+        if (judged.ok)
+            return false;
+        if (opts.force) {
+            console.log(`  ⚠ --force: ${judged.reason}; restarting anyway.`);
+            return false;
+        }
+        console.error(`  ✗ Not restarting: ${judged.reason}. Nothing was stopped.`);
+        if (judged.recovery)
+            console.error(`  To repair: ${judged.recovery}`);
+        process.exitCode = 1;
+        return true;
+    };
+    if (!expectation.ok && refuses(expectation))
+        return;
     // Try each runtime environment in order and stop at the first that succeeds.
     // Don't gate on fleet.pid: a fleet under systemd/launchd writes its pid in the
     // service's own HOME, which may differ from what this command resolves (sudo,
@@ -1892,8 +2080,8 @@ program
         const unitPath = systemdTarget.user ? getServicePath() : getSystemServicePath();
         const reloadCmd = systemdTarget.user ? "systemctl --user daemon-reload" : "systemctl daemon-reload";
         // #1113 rides the same migration: crash-dump, start-limit and
-        // start-timeout directives are filled in alongside KillMode. Only
-        // KillMode gates the restart — the others change no stop behaviour.
+        // start-timeout directives are filled in alongside KillMode. KillMode
+        // and the loaded #1071 stop grace gate the restart; the others are informational.
         // The drop-ins systemd applies to this unit, by its own account
         // (DropInPaths), plus any on disk it has not loaded yet. Guessing the
         // directories alone misses type-wide service.d and other load paths.
@@ -1951,6 +2139,23 @@ program
                 return;
             }
         }
+        // Migration preserves operator overrides. Admission independently requires
+        // the actual loaded budget for EVERY selected systemd target, even if its
+        // unit file disappeared or no migration/classification was possible.
+        if (hardening.TimeoutStopSec === "custom") {
+            console.log(`  ⚠ ${unitPath} sets its own TimeoutStopSec; left as is. A short grace can cut off busy CLI batches (#1071).`);
+        }
+        let loadedStopGrace = "";
+        try {
+            loadedStopGrace = execSync(`systemctl${scopeFlag} show -p TimeoutStopUSec --value ${systemdTarget.unit}`, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000 }).trim();
+        }
+        catch { /* unknown refuses */ }
+        const milliseconds = systemdStopTimeoutMs(loadedStopGrace);
+        if (milliseconds === null || milliseconds < FLEET_STOP_TIMEOUT_MS) {
+            console.error(`  ✗ Not restarting: systemd has ${loadedStopGrace || "unknown"} stop grace loaded; this fleet needs ${FLEET_STOP_TIMEOUT_MS / 1000}s. Set TimeoutStopSec to at least ${FLEET_STOP_TIMEOUT_MS / 1000}s in ${unitPath ?? systemdTarget.unit}, run \`${reloadCmd}\`, and retry (#1071).`);
+            process.exitCode = 1;
+            return;
+        }
         if (outcome === "added") {
             console.log(`  ✓ ${unitPath}: added KillMode=mixed (the fleet stops its CLIs; systemd no longer signals them all at once)`);
         }
@@ -1958,7 +2163,7 @@ program
             .filter(([key, state]) => key !== "KillMode" && (state === "added" || state === "upgraded"))
             .map(([key]) => key);
         if (updated.length > 0)
-            console.log(`  ✓ ${unitPath}: updated ${updated.join(", ")} (#1113: small crash dumps, bounded start, start limit)`);
+            console.log(`  ✓ ${unitPath}: updated ${updated.join(", ")} (#908/#1071/#1113: graceful stop, small crash dumps, bounded start, start limit)`);
         // Re-judged after the reload, against what systemd now applies: an
         // operator's own mask (anywhere — main file, unit or type drop-in, or a
         // trailing empty assignment that restores the inherited one) is warned
@@ -1989,6 +2194,8 @@ program
         }
         if (filterCustom)
             console.log(`  ⚠ ${unitPath} sets its own CoredumpFilter; left as is. CoredumpFilter=0 keeps crash dumps to a few KB (#1113).`);
+        if (expectation.ok && refuses(guard.guardSystemd(captureRun, systemdTarget.user, systemdTarget.unit, expectation.expected, guardDeps)))
+            return;
         // Clears the failed state AND the start-limit counter (#1113:
         // StartLimitBurst=4 in 30min) for whichever unit this restart targets,
         // so an operator's restart is never refused by the limit.
@@ -2015,62 +2222,177 @@ program
         process.exitCode = 1;
         return;
     }
-    // 3. launchd (macOS)
+    // 3. launchd (macOS). "Loaded" is launchctl print's own answer (113 = not loaded); nothing here may fall through
+    // to the detached restart once a job is known to be loaded.
     if (plat === "macos") {
         const uid = process.getuid?.() ?? 501;
         const label = "com.agend.fleet";
-        try {
-            // print succeeds only if the service is loaded in launchd
-            execSync(`launchctl print gui/${uid}/${label}`, { stdio: "pipe", timeout: 5000 });
-            if (run(`launchctl kickstart -k gui/${uid}/${label}`)) {
+        const target = `gui/${uid}/${label}`;
+        const deps = planDeps();
+        const printed = deps.run("launchctl", ["print", target]);
+        if (printed.status === 0) {
+            const plistPath = getServicePath() ?? join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+            // Path 2 (#1450 C6): a proven new plist waits on disk with its plan — exactly one bootout + bootstrap.
+            const { readPlan, admitPlan, planPath } = await import("./service-plan.js");
+            const plan = opts.force ? null : readPlan(DATA_DIR, deps);
+            if (plan && expectation.ok) {
+                const pkgDir = dirname(dirname(expectation.expected.entry));
+                const admitted = admitPlan(plan, { target, expected: expectation.expected, pkgDir }, deps);
+                if (!admitted.ok) {
+                    console.error(`  ✗ Not activating the planned launchd job: ${admitted.reason}. Nothing was stopped.`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const { activateService } = await import("./service-activation.js");
+                const outcome = activateService({ kind: "launchd", label, plistPath: plan.plistPath, domain: `gui/${uid}` }, { bin: expectation.expected.entry, entry: expectation.expected.entry, node: expectation.expected.node, dir: pkgDir }, {
+                    ...deps,
+                    readFirstLine: path => deps.readFile(path)?.split("\n", 1)[0] ?? null,
+                    isExecutable: path => { try {
+                        return statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+                    }
+                    catch {
+                        return false;
+                    } },
+                    refresh: () => ({ status: 0, signal: null, stdout: "", stderr: "" }),
+                    restart: () => { throw new Error("planned launchd activation does not invoke restart"); },
+                    log: message => console.log(message),
+                    launchdPreimage: plan.preimage.plist,
+                });
+                deps.removeFile(planPath(DATA_DIR));
+                if (outcome.ok) {
+                    console.log("Service restarted (launchd loaded the planned job).");
+                    return;
+                }
+                console.error(outcome.message);
+                process.exitCode = 1;
+                return;
+            }
+            // Path 1: an unchanged loaded job.
+            if (expectation.ok && refuses(guard.guardLaunchd(captureRun, target, plistPath, deps.readFile, expectation.expected, guardDeps)))
+                return;
+            if (run(`launchctl kickstart -k ${target}`)) {
                 console.log("Service restarted.");
                 return;
             }
+            console.error(`  ✗ launchctl kickstart -k ${target} failed.`);
+            process.exitCode = 1;
+            return;
+        }
+        const { LAUNCHD_NOT_LOADED } = await import("./service-plan.js");
+        if (!LAUNCHD_NOT_LOADED.includes(printed.status ?? -1) || printed.signal !== null) {
+            console.error(`  ✗ Could not tell whether ${label} is loaded (launchctl print ${printed.signal ? `killed by ${printed.signal}` : `exited ${printed.status}`}); refusing a detached restart that could duplicate the fleet.`);
+            process.exitCode = 1;
+            return;
         }
-        catch { /* not loaded — fall through */ }
     }
     // 4. Detached process tracked by fleet.pid (no service manager)
     if (existsSync(pidPath)) {
-        const oldPid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-        // Only signal a process confirmed to BE this fleet (#1125 review): a
-        // stale fleet.pid may name a recycled pid — an unrelated process. Not
-        // confirmed (gone, or something else) is treated as a stale pid file.
-        const isOurFleet = () => {
+        const originalPidFile = readFileSync(pidPath, "utf-8");
+        const oldPid = Number(originalPidFile.trim());
+        let claimedStart = null;
+        const absence = () => {
             try {
                 process.kill(oldPid, 0);
             }
-            catch {
-                return false;
+            catch (error) {
+                return error.code === "ESRCH" ? "gone" : "unknown";
             }
-            return isFleetStartCommandLine(readProcessCommandLine(oldPid));
+            return detachedProcessExited(oldPid) ? "gone" : null;
         };
-        if (oldPid && isOurFleet()) {
+        const inspect = () => {
             try {
-                process.kill(oldPid, "SIGTERM");
+                if (existsSync(pidPath) && readFileSync(pidPath, "utf-8") !== originalPidFile)
+                    return "unknown";
             }
-            catch { /* already gone */ }
-            for (let i = 0; i < 20; i++) {
-                try {
-                    process.kill(oldPid, 0);
-                }
-                catch {
-                    break;
-                }
-                spawnSync("sleep", ["0.5"]);
+            catch {
+                return "unknown";
+            }
+            const missing = absence();
+            if (missing)
+                return missing;
+            const start = detachedProcessStart(oldPid);
+            if (start === null)
+                return absence() ?? "unknown";
+            const command = readProcessCommandLine(oldPid);
+            if (!command)
+                return absence() ?? (claimedStart !== null && start === claimedStart ? "waiting" : "unknown");
+            const fleet = isFleetStartCommandLine(command);
+            if (claimedStart !== null && start !== claimedStart)
+                return fleet ? "unknown" : "other";
+            // The claimed process is still alive: rewritten argv is not exit proof.
+            if (claimedStart !== null && !fleet)
+                return "unknown";
+            claimedStart ??= start;
+            return fleet ? "fleet" : "other";
+        };
+        if (!Number.isSafeInteger(oldPid) || oldPid <= 1) {
+            console.error("  ✗ Invalid detached fleet PID; nothing was stopped or started.");
+            process.exitCode = 1;
+            return;
+        }
+        const state = inspect();
+        if (state === "unknown") {
+            console.error("  ✗ Cannot confirm the detached fleet owner; nothing was stopped or started.");
+            process.exitCode = 1;
+            return;
+        }
+        if (state === "fleet") {
+            if (expectation.ok && refuses(guard.guardDetached(process.execPath, expectation.expected, guardDeps)))
+                return;
+            console.log(`Stopping detached fleet (up to ${FLEET_STOP_TIMEOUT_MS / 60_000} minutes for graceful shutdown)...`);
+            try {
+                await stopDetachedOwner({
+                    inspect,
+                    signal: signal => {
+                        if (signal === "SIGKILL")
+                            console.log("  ⚠ Grace expired; forcing the confirmed fleet owner to exit.");
+                        // stdout can block. The helper's earlier proof cannot authorize a
+                        // signal after that write; prove the exact owner again now.
+                        const owner = inspect();
+                        if (owner === "gone" || owner === "other")
+                            return;
+                        if (owner !== "fleet")
+                            throw new Error("Detached fleet ownership changed before signalling; refusing the signal");
+                        try {
+                            process.kill(oldPid, signal);
+                        }
+                        catch (error) {
+                            if (error.code !== "ESRCH")
+                                throw error;
+                        }
+                    },
+                    now: () => performance.now(),
+                    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+                });
             }
-            // Re-confirmed right before the SIGKILL: the pid may have been reused
-            // during the wait.
-            if (isOurFleet()) {
-                try {
-                    process.kill(oldPid, "SIGKILL");
-                }
-                catch { /* already gone */ }
+            catch (error) {
+                console.error(`  ✗ ${error.message}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (expectation.ok && refuses(guard.guardDetached(process.execPath, expectation.expected, guardDeps)))
+                return;
+            const start = selfCommand(["fleet", "start"]);
+            // The runtime guard and command preparation can read files. Recheck
+            // publication AFTER both, immediately before cleanup/spawn. Unreadable
+            // publication cannot authorize deleting a newly published owner's file.
+            let publicationCurrent = false;
+            try {
+                publicationCurrent = readFileSync(pidPath, "utf-8") === originalPidFile;
+            }
+            catch (error) {
+                publicationCurrent = error?.code === "ENOENT";
+            }
+            if (!publicationCurrent) {
+                console.error("  ✗ Fleet owner changed or its publication is unreadable; refusing a duplicate restart.");
+                process.exitCode = 1;
+                return;
             }
             try {
                 unlinkSync(pidPath);
             }
-            catch { /* best effort */ }
-            const child = spawn("sh", ["-c", "agend fleet start"], { detached: true, stdio: "ignore" });
+            catch { /* old owner already removed it */ }
+            const child = spawn(start.command, start.args, { detached: true, stdio: "ignore" });
             child.unref();
             console.log("Fleet restarting in background.");
             return;