@songsid/agend 2.1.2-beta.8 → 2.1.2

package/dist/cli.js

@@ -14,7 +14,11 @@ import { getAgendHome, getTmuxSocketName } from "./paths.js";
 import { readClassicLastActivityAt } from "./classic-channel-manager.js";
 import { hasPausedMarker } from "./pause-marker.js";
 import { PIE_PERCENT_RE } from "./tui-glyphs.js";
+import { COMPLETION_SHELLS, completionScript } from "./completion.js";
 import { getUpdateSelector, lookupTargetVersion, reportUpdateRestart, shouldSkipUpdate, } from "./update-check.js";
+import { clearUpdateMarker, markUpdateInProgress } from "./update-marker.js";
+import { acquireFleetLock, releaseProcessFleetLock, setProcessFleetLock } from "./fleet-lock.js";
+import { SYSTEMD_RESTART_TIMEOUT_MS } from "./service-installer.js";
 /** Prefix tmux args with -L when socket isolation is active. */
 function tmuxArgs(args) {
     const socket = getTmuxSocketName();
@@ -25,6 +29,18 @@ const __dirname = dirname(__filename);
 const DATA_DIR = getAgendHome();
 const FLEET_CONFIG_PATH = join(DATA_DIR, "fleet.yaml");
 const program = new Command();
+function claimFleetSingleton() {
+    try {
+        setProcessFleetLock(acquireFleetLock(DATA_DIR));
+        process.once("exit", () => { releaseProcessFleetLock(); });
+        return true;
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 1;
+        return false;
+    }
+}
 // Read version from package.json at build time
 const pkgVersion = (() => {
     try {
@@ -68,8 +84,14 @@ fleet
         const fleet = loadFleetConfig(FLEET_CONFIG_PATH);
         const port = fleet.health_port ?? 19280;
         try {
-            const healthResp = await fetch(`http://127.0.0.1:${port}/health`);
-            if (healthResp.ok) {
+            // Any HTTP answer means a fleet daemon is listening — including a 503,
+            // which /health now returns when the fleet is degraded (no adapter
+            // connected, an instance crashed). Checking `.ok` here would treat a
+            // degraded fleet as "not running" and start a SECOND fleet on the same
+            // data dir, whose startup cleanup kills the first one's tmux windows.
+            // Only a connection error means nothing is there (the catch below).
+            await fetch(`http://127.0.0.1:${port}/health`);
+            {
                 try {
                     const resp = await fetch(`http://127.0.0.1:${port}/api/instance/${encodeURIComponent(instance)}/start`, { method: "POST" });
                     const body = await resp.json();
@@ -90,8 +112,65 @@ fleet
         }
         catch { /* fleet not running, fall through */ }
     }
+    // Claim the singleton before constructing FleetManager: its constructor and
+    // startAll path touch shared tmux, sockets, state files and adapters.
+    if (!claimFleetSingleton())
+        return;
     const { FleetManager } = await import("./fleet-manager.js");
     const fm = new FleetManager(DATA_DIR);
+    // Register crash/signal handlers BEFORE startAll(). Startup routinely takes
+    // minutes (sequential general spawn, staggered instances, warmup waits), and
+    // 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...");
+        await fm.stopAll().catch(err => console.error("Shutdown error:", err));
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", 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);
+        }
+    });
     if (instance) {
         const config = fm.loadConfig(FLEET_CONFIG_PATH);
         const inst = config.instances[instance];
@@ -100,7 +179,10 @@ fleet
             process.exit(1);
         }
         const topicMode = config.channel?.mode === "topic";
-        await fm.startInstance(instance, inst, topicMode);
+        // An explicit `agend fleet start <name>` is a resume request when the
+        // instance was auto/manual-paused.  Fleet startup itself still leaves
+        // persisted pauses alone.
+        await fm.startInstance(instance, inst, topicMode, "fleet-topic", true);
     }
     else {
         if (process.env.AGEND_HOME) {
@@ -109,30 +191,6 @@ fleet
         await fm.startAll(FLEET_CONFIG_PATH);
     }
     console.log("Fleet started");
-    // Keep process alive + clean shutdown on Ctrl+C
-    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);
-        // 409 = another bot poller exists — adapter handles retry, don't crash
-        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);
-    });
 });
 fleet
     .command("stop")
