@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.20

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 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).
@@ -13,6 +14,7 @@ applyNetworkReliabilityDefaults();
 import { checkNodeVersion } from "./node-version-guard.js";
 checkNodeVersion();
 import { Command } 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";
@@ -24,7 +26,7 @@ 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";
@@ -144,6 +146,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 {
@@ -275,67 +278,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;
     }
@@ -559,31 +511,14 @@ fleet
             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");
-        // 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)
@@ -1552,6 +1487,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(`  Note: the system install (v${pkgVersion}) is kept; only a 2.1-era copy is retired after a move to nvm.`);
+            delete verified.retireSystemCopy;
+        }
         if (verified.retireSystemCopy) {
             try {
                 const { markCleanupPending } = await import("./update-marker.js");
@@ -1664,6 +1605,9 @@ program
             const { planPath } = await import("./service-plan.js");
             planDeps().removeFile(planPath(DATA_DIR));
         }
+        // #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 +1694,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 +1741,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(`  ℹ ${pkg} has no installer of its own (a release from before #2264); this updater installs it.`);
+    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`);
     }
@@ -2013,6 +2001,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")
@@ -2776,9 +2777,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`;
@@ -3081,26 +3097,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})`);
+        }
     }
-    return match;
+    else {
+        console.error(`No instance matching "${query}". Run "agend ls" to see all instances.`);
+    }
+    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 +3262,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 +3359,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 +3421,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 +3451,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 +3476,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`);
@@ -3408,6 +3517,10 @@ program
     .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")
     .action(async (opts) => {
     await lsAction(opts);
 });
@@ -3642,8 +3755,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"));