@songsid/agend 2.3.0-beta.9 → 2.3.1

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
+// #2481: first — counts a `fleet start` attempt before anything below can fail (start-failure.ts).
+import "./start-attempt.js";
 import "./node-warnings.js";
+import { installFleetProcessHandlers } from "./fleet-process-handlers.js";
 import { applyNetworkReliabilityDefaults } from "./network-family.js";
 // Preserve Node's dual-stack Happy Eyeballs behavior, but avoid its 250ms
 // premature-connect failure on WSL/VPN/high-load hosts (#658).
@@ -12,32 +15,37 @@ 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";
 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";
 import { getUpdateSelector, isExactVersion, isUnrequestedDowngrade, lookupTargetVersion, reportUpdateRestart, shouldSkipUpdate, runningFleetPredatesInstall, fleetProvenStopped, readFleetPidEvidence, pidAlive, processStartMs, } from "./update-check.js";
-import { clearUpdateMarker, markUpdateInProgress, setUpdateProgressStage } from "./update-marker.js";
+import { clearUpdateMarker, markUpdateInProgress, readUpdateProgress, setUpdateProgressStage } from "./update-marker.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";
+import { SYSTEMD_RESTART_TIMEOUT_MS, getServicePath, getSystemServicePath } from "./service-installer.js";
+import { withFsPlanLock } from "./service-plan.js";
 import { selectSystemdRestartTarget, SYSTEMD_RESTART_INDETERMINATE_EXIT_CODE, } from "./service-restart-selection.js";
 import { loadRawFleetConfig } from "./config.js";
-import { setLocale, t } from "./locale.js";
+import { detectLocale, setLocale, t } from "./locale.js";
+import { settingsSourceLabel } from "./settings-confirmation.js";
 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";
+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) {
@@ -65,6 +73,7 @@ function planDeps() {
             unlinkSync(path);
         }
         catch { /* absent */ } },
