@mono-agent/agent-app 0.2.2 → 0.4.0

package/dist/cli.js

@@ -1,19 +1,28 @@
 #!/usr/bin/env node
+import { stat } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { startMonoAgentApp } from "./app.js";
+import { phoenixAppBaseUrl } from "./app-config.js";
+import { runBackfill } from "./backfill.js";
 import { defaultBackgroundDeps, resolveInstanceTarget, restartBackground, startBackground, statusBackground, stopBackground, tailLogs, } from "./background.js";
 import { validateMonoAgentFolder } from "./doctor.js";
 import { initMonoAgentFolder } from "./init.js";
 import { installComposerSkill } from "./install-skill.js";
+import { purgeSessions } from "./sessions.js";
+import * as ui from "./ui.js";
 const DEFAULT_LOG_LINES = 200;
+// Node's maximum setInterval/setTimeout delay (2^31 - 1 ms, ~24.8 days). A
+// referenced timer at this delay keeps the foreground event loop alive without
+// busy-waiting; larger values silently overflow to a 1ms delay.
+const KEEP_ALIVE_INTERVAL_MS = 2_147_483_647;
 const BACKGROUND_COMMANDS = ["start", "restart", "stop", "status", "logs"];
-const KNOWN_COMMANDS = ["init", "validate", "start", "restart", "stop", "status", "logs", "install-skill"];
+const KNOWN_COMMANDS = ["init", "validate", "start", "restart", "stop", "status", "logs", "install-skill", "backfill"];
 export function parseCliArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-        return { command: "help", noConsole: false, force: false, foreground: false, follow: false };
