@songsid/agend 2.3.0-beta.22 → 2.3.0-beta.23

package/dist/child-process.d.ts

@@ -0,0 +1,21 @@
+/**
+ * #2374: `spawn` and `execFile` for the fleet's own code, with every piped stdio stream heard.
+ *
+ * A child's stdin/stdout/stderr pipes are EventEmitters of their own: `child.on("error")` and the `execFile` callback
+ * never see their errors, and an `error` nobody listens to is an uncaught exception, which stops the fleet (#2243).
+ * Here each pipe gets a listener for its whole life. By default a pipe error kills the child and is passed on as the
+ * child's own `error` (when anything listens for one), so the call fails with it: `execFile`'s callback and promise get
+ * the pipe error even if the child then exits 0, or had already exited while something else held the pipe, and nothing
+ * half-read passes for an answer. A caller that listens on the pipe itself keeps its own handling; one with a different
+ * response passes `onError` to `guardStdio`. The `*Sync` forms have no streams and come from node:child_process directly.
+ */
+import * as cp from "node:child_process";
+/**
+ * An `error` listener on each of the child's pipes. The default response kills the child and passes the error on as
+ * the child's `error` (only to a listener: unheard, it would be uncaught again), unless the caller heard that pipe's
+ * errors itself (another listener): then the caller's own handling is the response. Tolerates test doubles.
+ */
+export declare function guardStdio<T>(child: T, onError?: (err: Error) => void): T;
+export declare const spawn: typeof cp.spawn;
+export declare const execFile: typeof cp.execFile;
+export declare const exec: typeof cp.exec;

package/dist/child-process.js

@@ -0,0 +1,54 @@
+/**
+ * #2374: `spawn` and `execFile` for the fleet's own code, with every piped stdio stream heard.
+ *
+ * A child's stdin/stdout/stderr pipes are EventEmitters of their own: `child.on("error")` and the `execFile` callback
+ * never see their errors, and an `error` nobody listens to is an uncaught exception, which stops the fleet (#2243).
+ * Here each pipe gets a listener for its whole life. By default a pipe error kills the child and is passed on as the
+ * child's own `error` (when anything listens for one), so the call fails with it: `execFile`'s callback and promise get
+ * the pipe error even if the child then exits 0, or had already exited while something else held the pipe, and nothing
+ * half-read passes for an answer. A caller that listens on the pipe itself keeps its own handling; one with a different
+ * response passes `onError` to `guardStdio`. The `*Sync` forms have no streams and come from node:child_process directly.
+ */
+import * as cp from "node:child_process";
+import { promisify } from "node:util";
+/**
+ * An `error` listener on each of the child's pipes. The default response kills the child and passes the error on as
+ * the child's `error` (only to a listener: unheard, it would be uncaught again), unless the caller heard that pipe's
+ * errors itself (another listener): then the caller's own handling is the response. Tolerates test doubles.
+ */
+export function guardStdio(child, onError) {
+    const c = child;
+    if (!c)
+        return child;
+    for (const stream of [c.stdin, c.stdout, c.stderr]) {
+        if (!stream || typeof stream.on !== "function")
+            continue;
+        stream.on("error", onError ?? ((err) => {
+            if ((stream.listenerCount?.("error") ?? 1) > 1)
+                return;
+            try {
+                c.kill?.();
+            }
+            catch { /* already gone */ }
+            if ((c.listenerCount?.("error") ?? 0) > 0)
+                c.emit?.("error", err);
+        }));
+    }
+    return child;
+}
+export const spawn = ((...args) => guardStdio(cp.spawn(...args)));
+/** `execFile`/`exec` guarded; `promisify` of it keeps node's own { stdout, stderr } form, with its `.child` guarded. */
+function guarded(original) {
+    const call = (...args) => guardStdio(original()(...args));
+    Object.defineProperty(call, promisify.custom, {
+        value: (...args) => {
+            const promise = promisify(original())(...args);
+            guardStdio(promise.child);
+            return promise;
+        },
+    });
+    return call;
+}
+export const execFile = guarded(() => cp.execFile);
+export const exec = guarded(() => cp.exec);
+//# sourceMappingURL=child-process.js.map