@@ -319,6 +377,8 @@ fleet
         }
         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);
@@ -1106,11 +1166,23 @@ program
     else {
         console.log(`\n  Updating AgEnD to ${tag}...\n`);
     }
+    // Tell the running fleet that what happens next is planned. `npm install -g`
+    // replaces the package directory underneath the live daemon — MCP servers
+    // die, then the restart stops every instance — and without this marker the
+    // old daemon reports each one as a crash. The new fleet deletes the marker
+    // once it finishes starting; it also expires on its own, so an update that
+    // dies here does not silence real alerts.
+    markUpdateInProgress(DATA_DIR);
+    const failUpdate = (message) => {
+        clearUpdateMarker(DATA_DIR);
+        console.error(message);
+        process.exit(1);
+    };
     // Detect and remove stale npm link (local build that shadows global install)
     try {
         const agendPath = execSync("which agend", { encoding: "utf-8", stdio: "pipe" }).trim();
         const resolved = execSync(`readlink -f "${agendPath}"`, { encoding: "utf-8", stdio: "pipe" }).trim();
-        if (resolved.includes("/Projects/") || resolved.includes("@suzuke") || resolved.includes("/src/")) {
+        if (resolved.includes("/Projects/") || resolved.includes("@songsid") || resolved.includes("@suzuke") || resolved.includes("/src/")) {
             console.log(`  ⚠️  Detected local npm link: ${resolved}`);
             console.log("  Removing link to allow global install...\n");
             try {
@@ -1147,8 +1219,7 @@ program
                 execSync("curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash", { stdio: "inherit" });
             }
             catch {
-                console.error("  Failed to install nvm. Install manually: https://github.com/nvm-sh/nvm");
-                process.exit(1);
+                failUpdate("  Failed to install nvm. Install manually: https://github.com/nvm-sh/nvm");
             }
         }
         console.log("  Using nvm to install Node 22...");
@@ -1157,12 +1228,16 @@ program
             execSync(`bash -c '${nvmPrefix} && npm install -g ${pkg}'`, { stdio: "inherit" });
         }
         catch {
-            console.error("  Failed to install via nvm.");
-            process.exit(1);
+            failUpdate("  Failed to install via nvm.");
         }
         // Try to remove old system binary
         console.log("  Note: removing old system install (may require sudo)...");
-        spawnSync("sudo", ["npm", "uninstall", "-g", "@songsid/agend"], { stdio: "inherit" });
+        // Never wait for a password in an agent/non-interactive terminal. This is
+        // best-effort cleanup; the new nvm install already succeeded.
+        spawnSync("sudo", ["-n", "npm", "uninstall", "-g", "@songsid/agend"], {
+            stdio: "inherit",
+            timeout: 10_000,
+        });
     }
     else {
         // ── Direct install ──
@@ -1170,8 +1245,7 @@ program
             execSync(`npm install -g ${pkg}`, { stdio: "inherit" });
         }
         catch {
-            console.error(`  Failed to update. Try: npm install -g ${pkg}`);
-            process.exit(1);
+            failUpdate(`  Failed to update. Try: npm install -g ${pkg}`);
         }
     }
     // ── Verify installation ──
@@ -1181,15 +1255,13 @@ program
         ? spawnSync("bash", ["-c", `source ${nvmSh2} && nvm use 22 > /dev/null 2>&1 && which agend`], { encoding: "utf-8" }).stdout?.trim()
         : spawnSync("which", ["agend"], { encoding: "utf-8" }).stdout?.trim();
     if (!agendPath) {
-        console.error("  ✗ Verification failed: agend not found in PATH after install.");
         if (needsSudo)
             console.error("  You may need to add nvm to your shell profile and restart.");
-        process.exit(1);
+        failUpdate("  ✗ Verification failed: agend not found in PATH after install.");
     }
     const verifyResult = spawnSync(agendPath, ["--version"], { encoding: "utf-8", timeout: 5000 });
     if (verifyResult.status !== 0) {
-        console.error("  ✗ Verification failed: agend --version returned error.");
-        process.exit(1);
+        failUpdate("  ✗ Verification failed: agend --version returned error.");
     }
     const newVersion = (verifyResult.stdout ?? "").trim();
     console.log(`  ✓ Installed: ${newVersion}`);