+        return { command: "help", force: false, foreground: false, follow: false, all: false, dryRun: false };
     }
     if (!KNOWN_COMMANDS.includes(command)) {
         throw new Error(`Unknown command \`${command}\`. Expected ${KNOWN_COMMANDS.join(", ")}.`);
@@ -21,32 +30,41 @@ export function parseCliArgs(argv) {
     const cmd = command;
     const isLogs = cmd === "logs";
     let configPath;
-    let port;
     let model;
     let fallbackModels;
     let memory;
     let envFile;
     let target;
-    let noConsole = false;
     let force = false;
     let foreground = false;
     let follow = false;
     let lines;
+    let run;
+    let all = false;
+    let since;
+    let until;
+    let dryRun = false;
     for (let i = 0; i < rest.length; i += 1) {
         const flag = rest[i];
         switch (flag) {
             case "--config":
                 configPath = requireValue(rest, ++i, flag);
                 break;
-            case "--port": {
-                const raw = requireValue(rest, ++i, flag);
-                const parsed = Number(raw);
-                if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65_535) {
-                    throw new Error("--port must be an integer between 0 and 65535.");
-                }
-                port = parsed;
+            case "--run":
+                run = requireValue(rest, ++i, flag);
+                break;
+            case "--all":
+                all = true;
+                break;
+            case "--since":
+                since = requireValue(rest, ++i, flag);
+                break;
+            case "--until":
+                until = requireValue(rest, ++i, flag);
+                break;
+            case "--dry-run":
+                dryRun = true;
                 break;
-            }
             case "--model":
                 model = requireValue(rest, ++i, flag);
                 break;
@@ -58,8 +76,8 @@ export function parseCliArgs(argv) {
                 break;
             case "--memory": {
                 const raw = requireValue(rest, ++i, flag);
-                if (raw !== "markdown" && raw !== "journal") {
-                    throw new Error("--memory must be markdown or journal.");
+                if (raw !== "lite" && raw !== "journal" && raw !== "bujo") {
+                    throw new Error("--memory must be lite, journal, or bujo.");
                 }
                 memory = raw;
                 break;
@@ -78,9 +96,6 @@ export function parseCliArgs(argv) {
             case "--force":
                 force = true;
                 break;
-            case "--no-console":
-                noConsole = true;
-                break;
             case "--foreground":
                 foreground = true;
                 break;
@@ -112,17 +127,20 @@ export function parseCliArgs(argv) {
     return {
         command: cmd,
         ...(configPath === undefined ? {} : { configPath }),
-        ...(port === undefined ? {} : { port }),
         ...(model === undefined ? {} : { model }),
         ...(fallbackModels === undefined ? {} : { fallbackModels }),
         ...(memory === undefined ? {} : { memory }),
         ...(envFile === undefined ? {} : { envFile }),
         ...(target === undefined ? {} : { target }),
-        noConsole,
         force,
         foreground,
         follow,
         ...(lines === undefined ? {} : { lines }),
+        ...(run === undefined ? {} : { run }),
+        all,
+        ...(since === undefined ? {} : { since }),
+        ...(until === undefined ? {} : { until }),
+        dryRun,
     };
 }
 /**
@@ -146,38 +164,66 @@ function requireValue(args, index, flag) {
     }
     return value;
 }
-const HELP_TEXT = `mono-agent — config-first agent host
-
-Usage:
-  mono-agent init [--model <ref>] [--fallback-models <csv>] [--memory markdown|journal]
-      Scaffold mono-agent.config.json, IDENTITY.md, and .mono-agent/ in the
-      current folder. Existing files are never overwritten.
-
-  mono-agent validate [--config <path>] [--env-file <path>]
-      Load every config section and report what would run, wait, or fail.
-
-  mono-agent start [--config <path>] [--port <n>] [--no-console] [--env-file <path>] [--foreground|-f]
-      Start the agent as a background macOS service (launchd), print its
-      instance info, and return. Re-running restarts the running instance.
-      Use --foreground (-f) to run in the blocking foreground instead.
-
-  mono-agent restart [--config <path>] [--port <n>] [--no-console]
-      Restart the background instance for this config (starts it if stopped).
-
-  mono-agent stop [--config <path>]
-      Stop the background instance and remove its LaunchAgent.
-
-  mono-agent status [--config <path>]
-      Show this config's instance plus any other running instances.
-
-  mono-agent logs [--config <path>] [--follow|-f] [--lines <n>]
-      Print (and optionally follow) the background instance's log files.
-
-  mono-agent install-skill [--target claude|codex|both] [--force]
-      Copy the bundled mono-agent-composer skill into ~/.claude/skills and
-      ~/.codex/skills (default: both). Refuses to overwrite without --force.
-
-Background mode runs the agent under launchd, keeping it alive across logins
+const HELP_COMMANDS = [
+    {
+        signature: "mono-agent init [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
+        lines: [
+            "Scaffold mono-agent.config.json, IDENTITY.md, and .mono-agent/ in the",
+            "current folder. Existing files are never overwritten.",
+        ],
+    },
+    {
+        signature: "mono-agent validate [--config <path>] [--env-file <path>]",
+        lines: ["Load every config section and report what would run, wait, or fail."],
+    },
+    {
+        signature: "mono-agent start [--config <path>] [--env-file <path>] [--foreground|-f]",
+        lines: [
+            "Start the agent as a background macOS service (launchd), print its",
+            "instance info, and return. Re-running restarts the running instance.",
+            "Refuses to start without a valid mono-agent.config.json in the folder.",
+            "Use --foreground (-f) to run in the blocking foreground instead.",
+        ],
+    },
+    {
+        signature: "mono-agent restart [--config <path>] [--force]",
+        lines: [
+            "Restart the background instance for this config (starts it if stopped).",
+            "--force also clears the persisted pi sessions so it starts with fresh",
+            "conversations instead of resuming saved ones (durable memory is untouched).",
+        ],
+    },
+    {
+        signature: "mono-agent stop [--config <path>]",
+        lines: ["Stop the background instance and remove its LaunchAgent."],
+    },
+    {
+        signature: "mono-agent status [--config <path>]",
+        lines: ["Show this config's instance plus any other running instances."],
+    },
+    {
+        signature: "mono-agent logs [--config <path>] [--follow|-f] [--lines <n>]",
+        lines: ["Print (and optionally follow) the background instance's log files."],
+    },
+    {
+        signature: "mono-agent install-skill [--target claude|codex|both] [--force]",
+        lines: [
+            "Copy the bundled mono-agent-composer skill into ~/.claude/skills and",
+            "~/.codex/skills (default: both). Refuses to overwrite without --force.",
+        ],
+    },
+    {
+        signature: "mono-agent backfill (--run <id> | --all) [--since <iso>] [--until <iso>]\n" +
+            "                    [--dry-run] [--config <path>] [--env-file <path>]",
+        lines: [
+            "Export already-recorded run artifacts to the configured Phoenix exporter",
+            "with their historical timestamps. Trace ids are deterministic per run, so",
+            "re-running overwrites rather than duplicating. --dry-run maps and",
+            "serializes without sending.",
+        ],
+    },
+];
+const HELP_NOTES = `Background mode runs the agent under launchd, keeping it alive across logins
 (auto-restarting only on crash) until you run stop. Secrets are read from the
 .env file in the working directory, the same as foreground mode. The background
 commands require macOS; elsewhere use start --foreground.
@@ -188,19 +234,38 @@ pi:<provider>:<model> (e.g. pi:ollama:gemma4:31b).
 A .env file in the current folder is loaded automatically when present;
 already-exported shell variables take precedence.
 `;
+/** Build the colorized help screen (plain text when color is disabled). */
+export function renderHelp() {
+    let out = ui.banner("mono-agent", "config-first agent host") + "\n";
+    out += ui.heading("Usage");
+    for (const entry of HELP_COMMANDS) {
+        const [first, ...rest] = entry.signature.split("\n");
+        out += `  ${ui.style.bold(ui.style.cyan(first ?? ""))}\n`;
+        for (const cont of rest) {
+            out += `  ${ui.style.cyan(cont)}\n`;
+        }
+        for (const line of entry.lines) {
+            out += `      ${ui.style.dim(line)}\n`;
+        }
+        out += "\n";
+    }
+    out += ui.style.dim(HELP_NOTES);
+    return out;
+}
 export async function runCli(argv) {
     let args;
     try {
         args = parseCliArgs(argv);
     }
     catch (error) {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP_TEXT}`);
+        process.stderr.write(ui.errorLine(error instanceof Error ? error.message : String(error)));
+        process.stdout.write(`\n${renderHelp()}`);
         return 2;
     }
     loadCliEnvFile(resolve(process.cwd(), args.envFile ?? ".env"));
     switch (args.command) {
         case "help":
-            process.stdout.write(HELP_TEXT);
+            process.stdout.write(renderHelp());
             return 0;
         case "init":
             return await runInit(args);
@@ -215,6 +280,15 @@ export async function runCli(argv) {
             return await runBackgroundCommand(args, args.command);
         case "install-skill":
             return await runInstallSkill(args);
+        case "backfill":
+            return await runBackfill({
+                ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
+                ...(args.run === undefined ? {} : { run: args.run }),
+                all: args.all,
+                ...(args.since === undefined ? {} : { since: args.since }),
+                ...(args.until === undefined ? {} : { until: args.until }),
+                dryRun: args.dryRun,
+            });
     }
 }
 async function runInit(args) {
@@ -225,18 +299,19 @@ async function runInit(args) {
         ...(args.memory === undefined ? {} : { memory: args.memory }),
     });
     for (const path of result.created) {
-        process.stdout.write(`created  ${path}\n`);
+        process.stdout.write(`${ui.badge("ok")}${ui.style.green("created")}  ${path}\n`);
     }
     for (const path of result.skipped) {
-        process.stdout.write(`kept     ${path}\n`);
+        process.stdout.write(ui.style.dim(`  kept     ${path}`) + "\n");
     }
     if (result.knowledgeFiles.length > 0) {
-        process.stdout.write(`\nIdentity references existing knowledge: ${result.knowledgeFiles.join(", ")}\n`);
+        process.stdout.write(`\nIdentity references existing knowledge: ${ui.style.cyan(result.knowledgeFiles.join(", "))}\n`);
     }
-    process.stdout.write("\nNext steps:\n" +
-        `  1. Edit ${result.configPath} (model, channels, skills, memory, sandbox).\n` +
-        "  2. mono-agent validate\n" +
-        "  3. mono-agent start\n");
+    process.stdout.write("\n" +
+        ui.heading("Next steps") +
+        `  ${ui.style.bold("1.")} Edit ${result.configPath} ${ui.style.dim("(model, channels, skills, memory, sandbox)")}\n` +
+        `  ${ui.style.bold("2.")} mono-agent validate\n` +
+        `  ${ui.style.bold("3.")} mono-agent start\n`);
     return 0;
 }
 async function runInstallSkill(args) {
@@ -248,11 +323,11 @@ async function runInstallSkill(args) {
         });
     }
     catch (error) {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(ui.errorLine(error instanceof Error ? error.message : String(error)));
         return 1;
     }
     for (const path of result.installed) {
-        process.stdout.write(`installed  ${path}\n`);
+        process.stdout.write(`${ui.badge("ok")}${ui.style.green("installed")}  ${path}\n`);
     }
     return 0;
 }
@@ -264,24 +339,72 @@ async function runValidate(args) {
         configPath: resolve(cwd, args.configPath ?? "mono-agent.config.json"),
     });
     for (const section of report.sections) {
-        process.stdout.write(`${statusIcon(section.status)} ${section.label}\n`);
-        for (const detail of section.details) {
-            process.stdout.write(`    ${detail}\n`);
-        }
+        process.stdout.write(formatSection(section));
     }
-    process.stdout.write(report.ok ? "\nConfig is ready to start.\n" : "\nFix the errors above, then re-run mono-agent validate.\n");
+    process.stdout.write(report.ok
+        ? `\n${ui.style.green("✓ Config is ready to start.")}\n`
+        : `\n${ui.hint("Fix the errors above, then re-run mono-agent validate.")}`);
     return report.ok ? 0 : 1;
 }
-function statusIcon(status) {
-    switch (status) {
-        case "ok":
-            return "[ok]      ";
-        case "waiting":
-            return "[waiting] ";
-        case "disabled":
-            return "[off]     ";
-        case "error":
-            return "[error]   ";
+/** Render one validation section: a status badge, a bold label, and its details. */
+function formatSection(section) {
+    let out = `${ui.badge(section.status)}${ui.style.bold(section.label)}\n`;
+    for (const detail of section.details) {
+        out += `    ${colorDetail(section.status, detail)}\n`;
+    }
+    return out;
+}
+function colorDetail(status, detail) {
+    if (status === "error") {
+        return ui.style.red(detail);
+    }
+    if (detail.startsWith("[WARN]")) {
+        return ui.style.yellow(detail);
+    }
+    return ui.style.dim(detail);
+}
+/**
+ * Gate for `start`/`restart`: refuse unless the directory has a present, valid
+ * config. First the config FILE must exist (env vars alone are not enough — a
+ * folder without a config is not a configured agent). Then run the structural
+ * validation with `liveness:false` (network probes only yield `waiting`, never
+ * `error`, so skipping them keeps the verdict but avoids ~6s of timeouts) and
+ * refuse on any `error` section. `waiting` (e.g. Ollama/Phoenix not up yet) is
+ * runtime-soft and never blocks.
+ */
+export async function ensureStartable(args) {
+    const cwd = process.cwd();
+    const configPath = resolve(cwd, args.configPath ?? "mono-agent.config.json");
+    if (!(await pathExists(configPath))) {
+        return { ok: false, code: 2, kind: "missing-config", configPath };
+    }
+    const report = await validateMonoAgentFolder({ env: process.env, cwd, configPath, liveness: false });
+    if (!report.ok) {
+        return { ok: false, code: 1, kind: "validation", report };
+    }
+    return { ok: true };
+}
+function printPreflightFailure(result) {
+    if (result.kind === "missing-config") {
+        process.stderr.write(ui.errorLine(`No mono-agent config found at ${result.configPath}.`));
+        process.stderr.write(ui.hint("Run `mono-agent init` to scaffold one, or pass --config <path>."));
+        return;
+    }
+    process.stderr.write(ui.heading("Cannot start: config has errors"));
+    for (const section of result.report.sections) {
+        if (section.status === "error") {
+            process.stderr.write(formatSection(section));
+        }
+    }
+    process.stderr.write(ui.hint("Run `mono-agent validate` for the full report, fix the errors, then retry."));
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
     }
 }
 async function runStart(args) {
@@ -292,33 +415,47 @@ async function runStart(args) {
 }
 /**
  * The blocking worker: builds the responder, starts every configured channel
- * plus the operator console and traceability, and stays alive until a signal.
- * This is what launchd invokes (via `start --foreground`) and what users get
- * with `--foreground`/`-f`.
+ * plus traceability, and stays alive until a signal. This is what launchd
+ * invokes (via `start --foreground`) and what users get with `--foreground`/`-f`.
  */
 async function runForeground(args) {
+    const pre = await ensureStartable(args);
+    if (!pre.ok) {
+        printPreflightFailure(pre);
+        return pre.code;
+    }
     const app = await startMonoAgentApp({
         cwd: process.cwd(),
         ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
-        ...(args.port === undefined ? {} : { operatorConsolePort: args.port }),
-        ...(args.noConsole ? { operatorConsole: false } : {}),
         logger: consoleLogger(),
     });
     printAppStatus(app);
-    installSignalHandlers(app);
-    return 0;
+    // Block until a shutdown signal. Returning here (the old behavior) let the
+    // process exit immediately whenever no channel owned a live handle — e.g. a
+    // traceability-only config, now that the operator console is retired and the
+    // trace heartbeat timer is unref'd.
+    return await waitForShutdownSignal(app);
 }
 async function runBackgroundCommand(args, command) {
     const guard = requireDarwin(command);
     if (guard !== undefined) {
         return guard;
     }
+    // Refuse to launch (or relaunch) an unconfigured/broken folder BEFORE writing
+    // the plist and bootstrapping launchctl — otherwise the worker would crash and
+    // launchd's KeepAlive would retry it forever. stop/status/logs stay ungated so
+    // a broken instance can still be inspected and torn down.
+    if (command === "start" || command === "restart") {
+        const pre = await ensureStartable(args);
+        if (!pre.ok) {
+            printPreflightFailure(pre);
+            return pre.code;
+        }
+    }
     const target = await resolveInstanceTarget({
         args: {
             ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
             ...(args.envFile === undefined ? {} : { envFile: args.envFile }),
-            ...(args.port === undefined ? {} : { port: args.port }),
-            noConsole: args.noConsole,
         },
         env: process.env,
         cwd: process.cwd(),
@@ -329,7 +466,7 @@ async function runBackgroundCommand(args, command) {
         case "start":
             return await startBackground(target, deps);
         case "restart":
-            return await restartBackground(target, deps);
+            return args.force ? await runForceRestart(target, deps) : await restartBackground(target, deps);
         case "stop":
             return await stopBackground(target, deps);
         case "status":
@@ -338,6 +475,27 @@ async function runBackgroundCommand(args, command) {
             return await tailLogs(target, deps, { follow: args.follow, lines: args.lines ?? DEFAULT_LOG_LINES });
     }
 }
+/**
+ * `restart --force`: stop the worker, purge its persisted pi-session store, then
+ * start fresh. Stopping first guarantees the worker is not writing sessions while
+ * they are deleted; the runtime recreates the store on the next session, and the
+ * agent's durable memory lives elsewhere, so only resumable transcripts are dropped.
+ */
+async function runForceRestart(target, deps) {
+    const stopCode = await stopBackground(target, deps);
+    if (stopCode !== 0) {
+        return stopCode;
+    }
+    const result = await purgeSessions({ env: process.env, cwd: target.cwd, configPath: target.configPath });
+    if (result.removed) {
+        const count = result.files === 0 ? "" : ` (${result.files} session file${result.files === 1 ? "" : "s"})`;
+        process.stdout.write(`${ui.badge("ok")}${ui.style.bold("Cleared persisted sessions")}${count}.\n`);
+    }
+    else {
+        process.stdout.write(ui.style.dim("No persisted sessions to clear (in-memory or none on disk).") + "\n");
+    }
+    return await startBackground(target, deps);
+}
 /**
  * Background service mode is launchd-specific. On other platforms point the
  * user at the still-supported blocking foreground path.
@@ -346,22 +504,53 @@ function requireDarwin(command) {
     if (process.platform === "darwin") {
         return undefined;
     }
-    process.stderr.write(`Background service mode (mono-agent ${command}) requires macOS (launchd).\n` +
-        "Run `mono-agent start --foreground` to run in the foreground on this platform.\n");
+    process.stderr.write(ui.errorLine(`Background service mode (mono-agent ${command}) requires macOS (launchd).`));
+    process.stderr.write(ui.hint("Run `mono-agent start --foreground` to run in the foreground on this platform."));
     return 1;
 }
-function printAppStatus(app) {
-    if (app.operatorConsole !== undefined) {
-        process.stdout.write(`operator console  ${app.operatorConsole.appUrl}\n`);
-    }
-    process.stdout.write(`config            ${app.configPath}\n`);
+export function printAppStatus(app) {
     const trace = app.traceabilityStatus;
-    process.stdout.write(trace.kind === "running"
-        ? `traceability      running (source ${trace.sourceId})\n`
-        : `traceability      ${trace.kind}: ${trace.reason}\n`);
-    for (const [id, status] of app.channelStatuses()) {
-        process.stdout.write(`${id.padEnd(17)} ${describeChannelStatus(status)}\n`);
+    process.stdout.write(ui.rule("instance"));
+    process.stdout.write(ui.keyValue([
+        ["config", app.configPath],
+        [
+            "traceability",
+            trace.kind === "running" ? `running (source ${trace.sourceId})` : `${trace.kind}: ${trace.reason}`,
+        ],
+    ], 2));
+    const artifactDir = app.traceabilityStatus.kind === "running" ? app.traceabilityStatus.artifactDir : undefined;
+    process.stdout.write(ui.rule("observability"));
+    process.stdout.write(`  ${describeExporter(app.exporterStatus, artifactDir)}\n`);
+    const channels = [...app.channelStatuses()];
+    if (channels.length > 0) {
+        process.stdout.write(ui.rule("channels"));
+        for (const [id, status] of channels) {
+            process.stdout.write(`  ${ui.channelBadge(status.kind)}${ui.style.bold(id.padEnd(11))} ${describeChannelStatus(status)}\n`);
+        }
+    }
+}
+function describeExporter(status, artifactDir) {
+    if (status.kind !== "configured") {
+        return `${status.kind}: ${status.reason}`;
+    }
+    const parts = [`phoenix ${status.endpoint}`];
+    const appUrl = phoenixAppBaseUrl(status.endpoint);
+    if (appUrl !== undefined) {
+        parts.push(`app ${appUrl}`);
+    }
+    if (status.includeSensitiveData) {
+        parts.push("includeSensitiveData=true");
     }
+    if (status.lastWarning !== undefined) {
+        parts.push(`last warning: ${status.lastWarning}`);
+    }
+    if (status.lastError !== undefined) {
+        parts.push(`last error: ${status.lastError}`);
+    }
+    parts.push(artifactDir === undefined
+        ? "JSONL artifacts remain local"
+        : `JSONL artifacts remain local at ${artifactDir}`);
+    return parts.join("; ");
 }
 function describeChannelStatus(status) {
     if (status.kind === "running") {
@@ -372,19 +561,34 @@ function describeChannelStatus(status) {
     }
     return `${status.kind}: ${status.reason}`;
 }
-function installSignalHandlers(app) {
-    let stopping = false;
-    const stop = async (signal) => {
-        if (stopping) {
-            return;
-        }
-        stopping = true;
-        process.stdout.write(`\nReceived ${signal}; stopping mono agent app...\n`);
-        await app.stop();
-        process.exit(0);
-    };
-    process.on("SIGINT", () => void stop("SIGINT"));
-    process.on("SIGTERM", () => void stop("SIGTERM"));
+/**
+ * Block the foreground process until SIGINT/SIGTERM, then stop the app and
+ * resolve the exit code. A referenced no-op timer owns the event loop so the
+ * process stays alive even with no channel handle (signal listeners alone do
+ * NOT keep Node running, and the trace heartbeat is unref'd). Cleared on stop so
+ * the loop drains cleanly without a forceful `process.exit`. Exported for tests.
+ */
+export function waitForShutdownSignal(app) {
+    return new Promise((resolve) => {
+        const keepAlive = setInterval(() => { }, KEEP_ALIVE_INTERVAL_MS);
+        let stopping = false;
+        const onSignal = (signal) => {
+            if (stopping) {
+                return;
+            }
+            stopping = true;
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            clearInterval(keepAlive);
+            void (async () => {
+                process.stdout.write("\n" + ui.hint(`Received ${signal}; stopping mono agent app…`));
+                await app.stop();
+                resolve(0);
+            })();
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    });
 }
 function consoleLogger() {
     return {
@@ -409,7 +613,7 @@ if (isDirectCliInvocation) {
         }
     })
         .catch((error) => {
-        process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+        process.stderr.write(`${ui.style.red("✗")} ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
         process.exitCode = 1;
     });
 }