package/dist/child-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-process.js","sourceRoot":"","sources":["../src/child-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ,EAAE,OAA8B;IACpE,MAAM,CAAC,GAAG,KAAiC,CAAC;IAC5C,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,KAAK,MAAM,MAAM,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAc,EAAE,CAAC;QAChE,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,UAAU;YAAE,SAAS;QACzD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,GAAU,EAAE,EAAE;YAC5C,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;gBAAE,OAAO;YACvD,IAAI,CAAC;gBAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;YAChD,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;gBAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC,CAAC;IACN,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,IAAe,EAAE,EAAE,CAC3C,UAAU,CAAE,EAAE,CAAC,KAA8C,CAAC,GAAG,IAAI,CAAC,CAAC,CAAoB,CAAC;AAE9F,wHAAwH;AACxH,SAAS,OAAO,CAAI,QAAiB;IACnC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,UAAU,CAAE,QAAQ,EAA2C,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/G,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE;QAC5C,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;YAC5B,MAAM,OAAO,GAAI,SAAS,CAAC,QAAQ,EAAW,CAAiE,CAAC,GAAG,IAAI,CAAC,CAAC;YACzH,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1B,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC,CAAC;IACH,OAAO,IAAoB,CAAC;AAC9B,CAAC;AACD,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;AACnD,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC"}

package/dist/cli.js

@@ -13,7 +13,7 @@ applyNetworkReliabilityDefaults();
 // never restarts into a binary that would crash at the first native DB open.
 import { checkNodeVersion } from "./node-version-guard.js";
 checkNodeVersion();
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { registerBugReportCommand } from "./bug-report-cli.js";
 import { join, dirname } from "node:path";
 import { SchedulerDb } from "./scheduler/db.js";
@@ -21,7 +21,8 @@ import { Cron } from "croner";
 import { existsSync, readFileSync, writeFileSync, appendFileSync, unlinkSync, mkdirSync, chmodSync, readdirSync, rmSync, statSync, realpathSync, openSync, writeSync, closeSync, } from "node:fs";
 import { homedir, totalmem, freemem, userInfo } from "node:os";
 import { fileURLToPath } from "node:url";
-import { spawn, spawnSync, execSync, execFileSync } from "node:child_process";
+import { spawnSync, execSync, execFileSync } from "node:child_process";
+import { spawn } from "./child-process.js";
 import { getAgendHome, getTmuxSocketName, isDefaultAgendHome } from "./paths.js";
 import { hasPausedMarker } from "./pause-marker.js";
 import { COMPLETION_SHELLS, completionScript } from "./completion.js";
@@ -31,7 +32,7 @@ import { describeSignalSource, forceAllowed, gateFleetControl, recordInstanceCon
 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";
+import { SYSTEMD_RESTART_TIMEOUT_MS, getServicePath, getSystemServicePath } from "./service-installer.js";
 import { selectSystemdRestartTarget, SYSTEMD_RESTART_INDETERMINATE_EXIT_CODE, } from "./service-restart-selection.js";
 import { loadRawFleetConfig } from "./config.js";
 import { setLocale, t } from "./locale.js";
@@ -40,6 +41,7 @@ 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";
+import { DIRECT_FLEET_START_ENV, redirectsToService, startedByServiceManager } from "./service-owner.js";
 import { handOff, shouldHandOff } from "./launchd-handoff.js";
 /** Prefix tmux args with -L when socket isolation is active. */
 function tmuxArgs(args) {
@@ -189,7 +191,7 @@ settingsCommand.command("confirm <id>").option("--yes", "Explicit noninteractive
         process.exitCode = 1;
     }
 });