@@ -1216,9 +1288,20 @@ program
     // restart` (new binary) does the 4-environment service detection (system
     // systemd → user systemd → launchd → detached pid).
     console.log("  Restarting fleet...");
-    const restartResult = spawnSync(agendPath, ["restart"], { encoding: "utf-8", timeout: 30000, stdio: "inherit" });
-    if (!reportUpdateRestart(restartResult.status))
+    // `agend restart` may synchronously wait for a Type=notify service to finish
+    // a multi-minute stop/start and send READY=1. Keep this parent wrapper alive
+    // longer than the restart command's own bounded wait.
+    const restartResult = spawnSync(agendPath, ["restart"], {
+        encoding: "utf-8",
+        timeout: SYSTEMD_RESTART_TIMEOUT_MS + 60_000,
+        stdio: "inherit",
+    });
+    if (!reportUpdateRestart(restartResult.status)) {
+        // No new fleet is coming up to clear the marker — do it here, or the next
+        // 15 minutes of genuine crashes would go unreported.
+        clearUpdateMarker(DATA_DIR);
         process.exitCode = 1;
+    }
 });
 program
     .command("reload")
@@ -1331,8 +1414,10 @@ program
     .command("start")
     .description("Start the AgEnD service (must be installed first)")
     .action(async () => {
-    const { getServicePath, startService } = await import("./service-installer.js");
-    if (!getServicePath()) {
+    const { getServicePath, getSystemServicePath, startService, startSystemService } = await import("./service-installer.js");
+    const userServicePath = getServicePath();
+    const systemServicePath = getSystemServicePath();
+    if (!userServicePath && !systemServicePath) {
         console.log("No service installed. Starting fleet directly...");
         const { spawn } = await import("node:child_process");
         const child = spawn("sh", ["-c", "agend fleet start"], { detached: true, stdio: "ignore" });
@@ -1340,16 +1425,16 @@ program
         console.log("Fleet starting in background.");
         return;
     }
-    if (startService()) {
+    const started = systemServicePath ? startSystemService() : startService();
+    if (started) {
         console.log("Service started.");
     }
     else {
-        // systemd/launchd failed — fallback to direct start
-        console.log("Service manager unavailable. Starting fleet directly...");
-        const { spawn } = await import("node:child_process");
-        const child = spawn("sh", ["-c", "agend fleet start"], { detached: true, stdio: "ignore" });
-        child.unref();
-        console.log("Fleet starting in background.");
+        // 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");
+        process.exitCode = 1;
     }
 });
 program
@@ -1361,18 +1446,10 @@ 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 } = await import("./service-installer.js");
+    const { detectPlatform, getServicePath, getSystemServicePath, getSystemdServiceState, restartSystemdService, } = await import("./service-installer.js");
     const { spawn, spawnSync } = await import("node:child_process");
     const plat = detectPlatform();
     const pidPath = join(DATA_DIR, "fleet.pid");
-    const isActive = (cmd) => {
-        try {
-            return spawnSync("sh", ["-c", cmd], { encoding: "utf-8", timeout: 5000 }).stdout?.trim() === "active";
-        }
-        catch {
-            return false;
-        }
-    };
     const run = (cmd) => {
         try {
             execSync(cmd, { stdio: "inherit", timeout: 15000 });
@@ -1383,9 +1460,17 @@ program
         }
     };
     // 1. System-level systemd service "agend"
-    if (plat !== "macos" && isActive("systemctl is-active agend 2>/dev/null")) {
+    const systemServiceInstalled = plat !== "macos" && getSystemServicePath() !== null;
+    const systemState = plat !== "macos" ? getSystemdServiceState("agend", false) : "stopped";
+    if (systemServiceInstalled && systemState === "unavailable") {
+        console.error("Cannot reach the system service manager; refusing a detached restart that could duplicate the fleet.");
+        console.error("Check: systemctl status agend");
+        process.exitCode = 1;
+        return;
+    }
+    if (systemServiceInstalled && (systemState === "running" || systemState === "stopped")) {
         run("systemctl daemon-reload");
-        if (run("systemctl restart agend")) {
+        if (restartSystemdService("agend", false)) {
             console.log("Service restarted (system).");
             return;
         }
@@ -1395,13 +1480,23 @@ program
         return;
     }
     // 2. User-level systemd service "com.agend.fleet"
-    if (plat !== "macos" && isActive("systemctl --user is-active com.agend.fleet 2>/dev/null")) {
+    const userServiceInstalled = plat !== "macos" && getServicePath() !== null;
+    const userState = plat !== "macos"
+        ? getSystemdServiceState("com.agend.fleet", true)
+        : "stopped";
+    if (userServiceInstalled && userState === "unavailable") {
+        console.error("Cannot reach the user service manager; refusing a detached restart that could duplicate the fleet.");
+        console.error("Check: systemctl --user status com.agend.fleet");
+        process.exitCode = 1;
+        return;
+    }
+    if (userServiceInstalled && (userState === "running" || userState === "stopped")) {
         run("systemctl --user daemon-reload");
         try {
             execSync("systemctl --user reset-failed com.agend.fleet", { stdio: "pipe", timeout: 5000 });
         }
         catch { /* best effort */ }
-        if (run("systemctl --user restart com.agend.fleet")) {
+        if (restartSystemdService("com.agend.fleet", true)) {
             console.log("Service restarted (user).");
             return;
         }
@@ -1835,28 +1930,7 @@ async function fuzzyMatch(query, names) {
     return null;
 }
 async function resolveInstance(query, config) {
-    const names = Object.keys(config.instances);
-    // Include classic instances from classicBot.yaml
-    try {
-        const classicPath = join(DATA_DIR, "classicBot.yaml");
-        if (existsSync(classicPath)) {
-            const yamlMod = (await import("js-yaml")).default;
-            const classic = yamlMod.load(readFileSync(classicPath, "utf-8"));
-            if (classic?.channels) {
-                for (const [key, val] of Object.entries(classic.channels)) {
-                    // New format persists instanceName; old format keyed by channelId.
-                    if (val.instanceName) {
-                        names.push(val.instanceName);
-                        continue;
-                    }
-                    const channelId = val.channelId ?? key;
-                    const chName = (val.name ?? channelId).toLowerCase().replace(/[^\p{L}\d-]/gu, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "project";
-                    names.push(`classic-${chName}-${channelId.slice(-4)}`);
-                }
-            }
-        }
-    }
-    catch { /* ignore */ }
+    const names = await listInstanceNames(config);
     const match = await fuzzyMatch(query, names);
     if (!match) {
         console.error(`No instance matching "${query}". Available: ${names.join(", ")}`);
@@ -1907,6 +1981,15 @@ function getTreeRssKb(pid, depth = 0) {
 function getInstanceStatusStandalone(name) {
     if (hasPausedMarker(join(DATA_DIR, "instances", name)))
         return "paused";
+    // daemon.pid is the shared FleetManager PID, so it remains alive when one
+    // CLI has entered the persisted 3-crashes circuit breaker. Consult that
+    // marker before using daemon.pid as a fallback.
+    try {
+        const crash = JSON.parse(readFileSync(join(DATA_DIR, "instances", name, "crash-state.json"), "utf8"));
+        if (Number(crash?.crashesInWindow) >= 3)
+            return "crashed";
+    }
+    catch { /* no valid crash-loop marker */ }
     const pidPath = join(DATA_DIR, "instances", name, "daemon.pid");
     if (!existsSync(pidPath))
         return "stopped";
@@ -1989,10 +2072,48 @@ const defaultParser = (output) => {
 };
 /** Optional backend-specific overrides; none needed — defaultParser covers all. */
 const contextParsers = {};
+/**
+ * Every instance name the CLI accepts: fleet.yaml instances plus the
+ * dynamically-created ClassicBot ones. Shared by `resolveInstance` (fuzzy
+ * matching for `attach`) and `ls --names-only` (shell completion), so the
+ * candidates offered by tab-completion are exactly the ones `attach` resolves.
+ */
+async function listInstanceNames(config) {
+    const names = Object.keys(config.instances);
+    try {
+        const classicPath = join(DATA_DIR, "classicBot.yaml");
+        if (existsSync(classicPath)) {
+            const yamlMod = (await import("js-yaml")).default;
+            const classic = yamlMod.load(readFileSync(classicPath, "utf-8"));
+            if (classic?.channels) {
+                for (const [key, val] of Object.entries(classic.channels)) {
+                    // New format persists instanceName; old format keyed by channelId.
+                    if (val.instanceName) {
+                        names.push(val.instanceName);
+                        continue;
+                    }
+                    const channelId = val.channelId ?? key;
+                    const chName = (val.name ?? channelId).toLowerCase().replace(/[^\p{L}\d-]/gu, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "project";
+                    names.push(`classic-${chName}-${channelId.slice(-4)}`);
+                }
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return names;
+}
 async function lsAction(opts) {
     const yaml = (await import("js-yaml")).default;
     const config = yaml.load(readFileSync(FLEET_CONFIG_PATH, "utf-8"));
     const names = Object.keys(config.instances);
+    // --names-only feeds shell completion, so it must return before any tmux or
+    // 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) {
+        for (const n of await listInstanceNames(config))
+            console.log(n);
+        return;
+    }
     // Load classic channels from classicBot.yaml (keyed by channelId)
     const classicPath = join(DATA_DIR, "classicBot.yaml");
     let classicConfig = null;
@@ -2195,6 +2316,10 @@ async function lsAction(opts) {
     }
     // Status icon — prefer tri-state 'state' field, fall back to idle boolean
     const statusIcon = (s, idle, state) => {
+        if (s === "crashed")
+            return "\x1b[31m●\x1b[0m";
+        if (s === "stopped")
+            return "\x1b[90m○\x1b[0m";
         if (state === "stuck")
             return "\x1b[31m●\x1b[0m";
         if (state === "paused" || s === "paused")
@@ -2206,11 +2331,13 @@ async function lsAction(opts) {
         // Fallback for when API is unreachable
         if (s === "running")
             return idle === false ? "\x1b[34m●\x1b[0m" : "\x1b[32m●\x1b[0m";
-        if (s === "crashed")
-            return "\x1b[31m●\x1b[0m";
         return "\x1b[90m○\x1b[0m";
     };
     const statusLabel = (s, idle, state) => {
+        if (s === "crashed")
+            return "Crashed";
+        if (s === "stopped")
+            return "Stopped";
         if (state === "stuck")
             return "Stuck";
         if (state === "paused" || s === "paused")
@@ -2221,8 +2348,6 @@ async function lsAction(opts) {
             return "Idle";
         if (s === "running")
             return idle === false ? "Busy" : "Idle";
-        if (s === "crashed")
-            return "Crashed";
         return "Stopped";
     };
     /** Get display width accounting for fullwidth (CJK) characters */
@@ -2278,12 +2403,38 @@ 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)")
     .action(async (opts) => {
     await lsAction(opts);
 });
 program
-    .command("health")
-    .description("Fleet health check — shows problems and diagnostics")
+    .command("completion")
+    .description("Print a shell completion script (bash or zsh)")
+    .argument("<shell>", `Shell to generate for (${COMPLETION_SHELLS.join(", ")})`)
+    .addHelpText("after", `
+Install:
+  bash   echo 'eval "$(agend completion bash)"' >> ~/.bashrc
+  zsh    echo 'eval "$(agend completion zsh)"'  >> ~/.zshrc
+
+Then reload the shell. Tab-completes instance names for \`agend attach\` and
+\`agend fleet start|stop|restart\`, and subcommands elsewhere.`)
+    .action((shell) => {
+    if (!COMPLETION_SHELLS.includes(shell)) {
+        console.error(`Unsupported shell: ${shell}. Supported: ${COMPLETION_SHELLS.join(", ")}`);
+        process.exit(2);
+    }
+    // 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");
+    console.log(completionScript(shell, {
+        topLevel: program.commands.map(c => c.name()),
+        fleetSub: fleetCmd?.commands.map(c => c.name()) ?? [],
+        instanceCommands: ["attach"],
+        fleetInstanceCommands: ["start", "stop", "restart"],
+    }));
+});
+program
+    .command("health").description("Fleet health check — shows problems and diagnostics")
     .option("--json", "Output as JSON")
     .option("-q, --quiet", "One-line summary only")
     .action(async (opts) => {