+        withPlanLock: (fn) => withFsPlanLock(DATA_DIR, fn),
         realpath: (path) => { try {
             return realpathSync(path);
         }
@@ -103,15 +112,38 @@ async function handOffLaunchdActivation(action) {
     return false;
 }
 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.
+// CLI commands run outside FleetManager, in the fleet's language as the fleet decides it (#2390 follow-up): an explicit
+// defaults.locale, else the host's zone (UTC+8 → zh-TW), else English. A line another program reads (the updater, the
+// Windows installer and shortcuts, the rehearsal scripts) is never a locale string: tests/cli-machine-lines-2390 pins them.
+let configForLocale;
 try {
-    const configuredLocale = loadRawFleetConfig(FLEET_CONFIG_PATH).defaults?.locale;
-    if (configuredLocale === "en" || configuredLocale === "zh-TW")
-        setLocale(configuredLocale);
+    configForLocale = loadRawFleetConfig(FLEET_CONFIG_PATH);
 }
-catch { /* malformed or missing config: keep the English CLI default */ }
+catch { /* malformed or missing config: the zone decides */ }
+setLocale(detectLocale(configForLocale));
 const program = new Command();
+/**
+ * #2481: an installed version whose fleet keeps failing to start is said on every command, with what to run to go back.
+ * Not for the fleet process itself (its own `fleet start`/`stop`, whose output is the service's log), completion, or
+ * machine output (--json); free once the installed version has started here (start-failure.ts).
+ */
+const NO_START_BANNER = new Set(["fleet", "completion", "web-token", "health"]);
+program.hook("preAction", async (_hooked, action) => {
+    let top = action;
+    while (top.parent && top.parent !== program)
+        top = top.parent;
+    if (NO_START_BANNER.has(top.name()) || action.opts().json)
+        return;
+    try {
+        const { checkStartFailure } = await import("./start-failure.js");
+        const failure = checkStartFailure(DATA_DIR);
+        if (!failure.failing)
+            return;
+        const { startFailureLines } = await import("./start-failure-notice.js");
+        console.error(["", ...startFailureLines(failure, DATA_DIR), ""].join("\n"));
+    }
+    catch { /* the banner never stands in a command's way */ }
+});
 function claimFleetSingleton() {
     try {
         setProcessFleetLock(acquireFleetLock(DATA_DIR));
@@ -144,6 +176,7 @@ program
     // The root's own options only before a subcommand: otherwise `agend update --version 2.1.9` is read as
     // `agend --version`, prints this version and installs nothing.
     .enablePositionalOptions();
+registerBugReportCommand(program, pkgVersion);
 function signalFleetReload() {
     const pidPath = join(DATA_DIR, "fleet.pid");
     try {
@@ -162,15 +195,15 @@ settingsCommand.command("confirm <id>").option("--yes", "Explicit noninteractive
     .action(async (id, options) => {
     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")}`);
+        console.log([t("settings_confirm.source", settingsSourceLabel(inspected.pending_change.source)), t("settings_confirm.requester", inspected.pending_change.requested_by), ...inspected.pending_change.summary].join("\n"));
         let confirmed = options.yes === true;
         if (!confirmed) {
             if (!process.stdin.isTTY)
-                throw new Error("Interactive confirmation required; --yes explicitly confirms the printed diff.");
+                throw new Error(t("settings_confirm.cli_interactive"));
             const { createInterface } = await import("node:readline/promises");
             const input = createInterface({ input: process.stdin, output: process.stdout });
             try {
-                confirmed = (await input.question("Apply this exact change? [y/N] ")).trim().toLowerCase() === "y";
+                confirmed = (await input.question(t("settings_confirm.cli_question"))).trim().toLowerCase() === "y";
             }
             finally {
                 input.close();
@@ -186,10 +219,10 @@ 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")}`);
+        console.log([t("settings_confirm.source", settingsSourceLabel(inspected.pending_change.source)), t("settings_confirm.requester", inspected.pending_change.requested_by), ...inspected.pending_change.summary].join("\n"));
         const result = await requestSettingsConfirmation(DATA_DIR, { action: "reject", ticket: inspected.ticket });
         console.log(result.pending_change.outcome?.message ?? result.pending_change.state);
     }
@@ -215,12 +248,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(t("cli.direct_refused"));
+        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");
@@ -275,67 +320,16 @@ fleet
     // without these a Ctrl-C or `systemctl stop` in that window got Node's default
     // behaviour: instant death with fleet.pid already written, databases unclosed,
     // and every tmux window orphaned.
-    let stopping = false;
-    const shutdown = async () => {
-        if (stopping)
-            return; // SIGINT and SIGTERM share this, and crash paths call stopAll too
-        stopping = true;
-        console.log("\nStopping fleet...");
-        // stopAll fences new profile requests synchronously, before it awaits
-        // the shared owner's stop/save. Stopping the env handle first would leave
-        // the manager open to replacing that closed owner during the save.
-        await fm.stopAll().catch(err => console.error("Shutdown error:", err));
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", () => {
-        // The restart that interrupted a fleet used to leave no trace of who asked.
-        console.log(describeSignalSource(DATA_DIR, "SIGTERM"));
-        void shutdown();
-    });
-    process.on("uncaughtException", (err) => {
-        // An uncaught exception leaves unknown state — still the one case worth
-        // tearing down for.
-        console.error("Uncaught exception:", err);
-        if (stopping)
-            return;
-        stopping = true;
-        fm.stopAll().catch(() => { }).finally(() => process.exit(1));
-    });
-    process.on("unhandledRejection", (err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        // 409 = another bot poller exists — the adapter retries, don't crash.
-        if (msg.includes("409") && msg.includes("getUpdates")) {
-            console.error("Bot polling conflict (409) — retrying...");
-            return;
-        }
-        // Do NOT take the fleet down. A rejected promise in one instance's tmux
-        // call, health tick, or model switch used to stop every other working
-        // instance and exit(1) — the widest blast radius in the process. The
-        // per-instance health check and crash recovery handle a genuinely broken
-        // instance on their own.
-        //
-        // Surviving quietly would be its own failure mode, so this reports to the
-        // General topic as well as the log: the operator must not have to read
-        // daemon.log to learn the fleet swallowed a fault. notifyFleetError()
-        // throttles repeats, since these usually arrive from a loop.
-        console.error("Unhandled rejection (fleet continues):", err);
-        if (err instanceof Error && err.stack)
-            console.error(err.stack);
-        try {
-            fm.notifyFleetError(`⚠️ Fleet caught an unhandled error and kept running:\n\`${msg}\`\nSee daemon.log for the stack trace.`);
-        }
-        catch (notifyErr) {
-            // Never let the reporting path itself become an unhandled rejection.
-            console.error("Failed to report unhandled rejection:", notifyErr);
-        }
+    const handlers = installFleetProcessHandlers({
+        dataDir: DATA_DIR, manager: fm, runtime: process, console,
+        describeSignal: () => describeSignalSource(DATA_DIR, "SIGTERM"),
     });
     await fm.startCpuProfileControl().catch(err => console.warn(`Local profile control unavailable: ${String(err)}`));
     await fm.startSettingsConfirmationControl().catch(err => console.warn(`Local Settings confirmation unavailable: ${String(err)}`));
-    if (stopping)
+    if (handlers.stopping)
         return;
     cpuProfile = await fm.startEnvironmentCpuProfile();
-    if (stopping) {
+    if (handlers.stopping) {
         await cpuProfile?.stop("startup superseded by shutdown");
         return;
     }
@@ -366,6 +360,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 }))
@@ -399,7 +395,7 @@ fleet
             }
         }
         catch {
-            console.error(`Cannot connect to fleet (port ${port}). Is the fleet running?`);
+            console.error(t("cli.fleet_unreachable", port));
             process.exit(1);
         }
         return;
@@ -440,176 +436,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);
-        await fm.startAll(FLEET_CONFIG_PATH);
-        console.log("Fleet restarted with new code");
-        // Keep process alive (same as fleet start)
-        const shutdown = async () => {
-            console.log("\nStopping fleet...");
-            await fm.stopAll();
-            process.exit(0);
-        };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-        process.on("uncaughtException", async (err) => {
-            console.error("Uncaught exception:", err);
-            await fm.stopAll().catch(() => { });
-            process.exit(1);
-        });
-        process.on("unhandledRejection", async (err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes("409") && msg.includes("getUpdates")) {
-                console.error("Bot polling conflict (409) — retrying...");
-                return;
-            }
-            console.error("Unhandled rejection:", err);
-            await fm.stopAll().catch(() => { });
-            process.exit(1);
-        });
-    }
-    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(t("cli.fleet_restart_deprecated", 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(t("cli.fleet_logs_removed"));
+    process.exitCode = 1;
 });
 fleet
     .command("history")
@@ -941,9 +798,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}`); };
@@ -1207,7 +1061,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;
@@ -1552,6 +1406,12 @@ program
         // the cleanup write later can prove it still owns the marker (checklist
         // 3/5). A missed capture only skips the marker write; retire still runs.
         let cleanupReceipt = null;
+        // #2264 review: the old system copy is retired only for a confirmed 2.1-era layout — the copy this updater runs
+        // from is a 2.1.x release (2.1's updater left it there). Never from "nvm" or "root" alone: a 2.2+ copy stays.
+        if (verified.retireSystemCopy && !/^2\.1\./.test(pkgVersion)) {
+            console.log(t("cli.system_install_kept", pkgVersion));
+            delete verified.retireSystemCopy;
+        }
         if (verified.retireSystemCopy) {
             try {
                 const { markCleanupPending } = await import("./update-marker.js");
@@ -1658,12 +1518,16 @@ program
                 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.
+        // The refresh above (`install --no-activate`) records a launchd plan; this activation consumed it. Compare-and-
+        // delete so a newer plan published during the slow bootout is left (#2376 / #2439).
         if (manager.kind === "launchd") {
-            const { planPath } = await import("./service-plan.js");
-            planDeps().removeFile(planPath(DATA_DIR));
+            const { consumeCarriedOutPlan } = await import("./service-plan.js");
+            const uid = process.getuid?.() ?? 501;
+            consumeCarriedOutPlan(DATA_DIR, `gui/${uid}/com.agend.fleet`, planDeps());
         }
+        // #1853: in a WSL terminal without the Windows desktop shortcuts, say once how to make them (never makes them).
+        if (outcome.ok)
+            await import("./windows-shortcuts.js").then(m => m.printUpdateShortcutsHint(DATA_DIR)).catch(() => { });
         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.
@@ -1750,6 +1614,7 @@ program
         }
         console.log(`\n  ✓ Already up to date (v${pkgVersion})\n`);
         setUpdateProgressStage(DATA_DIR, "complete", { version: pkgVersion });
+        await import("./windows-shortcuts.js").then(m => m.printUpdateShortcutsHint(DATA_DIR)).catch(() => { });
         return;
     }
     if (isUnrequestedDowngrade(pkgVersion, targetVersion, opts)) {
@@ -1796,6 +1661,49 @@ program
         if (verdict.kind === "unknown")
             console.log(verdict.note);
     }
+    // ── #2264: the target release installs itself ──
+    // `agend update` only chooses the version; the install — repair, `npm install -g`, proof, service, restart, the
+    // chat's progress — is that release's own installer (launcher/agend-install.cjs), fetched pinned by npm with its
+    // integrity checks. So every update runs the NEWEST install logic, never this (possibly old) package's, and the
+    // one-liner runs the same program. The code below this branch is the compatibility path, unchanged: for a prefix
+    // that needs sudo (the nvm route), and for a target from before the installer.
+    // Only a known target that ships the installer runs it: `npm exec --package <a release without agend-install>` would
+    // run whatever agend-install PATH has (#2264 review). An older target, or one npm cannot describe, takes the
+    // compatibility path below; `--target` makes any other installer refuse.
+    const shipsInstaller = () => {
+        const viewed = spawnSync("npm", ["view", pkg, "bin", "--json"], { encoding: "utf-8", timeout: 60_000, stdio: ["ignore", "pipe", "ignore"] });
+        try {
+            const parsed = JSON.parse(viewed.stdout || "null");
+            const bin = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+            return viewed.status === 0 && !!bin && typeof bin === "object" && Object.hasOwn(bin, "agend-install");
+        }
+        catch {
+            return false;
+        }
+    };
+    const viaInstaller = !needsSudo && targetVersion !== null && shipsInstaller();
+    if (!needsSudo && !viaInstaller)
+        console.log(t("cli.no_own_installer", pkg));
+    if (viaInstaller) {
+        console.log(`\n  Updating AgEnD v${pkgVersion} → v${targetVersion} (its own installer)...\n`);
+        markUpdateInProgress(DATA_DIR);
+        setUpdateProgressStage(DATA_DIR, "downloading", { version: targetVersion });
+        // AGEND_UPDATE_OWNER_PID: the marker this process just wrote is the installer's to carry on (and no one else's).
+        const installer = spawnSync("npm", ["exec", "--yes", "--package", pkg, "--", "agend-install", "--upgrade", "--target", targetVersion], {
+            stdio: "inherit", env: { ...withOrigin("agend-update"), AGEND_UPDATE_OWNER_PID: String(process.pid) },
+        });
+        if (installer.status === 0 || installer.status === 75) {
+            process.exitCode = installer.status ?? 0;
+            return;
+        }
+        // The installer records its own failure; one that never started (npm could not fetch it) is recorded here.
+        const progress = readUpdateProgress(DATA_DIR)?.progress;
+        if (progress && progress.stage !== "failed" && progress.stage !== "complete") {
+            setUpdateProgressStage(DATA_DIR, "failed", { error: `the installer for ${pkg} did not run (npm exec exited ${installer.status ?? installer.signal ?? installer.error?.message}); nothing was changed` });
+        }
+        process.exitCode = installer.status || 1;
+        return;
+    }
     if (targetVersion) {
         console.log(`\n  Updating AgEnD v${pkgVersion} → v${targetVersion}...\n`);
     }
@@ -1906,9 +1814,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(t("cli.install_activate_removed"));
+    }
     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
@@ -1940,9 +1851,9 @@ program
     // #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");
+        const { refreshLaunchdWithoutActivating, revokePlan } = 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));
+        revokePlan(DATA_DIR, planDeps());
         const { expectedTuple } = await import("./restart-guard.js");
         const expectation = expectedTuple();
         if (!expectation.ok) {
@@ -1989,6 +1900,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) {
@@ -2013,6 +1931,19 @@ program
         console.log(t("install.updated"));
     }
 });
+program
+    .command("shortcuts")
+    .description("WSL: create or update the Windows desktop shortcuts (the dashboard and restart)")
+    .action(async () => {
+    // #1853: for an install that predates the installer's shortcuts, or that is only ever updated with `agend update`.
+    const { runShortcuts, realShortcutsDeps } = await import("./windows-shortcuts.js");
+    const { spawnSync } = await import("node:child_process");
+    const { userInfo } = await import("node:os");
+    process.exitCode = await runShortcuts(realShortcutsDeps(DATA_DIR, userInfo().username, (command, args) => {
+        const r = spawnSync(command, args, { encoding: "utf-8", timeout: 120_000, stdio: ["ignore", "pipe", "pipe"] });
+        return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error };
+    }));
+});
 program
     .command("uninstall")
     .description("Remove the AgEnD system service")
@@ -2074,7 +2005,22 @@ program
     .action(async (opts) => {
     if (!gateFleetControl(DATA_DIR, "stop", { yes: opts.yes }))
         process.exit(1);
-    const { getServicePath, stopService } = await import("./service-installer.js");
+    // #2481: a deliberate stop — the start attempts so far are not a crash loop.
+    {
+        const { clearStartAttempts } = await import("./start-failure.js");
+        clearStartAttempts(DATA_DIR);
+    }
+    const { getServicePath, getSystemServicePath, stopService, stopSystemService, serviceStopReport } = 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(t("cli.system_service_stopped"));
+            return;
+        }
+        console.error(t("cli.system_service_stop_failed"));
+        process.exitCode = 1;
+        return;
+    }
     if (!getServicePath()) {
         // No service — try killing by PID
         const pidPath = join(DATA_DIR, "fleet.pid");
@@ -2093,8 +2039,11 @@ program
         }
         return;
     }
-    if (stopService()) {
-        console.log("Service stopped.");
+    const report = serviceStopReport(stopService()); // #2505: "unloading" is not stopped
+    if (report.kind !== "fallback") {
+        console.log(report.line);
+        if (report.exitCode)
+            process.exitCode = report.exitCode;
     }
     else {
         // systemd/launchd failed (e.g. no D-Bus user session) — fallback to PID kill
@@ -2123,10 +2072,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;
@@ -2139,16 +2088,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(t("cli.service_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(t("cli.service_direct_hint"));
         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(t("cli.service_redirect", String(installed), [command, ...extra].join(" ")));
+    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(t("cli.instance_restarted", instance));
+        }
+        else {
+            console.error(t("cli.restart_failed", String(body.error ?? resp.statusText)));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(t("cli.fleet_unreachable", port));
+        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(t("cli.force_whole_service"));
+            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.");
@@ -2198,8 +2210,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) => {
@@ -2328,7 +2341,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(t("cli.unit_updated", String(unitPath), updated.join(", ")));
+        // #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
@@ -2399,13 +2416,11 @@ program
         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, planCarriedOut } = await import("./service-plan.js");
-            const recorded = opts.force ? null : readPlan(DATA_DIR, deps);
-            // #1871: an interrupted update's plan whose job launchd already runs (after `agend start`) is done: restart that
-            // job as an unchanged one (path 1) instead of refusing it for its new pid.
-            const plan = recorded && planCarriedOut(recorded, target, deps) ? null : recorded;
-            if (recorded && !plan)
-                console.log("  ℹ launchd already runs the job an interrupted update planned; restarting it as it is.");
+            const { pendingPlan, admitPlan, planPath, consumeUnchangedPlan, consumeCarriedOutPlan } = await import("./service-plan.js");
+            // #1871: a plan whose job launchd already runs (an interrupted update, then `agend start`) is done: restart that
+            // job as an unchanged one (path 1) instead of refusing it for its new pid. #2375: quietly (no note on every restart).
+            const published = deps.readFile(planPath(DATA_DIR));
+            const plan = opts.force ? null : pendingPlan(DATA_DIR, target, deps);
             if (plan && expectation.ok) {
                 const pkgDir = dirname(dirname(expectation.expected.entry));
                 const admitted = admitPlan(plan, { target, expected: expectation.expected, pkgDir }, deps);
@@ -2431,7 +2446,7 @@ program
                     log: message => console.log(message),
                     launchdPreimage: plan.preimage.plist,
                 });
-                deps.removeFile(planPath(DATA_DIR));
+                consumeUnchangedPlan(DATA_DIR, published, deps);
                 if (outcome.ok) {
                     console.log("Service restarted (launchd loaded the planned job).");
                     return;
@@ -2440,7 +2455,9 @@ program
                 process.exitCode = 1;
                 return;
             }
-            // Path 1: an unchanged loaded job.
+            // Path 1: an unchanged loaded job, or a leftover carried-out plan. Compare-and-delete that leftover (#2439);
+            // pendingPlan itself stays read-only (#2376).
+            consumeCarriedOutPlan(DATA_DIR, target, deps);
             if (expectation.ok && refuses(guard.guardLaunchd(captureRun, target, plistPath, deps.readFile, expectation.expected, guardDeps)))
                 return;
             if (run(`launchctl kickstart -k ${target}`)) {
@@ -2565,7 +2582,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;
@@ -2582,7 +2599,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")
@@ -2677,14 +2694,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();
@@ -2733,7 +2750,7 @@ program
         minutes = Math.max(1, Math.round(((body.expiresAt ?? Date.now()) - Date.now()) / 60_000));
     }
     catch {
-        console.error(`Cannot connect to fleet (port ${port}). Is the fleet running?`);
+        console.error(t("cli.fleet_unreachable", port));
         process.exit(1);
     }
     const signin = `http://localhost:${port}/signin`;
@@ -2776,9 +2793,24 @@ program
 program
     .command("validate")
     .description("Validate fleet.yaml and classicBot.yaml")
-    .action(async () => {
-    const { validateFleetConfig, validateClassicBotConfig } = await import("./config-validator.js");
+    .option("--connections", "Only print how many chat connections fleet.yaml has, as CONNECTIONS=<n> (for scripts; CONNECTIONS=unknown and exit 1 when it cannot be read)")
+    .action(async (opts) => {
+    const { validateFleetConfig, validateClassicBotConfig, configuredConnectionCount } = await import("./config-validator.js");
     const yaml = (await import("js-yaml")).default;
+    if (opts.connections) {
+        // #2233: the Windows installer's question — did the setup page make a web-only fleet? Parsed, never grepped.
+        let count = null;
+        try {
+            count = configuredConnectionCount(yaml.load(readFileSync(FLEET_CONFIG_PATH, "utf-8")));
+        }
+        catch {
+            count = null;
+        }
+        console.log(`CONNECTIONS=${count ?? "unknown"}`);
+        if (count === null)
+            process.exit(1);
+        return;
+    }
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
@@ -2990,11 +3022,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(t("cli.schedule_trigger_removed"));
+    process.exitCode = 1;
 });
 // === Chat Export ===
 program
@@ -3081,26 +3113,88 @@ async function fuzzyMatch(query, names) {
 }
 async function resolveInstance(query, config) {
     const namesRaw = await listInstanceNames(config);
-    const names = [...new Set(namesRaw)]; // P3-3: deduplicate (a classicBot instanceName can equal a fleet name)
-    const { resolveName } = await import("./topic-commands.js");
-    const entries = names.map((name) => ({
+    const names = [...new Set(namesRaw)];
+    const { assignDisplayLabels } = await import("./topic-commands.js");
+    const entries = names.map(name => ({
         name,
-        displayName: config.instances[name]?.display_name,
+        displayName: config.instances[name]?.display_name ?? null,
+    }));
+    const labelMap = assignDisplayLabels(entries);
+    // Build candidates with 1-based row index and status, matching ls order.
+    const candidates = names.map((name, i) => ({
+        idx: i + 1,
+        realName: name,
+        displayLabel: labelMap.get(name) ?? name,
+        teams: getTeamsForInstance(config, name),
+        status: getInstanceStatusStandalone(name),
     }));
-    const result = resolveName(query, entries);
-    if (result.kind === "name")
-        return result.realName;
+    const { resolveCandidate } = await import("./ls-attach-resolve.js");
+    // No argument on a TTY: show interactive picker.
+    if (query === undefined) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error("No instance specified.");
+            process.exit(1);
+        }
+        return interactivePicker(candidates);
+    }
+    const result = resolveCandidate(query, candidates);
+    if (result.kind === "exact")
+        return result.candidate.realName;
     if (result.kind === "ambiguous") {
-        console.error(`"${query}" matches multiple instances: ${result.realNames.join(", ")}. Use the real name.`);
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            console.log(`"${query}" matches multiple instances:`);
+            const { ambiguityLine } = await import("./ls-attach-resolve.js");
+            const { computeLsNameWidth: cnw } = await import("./ls-rows.js");
+            const maxNameW = cnw(result.candidates.map(c => c.realName), 0);
+            for (const c of result.candidates) {
+                console.log(ambiguityLine(c, maxNameW));
+            }
+            return interactivePicker(result.candidates);
+        }
+        const names2 = result.candidates.map(c => `${c.displayLabel} (${c.realName})`).join(", ");
+        console.error(`"${query}" matches multiple instances: ${names2}. Use the real name.`);
         process.exit(1);
     }
-    // Fall through to the original fuzzy match on real names.
-    const match = await fuzzyMatch(query, names);
-    if (!match) {
-        console.error(`No instance matching "${query}". Available: ${names.join(", ")}`);
-        process.exit(1);
+    // kind === "none" — show top-5 fuzzy suggestions, not the full list.
+    const suggestions = result.suggestions;
+    if (suggestions.length > 0) {
+        console.error(`No instance matching "${query}". Did you mean:`);
+        for (const c of suggestions) {
+            console.error(`  ${String(c.idx).padStart(2)}) ${c.displayLabel}  (${c.realName})`);
+        }
+    }
+    else {
+        console.error(`No instance matching "${query}". Run "agend ls" to see all instances.`);
     }
-    return match;
+    process.exit(1);
+}
+async function interactivePicker(candidates) {
+    const running = candidates.filter(c => c.status === "running");
+    const rest = candidates.filter(c => c.status !== "running");
+    const ordered = [...running, ...rest];
+    const { pickerDefaultIdx } = await import("./ls-attach-resolve.js");
+    const defaultIdx = pickerDefaultIdx(ordered);
+    const { pickerLine } = await import("./ls-attach-resolve.js");
+    const { computeLsNameWidth: cnwPicker } = await import("./ls-rows.js");
+    const maxNameW = cnwPicker(ordered.map(c => c.realName), 0);
+    console.log("Select an instance:");
+    for (const c of ordered) {
+        console.log(pickerLine(c, maxNameW));
+    }
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    // Use the unambiguous #N form so Enter always selects the displayed-first
+    // row, even when its global idx matches a digit-string real name.
+    const answer = await new Promise(resolve => rl.question(`\nRow number or name [#${defaultIdx}]: `, resolve));
+    rl.close();
+    const trimmed = answer.trim() || `#${defaultIdx}`;
+    // Accept a number or re-run resolution.
+    const { resolveCandidate } = await import("./ls-attach-resolve.js");
+    const reResult = resolveCandidate(trimmed, candidates);
+    if (reResult.kind === "exact")
+        return reResult.candidate.realName;
+    console.error(`Invalid selection "${trimmed}".`);
+    process.exit(1);
 }
 function getInstanceStatusStandalone(name) {
     if (hasPausedMarker(join(DATA_DIR, "instances", name)))
@@ -3184,6 +3278,12 @@ async function lsAction(opts) {
     // status work (a tab press should not wait on the fleet) and must print
     // nothing but names — a "no instances" notice would become a candidate.
     if (opts.namesOnly) {
+        const { validateNamesOnlyFilters } = await import("./ls-attach-resolve.js");
+        const filterErr = validateNamesOnlyFilters(opts);
+        if (filterErr) {
+            console.error(filterErr);
+            process.exit(1);
+        }
         for (const n of await listInstanceNames(config))
             console.log(n);
         return;
@@ -3275,7 +3375,7 @@ async function lsAction(opts) {
     };
     // Row collection runs concurrently (see ls-rows.ts): the per-instance
     // tmux captures overlap instead of stacking their 2s bounds serially.
-    const { collectLsRows, capturePaneAsync, formatTimeSince, lsStatusIcon, lsStatusLabel, displayWidth } = await import("./ls-rows.js");
+    const { collectLsRows, capturePaneAsync, formatTimeSince, lsStatusIcon, lsStatusLabel, displayWidth, computeLsNameWidth, padToDisplayWidth } = await import("./ls-rows.js");
     const { getTmuxSocketName } = await import("./paths.js");
     const socketName = getTmuxSocketName();
     const rows = await collectLsRows(allNames.map(name => {
@@ -3337,8 +3437,25 @@ async function lsAction(opts) {
         }
     }
     catch { /* fleet not running or API unreachable */ }
+    // Assign stable global indices BEFORE any filtering (#P2-1 — filters must not
+    // renumber rows, so `agend attach N` always resolves the same instance).
+    const { applyLsFilters } = await import("./ls-attach-resolve.js");
+    const allRowsIndexed = rows.map((r, i) => ({ ...r, globalIdx: i + 1 }));
+    // Apply --running / --team / --backend CLI filters. Done before --json so
+    // `ls --json --running` honours the flag (#P2-2).
+    const filteredMeta = applyLsFilters(allRowsIndexed.map(r => ({
+        globalIdx: r.globalIdx,
+        realName: r.name,
+        displayLabel: r.name,
+        status: (r.status ?? "stopped"),
+        teams: r.teams,
+        backend: r.backend,
+    })), { running: opts.running, team: opts.team, backend: opts.backend });
+    const filteredNames = new Set(filteredMeta.map(m => m.realName));
+    const displayRows = allRowsIndexed.filter(r => filteredNames.has(r.name));
     if (opts.json) {
-        console.log(JSON.stringify(rows, null, 2));
+        // Strip internal globalIdx from JSON output to keep the schema stable.
+        console.log(JSON.stringify(displayRows.map(({ globalIdx: _idx, ...rest }) => rest), null, 2));
         return;
     }
     // Merged State column (#1052): one glyph per lifecycle/execution state,
@@ -3350,19 +3467,24 @@ async function lsAction(opts) {
     // across the fleet (#1305 P2-1). --json and --names-only above keep the
     // real names (machine use + attach target).
     const { assignDisplayLabels } = await import("./topic-commands.js");
-    const lsLabels = assignDisplayLabels(rows.map((r) => ({
+    const { lsDisplayAnnotation } = await import("./ls-attach-resolve.js");
+    const lsLabels = assignDisplayLabels(displayRows.map((r) => ({
         name: r.name,
         displayName: config.instances[r.name]?.display_name,
     })));
-    const displayName = (row) => lsLabels.get(row.name) ?? row.name;
-    const nameW = Math.max(20, ...rows.map(r => displayWidth(displayName(r)) + 2));
+    const displayLabel = (row) => lsLabels.get(row.name) ?? row.name;
+    // Columns: # (global row number), Name (real, full, copyable), then the rest.
+    // Display name (if set) appears at the end of the row as context — secondary.
+    const numW = 3;
+    const nameW = computeLsNameWidth(displayRows.map(r => r.name));
     const backendW = 14;
     const statusW = 12;
     const teamW = 20;
     const srcW = 4;
     const ctxW = 8;
     const memW = 8;
-    console.log("Name".padEnd(nameW) +
+    console.log("#".padEnd(numW) +
+        "Name".padEnd(nameW) +
         "Backend".padEnd(backendW) +
         "Status".padEnd(statusW) +
         "Team".padEnd(teamW) +
@@ -3370,25 +3492,28 @@ async function lsAction(opts) {
         "Ctx".padEnd(ctxW) +
         "Mem".padEnd(memW) +
         "Activity");
-    console.log("\u2500".repeat(nameW + backendW + statusW + teamW + srcW + ctxW + memW + 10));
-    for (const r of rows) {
+    console.log("\u2500".repeat(numW + nameW + backendW + statusW + teamW + srcW + ctxW + memW + 10));
+    for (const r of displayRows) {
         const teamStr = r.teams.length > 0 ? r.teams.join(",") : "-";
         const ctxStr = r.context != null ? `${Math.round(r.context)}%` : "-";
         const memStr = r.memMb != null ? `${r.memMb}MB` : "-";
         const actStr = r.lastActivity ?? "-";
-        console.log(padDisplay(displayName(r), nameW) +
+        const dispAnnotation = lsDisplayAnnotation(r.name, displayLabel(r), opts.display ?? false);
+        console.log(String(r.globalIdx).padEnd(numW) +
+            padToDisplayWidth(r.name, nameW) +
             r.backend.padEnd(backendW) +
             statusIcon(r.status, r.idle, r.state) + " " + statusLabel(r.status, r.idle, r.state).padEnd(statusW - 2) +
             padDisplay(teamStr, teamW) +
             r.source.padEnd(srcW) +
             ctxStr.padEnd(ctxW) +
             memStr.padEnd(memW) +
-            actStr);
+            actStr +
+            dispAnnotation);
     }
     // System memory footer
-    const totalMemMb = rows.reduce((sum, r) => sum + (r.memMb ?? 0), 0);
-    const runningCount = rows.filter(r => r.status === "running").length;
-    const pausedCount = rows.filter(r => r.status === "paused").length;
+    const totalMemMb = displayRows.reduce((sum, r) => sum + (r.memMb ?? 0), 0);
+    const runningCount = displayRows.filter(r => r.status === "running").length;
+    const pausedCount = displayRows.filter(r => r.status === "paused").length;
     const totalGB = totalmem() / (1024 ** 3);
     const usedGB = (totalmem() - freemem()) / (1024 ** 3);
     console.log(`\nInstances: ${runningCount} running, ${pausedCount} paused | Fleet Mem: ${(totalMemMb / 1024).toFixed(1)} GB | System Memory: ${usedGB.toFixed(1)} / ${totalGB.toFixed(1)} GB`);
@@ -3402,12 +3527,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)")
+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);
 });
@@ -3434,9 +3568,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"],
     };
@@ -3493,7 +3628,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) => {
@@ -3642,8 +3777,8 @@ program
 });
 program
     .command("attach")
-    .description("Attach to an instance's tmux window (fuzzy match)")
-    .argument("<name>", "Instance name (supports fuzzy matching)")
+    .description("Attach to an instance's tmux window. Accepts display name, instance name, row number from ls, or a substring. No argument: interactive picker.")
+    .argument("[name]", "Instance name, display name, row number, or substring (omit for interactive picker)")
     .action(async (query) => {
     const yaml = (await import("js-yaml")).default;
     const config = yaml.load(readFileSync(FLEET_CONFIG_PATH, "utf-8"));
@@ -3731,7 +3866,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")