-settingsCommand.command("reject <id>").action(async (id) => {
+settingsCommand.command("reject <id>").description("Reject a pending Settings change on this host").action(async (id) => {
     try {
         const inspected = await requestSettingsConfirmation(DATA_DIR, { action: "inspect", id });
         console.log(`Source: ${inspected.pending_change.source}\nRequester: ${inspected.pending_change.requested_by}\n${inspected.pending_change.summary.join("\n")}`);
@@ -218,12 +220,24 @@ fleet
     .command("start")
     .description("Start fleet or specific instance")
     .argument("[instance]", "Specific instance to start")
-    .action(async (instance) => {
+    .option("--direct", "Start here even though an AgEnD service is installed (operators only: the service cannot run on this host)")
+    .action(async (instance, opts) => {
     // Root running fleet = sandbox environment (e.g. Docker, WSL root service)
     // Set IS_SANDBOX so child processes (claude-code) don't refuse to run
     if (process.getuid?.() === 0 && !process.env.IS_SANDBOX) {
         process.env.IS_SANDBOX = "1";
     }
+    const marked = process.env[DIRECT_FLEET_START_ENV] === "1";
+    delete process.env[DIRECT_FLEET_START_ENV];
+    // #2356: the way out when the installed service cannot run here (never activated, no GUI session for launchd) — an
+    // operator's own decision, as `restart --force` is; the fleet's singleton lock still refuses a second fleet.
+    if (opts?.direct && !forceAllowed()) {
+        console.error("  ✗ --direct is for an operator's own shell, not a fleet agent session or the fleet's own commands. Nothing was started.");
+        process.exit(1);
+    }
+    const direct = marked || !!opts?.direct;
+    if (!instance && redirectToService("start", [], direct))
+        return;
     if (instance) {
         // If fleet daemon is already running, delegate via HTTP API
         const { loadFleetConfig } = await import("./config.js");
@@ -318,6 +332,8 @@ fleet
     .argument("[instance]", "Specific instance to stop")
     .option("-y, --yes", "Confirm when run from a fleet agent session (this affects every instance)")
     .action(async (instance, opts) => {
+    if (!instance && redirectToService("stop", opts?.yes ? ["--yes"] : [], false))
+        return;
     if (instance)
         recordInstanceControl(DATA_DIR, "instance-stop", instance);
     else if (!gateFleetControl(DATA_DIR, "fleet-stop", { yes: opts?.yes }))
@@ -392,159 +408,37 @@ fleet
 });
 fleet
     .command("restart")
-    .description("Graceful restart: wait for instances to idle, then restart")
-    .argument("[instance]", "Specific instance to restart (immediate, no idle wait)")
-    .option("--reload", "Full process restart to load new code")
+    .description("Deprecated: runs `agend restart` (removed in 2.4)")
+    .argument("[instance]", "Restart only this instance (now `agend restart <instance>`)")
+    .option("--reload", "Ignored: every full restart is `agend restart`")
     .option("-y, --yes", "Confirm when run from a fleet agent session (this affects every instance)")
-    .action(async (instance, opts) => {
+    .action((instance, opts) => {
     if (instance && opts?.reload) {
         console.error("--reload restarts the entire fleet process. Cannot combine with instance name.");
         process.exit(1);
     }
-    if (instance)
-        recordInstanceControl(DATA_DIR, "instance-restart", instance);
-    else if (!gateFleetControl(DATA_DIR, opts?.reload ? "fleet-restart-reload" : "fleet-restart", { yes: opts?.yes }))
-        process.exit(1);
-    if (instance) {
-        // Single instance restart via fleet's HTTP API
-        const { loadFleetConfig } = await import("./config.js");
-        const fleet = loadFleetConfig(FLEET_CONFIG_PATH);
-        const port = fleet.health_port ?? 19280;
-        let token = "";
-        try {
-            token = readFileSync(join(DATA_DIR, "web.token"), "utf-8").trim();
-        }
-        catch { /* fleet may not be running */ }
-        try {
-            const resp = await fetch(`http://127.0.0.1:${port}/restart/${encodeURIComponent(instance)}`, {
-                method: "POST",
-                headers: token ? { "X-Agend-Token": token } : {},
-            });
-            const body = await resp.json();
-            if (resp.ok) {
-                console.log(`Instance "${instance}" restarted (immediate)`);
-            }
-            else {
-                console.error(`Restart failed: ${body.error ?? resp.statusText}`);
-                process.exit(1);
-            }
-        }
-        catch (err) {
-            console.error(`Cannot connect to fleet (port ${port}). Is the fleet running?`);
-            process.exit(1);
-        }
-        return;
-    }
-    const pidPath = join(DATA_DIR, "fleet.pid");
-    if (!existsSync(pidPath)) {
-        console.error("Fleet is not running (no PID file found)");
-        process.exit(1);
-    }
-    const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-    if (!Number.isInteger(pid) || pid <= 0) {
-        console.error(`Fleet PID file at ${pidPath} is corrupted`);
-        process.exit(1);
-    }
-    if (opts?.reload) {
-        // Check if managed by launchd — if so, just signal and let launchd restart
-        let managedByLaunchd = false;
-        try {
-            const ppid = parseInt(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)]).toString().trim(), 10);
-            managedByLaunchd = ppid === 1;
-        }
-        catch { /* ignore */ }
-        try {
-            process.kill(pid, "SIGUSR1");
-        }
-        catch {
-            console.error("Failed to send reload signal (process may have exited)");
-            process.exit(1);
-        }
-        if (managedByLaunchd) {
-            console.log("Fleet is managed by launchd — sent reload signal.");
-            console.log("launchd will automatically restart with new code.");
-            // Wait briefly for old process to exit, then confirm new one started
-            const deadline = Date.now() + 6 * 60 * 1000;
-            while (Date.now() < deadline) {
-                try {
-                    process.kill(pid, 0);
-                    await new Promise(r => setTimeout(r, 500));
-                }
-                catch {
-                    break;
-                }
-            }
-            // Wait for launchd to start new process
-            await new Promise(r => setTimeout(r, 2000));
-            if (existsSync(pidPath)) {
-                const newPid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-                if (newPid !== pid) {
-                    console.log(`New fleet process started (PID ${newPid})`);
-                }
-            }
-            return;
-        }
-        console.log("Full restart signal sent — waiting for fleet to stop...");
-        // Wait for old process to exit (up to 6 minutes: 5 min idle wait + buffer)
-        const deadline = Date.now() + 6 * 60 * 1000;
-        while (Date.now() < deadline) {
-            try {
-                process.kill(pid, 0); // check if alive
-                await new Promise(r => setTimeout(r, 500));
-            }
-            catch {
-                break; // process exited
-            }
-        }
-        // Verify it actually exited
-        try {
-            process.kill(pid, 0);
-            console.error("Old fleet process still running after timeout — aborting");
-            process.exit(1);
-        }
-        catch {
-            // Good, it exited
-        }
-        console.log("Old fleet stopped. Starting with new code...");
-        // Start new fleet in this process (new Node.js process = new code loaded)
-        if (!claimFleetSingleton())
-            return;
-        const { FleetManager } = await import("./fleet-manager.js");
-        const fm = new FleetManager(DATA_DIR);
-        const handlers = installFleetProcessHandlers({
-            dataDir: DATA_DIR, manager: fm, runtime: process, console,
-            describeSignal: () => describeSignalSource(DATA_DIR, "SIGTERM"),
-        });
-        if (handlers.stopping)
-            return;
-        await fm.startAll(FLEET_CONFIG_PATH);
-        console.log("Fleet restarted with new code");
-    }
-    else {
-        // Instance-only restart (existing behavior)
-        try {
-            process.kill(pid, "SIGUSR2");
-            console.log("Graceful restart signal sent — fleet will restart when all instances are idle");
-        }
-        catch {
-            console.error("Failed to send restart signal (process may have exited)");
-            process.exit(1);
-        }
-    }
+    // #2356: no restart of its own any more. Its SIGUSR1 reload made the fleet exit 0 and took over in this process, so
+    // under a Restart=on-failure unit the fleet stayed down (and this process, in an agent pane, died with the unit's
+    // cgroup). It runs `agend restart` itself — this Node, this CLI — with the same gate, guard and exit code.
+    const args = instance ? ["restart", instance] : ["restart", ...(opts?.yes ? ["--yes"] : [])];
+    console.error(`⚠ \`agend fleet restart\` is deprecated and goes away in 2.4 — running \`agend ${args.join(" ")}\`.`);
+    const self = selfCommand(args);
+    const result = spawnSync(self.command, self.args, { stdio: "inherit" });
+    process.exit(result.status ?? 1);
 });
 fleet
-    .command("status")
-    .description("Show fleet status, workspace disk usage, unregistered instance directories, and host memory/swap")
+    .command("status", { hidden: true })
+    .description("Alias of `agend ls --resources`")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
-    // Delegate to the `ls` command implementation
     await lsAction({ ...opts, resources: true });
 });
 fleet
-    .command("logs")
-    .description("Alias for `agend logs`")
+    .command("logs", { hidden: true })
+    .description("Removed; use `agend logs`")
     .action(() => {
-    console.log("Use `agend logs` instead. Run `agend logs --help` for options.");
+    console.error("`agend fleet logs` was removed. Use `agend logs`.");
+    process.exitCode = 1;
 });
 fleet
     .command("history")
@@ -876,9 +770,6 @@ backend
         console.error(`Unknown backend: ${backendName}. Available: ${BACKENDS.map(b => b.id).join(", ")}`);
         process.exit(1);
     }
-    if (info.deprecated) {
-        console.warn(`⚠️  ${info.label} is deprecated (stops 2026-06-18). Consider switching to backend: antigravity`);
-    }
     let issues = 0;
     const ok = (msg) => console.log(`  \x1b[32m✓\x1b[0m ${msg}`);
     const fail = (msg) => { issues++; console.log(`  \x1b[31m✗\x1b[0m ${msg}`); };
@@ -1142,7 +1033,7 @@ async function doctorMcp() {
         }
         if (!ipcOk) {
             issues.push("IPC ✗ (socket not responding)");
-            suggestions.push("agend fleet restart");
+            suggestions.push("agend restart");
         }
         // 2. MCP config check
         let mcpOk = false;
@@ -1894,9 +1785,12 @@ program
 program
     .command("install")
     .description("Install the AgEnD system service and start it by default")
-    .option("--activate", "Deprecated; service activation is now the default")
+    .addOption(new Option("--activate").hideHelp())
     .option("--no-activate", "Write the service file without activating it")
     .action(async (opts) => {
+    if (process.argv.includes("--activate")) {
+        console.error("`agend install --activate` was removed; service activation is the default.");
+    }
     const { installService, activateService, detectPlatform, renderLaunchdPlist, launchdPlistPath, getServicePath, getSystemServicePath, serviceHomeFor } = await import("./service-installer.js");
     // #1631 B: an older updater (2.2.0-beta.1 and before) refreshes a hand-started fleet's service too, through this
     // command — which would CREATE a unit or plist, and every later update would then take a manager it may not reach
@@ -1977,6 +1871,13 @@ program
             process.exitCode = 1;
         }
     }
+    // #2331: a host whose fleet runs under the system unit gets no second, user unit from the refresh — it would only
+    // sit beside it unused, and be named as a leftover on every update after.
+    if (systemUnit) {
+        console.log(t("install.path", systemUnit));
+        console.log(t("install.updated"));
+        return;
+    }
     const svcPath = installService(serviceVars);
     console.log(t("install.path", svcPath));
     if (opts.activate !== false) {
@@ -2075,7 +1976,17 @@ program
     .action(async (opts) => {
     if (!gateFleetControl(DATA_DIR, "stop", { yes: opts.yes }))
         process.exit(1);
-    const { getServicePath, stopService } = await import("./service-installer.js");
+    const { getServicePath, getSystemServicePath, stopService, stopSystemService } = await import("./service-installer.js");
+    // #2356: the system unit first, as `agend start` and `agend restart` choose it; a SIGTERM would only stop the process.
+    if (getSystemServicePath()) {
+        if (stopSystemService()) {
+            console.log("Service stopped (system).");
+            return;
+        }
+        console.error("Failed to stop the system service: systemctl stop agend (run it as root).");
+        process.exitCode = 1;
+        return;
+    }
     if (!getServicePath()) {
         // No service — try killing by PID
         const pidPath = join(DATA_DIR, "fleet.pid");
@@ -2124,10 +2035,10 @@ program
     const systemServicePath = getSystemServicePath();
     if (!userServicePath && !systemServicePath) {
         console.log("No service installed. Starting fleet directly...");
-        const { spawn } = await import("node:child_process");
+        const { spawn } = await import("./child-process.js");
         // 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" });
+        const child = spawn(start.command, start.args, { detached: true, stdio: "ignore", env: { ...process.env, [DIRECT_FLEET_START_ENV]: "1" } });
         child.unref();
         console.log("Fleet starting in background.");
         return;
@@ -2140,16 +2051,79 @@ program
         // A service file means the service manager owns this fleet. Falling back
         // to a detached process here creates a second fleet when the bus recovers.
         console.error("Failed to start the installed AgEnD service; refusing to start a detached duplicate.");
-        console.error("Check your service manager, then retry: systemctl --user status com.agend.fleet");
+        console.error(`Check your service manager, then retry: ${process.platform === "darwin" ? "launchctl print gui/$(id -u)/com.agend.fleet" : systemServicePath ? "systemctl status agend" : "systemctl --user status com.agend.fleet"}`);
+        // #2356: a service file that cannot run here (never activated, no session for it) would otherwise leave no start.
+        console.error("If the service cannot run on this host, start the fleet without it: agend fleet start --direct");
         process.exitCode = 1;
     }
 });
+/**
+ * #2356 (user decision): on a host with an AgEnD service installed, a hand-run `fleet start` / `fleet stop` would run or
+ * kill a fleet the service manager does not own — a duplicate beside the unit, or a stop systemd undoes. Run `agend
+ * start` / `agend stop` instead (this Node, this CLI; their own gate and exit code). The manager's own `fleet start`
+ * (the unit's ExecStart, the launchd job) and AgEnD's marked detached start go ahead directly; so does every host
+ * without a service (Docker, manual setups). Exits when it redirected; false to go on.
+ */
+function redirectToService(command, extra, directMarker) {
+    let ownCgroup = null;
+    try {
+        ownCgroup = readFileSync("/proc/self/cgroup", "utf-8");
+    }
+    catch { /* not Linux */ }
+    const byServiceManager = startedByServiceManager({ platform: process.platform, env: process.env, ownCgroup, ppid: process.ppid, launchdLabel: "com.agend.fleet" });
+    const installed = getSystemServicePath() ?? getServicePath();
+    if (!redirectsToService({ command, directMarker, byServiceManager, installedServicePath: installed }))
+        return false;
+    console.error(`ℹ An AgEnD service is installed here (${installed}): running \`agend ${[command, ...extra].join(" ")}\` so the service manager owns the fleet.`);
+    const self = selfCommand([command, ...extra]);
+    const result = spawnSync(self.command, self.args, { stdio: "inherit" });
+    process.exit(result.status ?? 1);
+}
+/** One instance, at once, through the running fleet's HTTP API; the fleet process keeps running. */
+async function restartOneInstance(instance) {
+    recordInstanceControl(DATA_DIR, "instance-restart", instance);
+    const { loadFleetConfig } = await import("./config.js");
+    const fleet = loadFleetConfig(FLEET_CONFIG_PATH);
+    const port = fleet.health_port ?? 19280;
+    let token = "";
+    try {
+        token = readFileSync(join(DATA_DIR, "web.token"), "utf-8").trim();
+    }
+    catch { /* fleet may not be running */ }
+    try {
+        const resp = await fetch(`http://127.0.0.1:${port}/restart/${encodeURIComponent(instance)}`, {
+            method: "POST",
+            headers: token ? { "X-Agend-Token": token } : {},
+        });
+        const body = await resp.json();
+        if (resp.ok) {
+            console.log(`Instance "${instance}" restarted (immediate)`);
+        }
+        else {
+            console.error(`Restart failed: ${body.error ?? resp.statusText}`);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(`Cannot connect to fleet (port ${port}). Is the fleet running?`);
+        process.exit(1);
+    }
+}
 program
     .command("restart")
-    .description("Restart the AgEnD service (auto-detects systemd/launchd/detached)")
+    .description("Restart the AgEnD service (auto-detects systemd/launchd/detached) — the one full restart; or one instance")
+    .argument("[instance]", "Restart only this instance, immediately; the fleet keeps running")
     .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) => {
+    .action(async (instance, opts) => {
+    if (instance) {
+        if (opts.force) {
+            console.error("--force applies to the whole service, not one instance.");
+            process.exit(1);
+        }
+        await restartOneInstance(instance);
+        return;
+    }
     // --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.");
@@ -2199,8 +2173,9 @@ program
     // service's own HOME, which may differ from what this command resolves (sudo,
     // AGEND_HOME) — an absent pid file does NOT mean it's stopped. Ask the service
     // manager first. This is the canonical restart the `update` flow spawns.
-    const { detectPlatform, getServicePath, getSystemServicePath, getSystemdServiceState, systemdRestartOutcome, ensureSystemdUnitHardening, effectiveUnitDropIns, unitCoredumpFilterState, } = await import("./service-installer.js");
-    const { spawn, spawnSync } = await import("node:child_process");
+    const { detectPlatform, getServicePath, getSystemServicePath, getSystemdServiceState, systemdRestartOutcome, ensureSystemdUnitHardening, effectiveUnitDropIns, unitCoredumpFilterState, loadedUnitCheck, } = await import("./service-installer.js");
+    const { spawnSync } = await import("node:child_process");
+    const { spawn } = await import("./child-process.js");
     const plat = detectPlatform();
     const pidPath = join(DATA_DIR, "fleet.pid");
     const run = (cmd) => {
@@ -2329,7 +2304,11 @@ program
             .filter(([key, state]) => key !== "KillMode" && (state === "added" || state === "upgraded"))
             .map(([key]) => key);
         if (updated.length > 0)
-            console.log(`  ✓ ${unitPath}: updated ${updated.join(", ")} (#908/#1071/#1113: graceful stop, small crash dumps, bounded start, start limit)`);
+            console.log(`  ✓ ${unitPath}: updated ${updated.join(", ")} (#908/#1071/#1113/#2331: graceful stop, small crash dumps, bounded start, start limit, the fleet's ready signal)`);
+        // #2331: what systemd LOADED — a drop-in that refuses the fleet's READY is overridden by AgEnD's own, leftovers
+        // are named. Not a gate: the fleet still restarts, and the line says what will happen and what to remove.
+        for (const line of loadedUnitCheck({ user: systemdTarget.user, unit: systemdTarget.unit, unitPath }))
+            console.log(line);
         // 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
@@ -2566,7 +2545,7 @@ program
                 unlinkSync(pidPath);
             }
             catch { /* old owner already removed it */ }
-            const child = spawn(start.command, start.args, { detached: true, stdio: "ignore" });
+            const child = spawn(start.command, start.args, { detached: true, stdio: "ignore", env: { ...process.env, [DIRECT_FLEET_START_ENV]: "1" } });
             child.unref();
             console.log("Fleet restarting in background.");
             return;
@@ -2583,7 +2562,7 @@ program
 });
 program
     .command("setup")
-    .description("Open the guided setup page in a browser (before a fleet exists)")
+    .description("Browser first-run page, before a fleet exists (not the CLI wizard; see `agend quickstart`)")
     .option("--reset", "Allow setup again after it has already been completed")
     .option("--port <port>", "Port for the setup page (default: the health port)")
     .option("--tunnel", "Expose the setup page through a Cloudflare quick tunnel so a phone can open it")
@@ -2678,14 +2657,14 @@ program
 });
 program
     .command("quickstart")
-    .description("Guided setup for a Backend, chat channel, projects, and fleet service")
+    .description("CLI guided setup: backend, chat channel, projects, and fleet service (recommended)")
     .action(async () => {
     const { runQuickstart } = await import("./quickstart.js");
     await runQuickstart();
 });
 program
     .command("init")
-    .description("Interactive setup wizard (advanced)")
+    .description("Interactive advanced wizard (setup-wizard); for first-run use `agend quickstart` or `agend setup`")
     .action(async () => {
     const { runSetupWizard } = await import("./setup-wizard.js");
     await runSetupWizard();
@@ -3006,11 +2985,11 @@ schedule
     }
 });
 schedule
-    .command("trigger")
-    .description("Show how to manually trigger a schedule")
-    .argument("<id>", "Schedule ID")
-    .action((id) => {
-    console.log("Manual trigger requires fleet manager running. Use the Telegram interface instead.");
+    .command("trigger", { hidden: true })
+    .argument("[id]", "Schedule ID")
+    .action(() => {
+    console.error("`agend schedule trigger` was removed. There is no Telegram trigger; use `agend schedule enable` or the Task Board.");
+    process.exitCode = 1;
 });
 // === Chat Export ===
 program
@@ -3511,16 +3490,21 @@ async function lsAction(opts) {
             console.log("Tip: agend completion install  — then agend attach <TAB> completes instance names.");
     }
 }
-program
-    .command("ls")
-    .description("List all instances with status, backend, team, and last activity")
-    .option("--json", "Output as JSON")
-    .option("--names-only", "Print instance names one per line (for shell completion)")
-    .option("--resources", "Also report workspace disk usage, unregistered instance directories, and host memory/swap (text only)")
-    .option("--running", "Show only running instances")
-    .option("--team <name>", "Filter by team name")
-    .option("--backend <name>", "Filter by backend (exact match)")
-    .option("--display", "Show display names as last column")
+function addLsOptions(cmd) {
+    return cmd
+        .option("--json", "Output as JSON")
+        .option("--names-only", "Print instance names one per line (for shell completion)")
+        .option("--resources", "Also report workspace disk usage, unregistered instance directories, and host memory/swap (text only); `agend fleet status` is a hidden alias of this")
+        .option("--running", "Show only running instances")
+        .option("--team <name>", "Filter by team name")
+        .option("--backend <name>", "Filter by backend (exact match)")
+        .option("--display", "Show display names as last column");
+}
+addLsOptions(program.command("ls").description("List all instances with status, backend, team, and last activity"))
+    .action(async (opts) => {
+    await lsAction(opts);
+});
+addLsOptions(program.command("status", { hidden: true }).description("Alias of `agend ls`"))
     .action(async (opts) => {
     await lsAction(opts);
 });
@@ -3547,9 +3531,10 @@ Then reload the shell. Tab-completes instance names for \`agend attach\` and
     // Subcommand names come from commander itself, so the script can't drift
     // out of sync with the CLI the way a hardcoded list would.
     const fleetCmd = program.commands.find(c => c.name() === "fleet");
+    const visible = (cmds) => cmds.filter(c => !c._hidden).map(c => c.name());
     const spec = {
-        topLevel: program.commands.map(c => c.name()),
-        fleetSub: fleetCmd?.commands.map(c => c.name()) ?? [],
+        topLevel: visible(program.commands),
+        fleetSub: visible(fleetCmd?.commands ?? []),
         instanceCommands: ["attach"],
         fleetInstanceCommands: ["start", "stop", "restart"],
     };
@@ -3606,7 +3591,7 @@ Then reload the shell. Tab-completes instance names for \`agend attach\` and
     console.log(completionScript(target, spec));
 });
 program
-    .command("health").description("Fleet health check — shows problems and diagnostics")
+    .command("health").description("Live fleet health of running instances (HTTP, tmux, IPC); for host/setup diagnostics use `agend doctor`")
     .option("--json", "Output as JSON")
     .option("-q, --quiet", "One-line summary only")
     .action(async (opts) => {
@@ -3844,7 +3829,7 @@ program
 });
 program
     .command("logs")
-    .description("Show fleet log (alias for `agend fleet logs`)")
+    .description("Show fleet log (daemon.log, or fleet.log if the daemon log is not there yet)")
     .option("-n, --lines <count>", "Number of lines to show", "50")
     .option("-f, --follow", "Follow log output (like tail -f)")
     .option("--instance <name>", "Filter by instance name")