ima2-gen 3.9.0 → 3.10.0

package/README.md

@@ -16,9 +16,9 @@
 
 `ima2-gen` is a local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.
 
-Install globally and generate images and videos from eight core lanes: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, and MiniMax. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup.
+Install globally and generate images and videos from eight core lanes: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, and MiniMax. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup — now with one-click GPT background transparency (server-verified real alpha), annotation hover feedback, and a full light/dark/system theme.
 
-![ima2-gen video playback with gallery sidebar showing generated images and videos.](assets/screenshots/classic-generate-light.png)
+![ima2-gen classic workspace in light mode with a transparent-background result on the canvas.](assets/screenshots/classic-generate-lightmode.png)
 
 ## Quick Start
 
@@ -91,6 +91,7 @@ Video generation requires Grok OAuth (option 2 or 3). Run `ima2 grok login` sepa
 ### Updating
 
 Stop the running server with Ctrl+C, then:
+(or from another terminal: `ima2 stop`)
 
 ```bash
 npm install -g ima2-gen@latest
@@ -105,7 +106,8 @@ Ctrl+C now performs a clean shutdown — closing the database, stopping child pr
 - **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
 - **Video generation**: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done. Video frame copy buttons (First/Mid/Last) let you extract and copy keyframes from generated videos.
 - **Storyboard mode**: toggle storyboard mode in the composer to maintain character and scene continuity across sequential frames. Works with both image and video generation — image keyframes are composed for video production, and video clips inherit character/environment lock rules.
-- **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
+- **Canvas Mode**: zoom, pan, annotate (with hover highlighting), erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions. A one-click **GPT transparency** button sends the current image through the i2i edit lane and reports honestly whether the result carries real pixel alpha — verified on the server, never trusted from provider metadata.
+- **Light & dark themes**: a token-based light mode with tinted neutrals and AA contrast, switchable between light / dark / system in Settings, with no flash on load.
 - **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
 - **Reference images**: drag, drop, paste, and attach up to 5 references (images) or up to 7 references (video); large images are compressed before upload.
 - **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
@@ -212,9 +214,13 @@ Use Canvas Mode when a generated image is close but needs targeted cleanup befor
 - Pick background-cleanup seeds, preview the mask, and save the cleanup as a canvas version.
 - Detect transparent images and show a checkerboard preview; export with preserved alpha or with a chosen matte color.
 - Saved canvas versions stay hidden from Gallery and HistoryStrip, but Canvas Mode can reuse them and attach a canvas version as the next reference.
+- Hover any annotation with the select tool to see a live outline and a move cursor before you click.
+- Press the **GPT transparency** button in the canvas toolbar to remove the background through the OAuth i2i lane in one click. The server decodes the returned bytes and reports `alphaVerified` — the toast tells you whether real transparency actually landed, instead of assuming.
 
 ![Canvas Mode with zoom controls, annotation marks, a sticky note, and the canvas toolbar.](assets/screenshots/canvas-mode-cleanup.png)
 
+![Canvas Mode in light theme with the one-click GPT transparency flow and a transparent checkerboard result.](assets/screenshots/canvas-mode-light-transparency.png)
+
 ### Prompt Library And Imports
 
 The prompt library can now be filled from local files, GitHub folders, curated sources, and GPT-image hint packs. Imported prompts are indexed locally so search and ranking work without re-importing the same source every session.
@@ -230,9 +236,12 @@ be treated as a stable public feature yet.
 ### Settings
 
 The settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.
+Appearance now includes a light / dark / system theme toggle; the light palette uses tinted neutrals with AA contrast and applies before first paint.
 
 ![Settings workspace with account navigation and generation model controls.](assets/screenshots/settings-workspace.png)
 
+![Settings appearance section with the light, dark, and system theme toggle in light mode.](assets/screenshots/settings-theme-toggle.png)
+
 ## CLI Commands
 
 ### Server
@@ -240,6 +249,8 @@ The settings workspace keeps account, model, appearance, and language controls a
 | Command | Description |
 |---|---|
 | `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |
+| `ima2 stop [--force]` | Stop the running server safely — graceful admin-API stop first, then SIGTERM/SIGKILL; verifies the advertised pid against `/api/health` so a recycled pid is never killed |
+| `ima2 service <sub>` | Background service: `install`/`uninstall`/`start`/`stop`/`restart`/`status`/`logs`/`repair` — launchd on macOS, systemd user unit on Linux, auto-start on login with crash restart |
 | `ima2 setup` | Reconfigure saved auth |
 | `ima2 status` | Show config and OAuth status |
 | `ima2 doctor` | Diagnose Node, package, config, and auth |

package/bin/commands/service.js

@@ -0,0 +1,450 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LAUNCHD_LABEL, SYSTEMD_UNIT, launchctlOutputIndicatesFailure, renderLaunchdPlist, renderSystemdUnit, serviceStateStale, } from "../lib/serviceTemplates.js";
+import { corroborateByStartTime, escalateKill, gracefulStop, isProcessAlive, verifyServerIdentity, waitForExit, } from "../../lib/processControl.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+function configDir() {
+    return process.env.IMA2_CONFIG_DIR || join(homedir(), ".ima2");
+}
+function stateFile() {
+    return join(configDir(), "service-state.json");
+}
+function logDir() {
+    return join(configDir(), "logs");
+}
+function plistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+function unitPath() {
+    return join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT);
+}
+function advertisePath() {
+    return process.env.IMA2_ADVERTISE_FILE || join(configDir(), "server.json");
+}
+function readState() {
+    try {
+        return JSON.parse(readFileSync(stateFile(), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function currentPaths() {
+    return { nodePath: process.execPath, serverJs: join(ROOT, "server.js") };
+}
+function renderInput() {
+    const cur = currentPaths();
+    return {
+        nodePath: cur.nodePath,
+        serverJs: cur.serverJs,
+        rootDir: ROOT,
+        pathEnv: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+        logDir: logDir(),
+        configDir: process.env.IMA2_CONFIG_DIR,
+    };
+}
+function run(cmd, args) {
+    try {
+        const stdout = execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        return { ok: true, stdout, stderr: "" };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, stdout: err.stdout ?? "", stderr: err.stderr ?? err.message ?? "" };
+    }
+}
+function guiDomain() {
+    return `gui/${process.getuid?.() ?? 501}`;
+}
+function writeState() {
+    const cur = currentPaths();
+    const state = {
+        version: 1,
+        platform: process.platform,
+        nodePath: cur.nodePath,
+        serverJs: cur.serverJs,
+        configDir: configDir(),
+        installedAt: Date.now(),
+    };
+    mkdirSync(dirname(stateFile()), { recursive: true });
+    writeFileSync(stateFile(), JSON.stringify(state, null, 2));
+}
+function readAdvertise() {
+    try {
+        return JSON.parse(readFileSync(advertisePath(), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForHealth(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const entry = readAdvertise();
+        if (entry?.url) {
+            try {
+                const r = await fetch(`${String(entry.url).replace(/\/$/, "")}/api/health`, { headers: { connection: "close" } });
+                if (r.ok)
+                    return { ok: true, entry };
+            }
+            catch { /* keep polling */ }
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return { ok: false, entry: readAdvertise() };
+}
+function reportProviderLiveness(entry) {
+    if (!entry)
+        return;
+    const oauth = entry.oauth;
+    const grok = entry.grok;
+    if (oauth?.status && oauth.status !== "ready" && oauth.status !== "disabled") {
+        console.log(`  Warning: GPT OAuth proxy status is "${oauth.status}" — check 'ima2 service logs'.`);
+    }
+    // grok.live only exists in the advertise payload, not /api/health (audit note).
+    if (grok && grok.live === false) {
+        console.log("  Warning: Grok proxy is not live under the service environment.");
+        console.log("  If Grok worked in a terminal, the service PATH may be missing its binary.");
+    }
+}
+// ── macOS (launchd) ──
+async function macInstall() {
+    mkdirSync(logDir(), { recursive: true });
+    mkdirSync(dirname(plistPath()), { recursive: true });
+    writeFileSync(plistPath(), renderLaunchdPlist(renderInput()));
+    const boot = await macBootstrapWithRetry();
+    if (!boot.ok || launchctlOutputIndicatesFailure(boot.stderr)) {
+        const legacy = run("/bin/launchctl", ["load", "-w", plistPath()]);
+        if (!legacy.ok || launchctlOutputIndicatesFailure(legacy.stderr)) {
+            console.error(`  launchctl could not load the service: ${boot.stderr || legacy.stderr || "unknown"}`);
+            return false;
+        }
+    }
+    writeState();
+    return true;
+}
+async function macBootout() {
+    run("/bin/launchctl", ["bootout", `${guiDomain()}/${LAUNCHD_LABEL}`]);
+    // bootout is asynchronous: bootstrapping again while the old job is still
+    // draining fails with "Bootstrap failed: 5: Input/output error" (hit live
+    // during 040 verification — restart left the service unregistered). Wait for
+    // the registration to actually disappear before letting a start proceed.
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline && macRegistered()) {
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    // Honest outcome: a job still registered after the drain window is a FAILED
+    // bootout, not a success to report (audit P2).
+    return !macRegistered();
+}
+async function macBootstrapWithRetry() {
+    let last = { ok: false, stdout: "", stderr: "never attempted" };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        last = run("/bin/launchctl", ["bootstrap", guiDomain(), plistPath()]);
+        const failed = !last.ok || launchctlOutputIndicatesFailure(last.stderr);
+        if (!failed && macRegistered())
+            return { ...last, ok: true };
+        await new Promise((r) => setTimeout(r, 1000));
+        if (macRegistered())
+            return { ...last, ok: true };
+    }
+    return last;
+}
+function macRegistered() {
+    const r = run("/bin/launchctl", ["print", `${guiDomain()}/${LAUNCHD_LABEL}`]);
+    return r.ok;
+}
+// ── Linux (systemd user unit) ──
+function linuxInstall() {
+    mkdirSync(logDir(), { recursive: true });
+    mkdirSync(dirname(unitPath()), { recursive: true });
+    writeFileSync(unitPath(), renderSystemdUnit(renderInput()));
+    const reload = run("systemctl", ["--user", "daemon-reload"]);
+    if (!reload.ok) {
+        console.error(`  systemctl daemon-reload failed: ${reload.stderr}`);
+        return false;
+    }
+    const enable = run("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT]);
+    if (!enable.ok) {
+        console.error(`  systemctl enable --now failed: ${enable.stderr}`);
+        return false;
+    }
+    writeState();
+    return true;
+}
+// ── shared flows ──
+/**
+ * Stop whatever server the advertise file names — same doctrine as
+ * `ima2 stop` (audit blocker 2): graceful admin-API first, identity-verified
+ * signals second, and NEVER a signal to a pid we cannot corroborate.
+ */
+async function stopLiveServer() {
+    const entry = readAdvertise();
+    if (!entry?.pid)
+        return;
+    const pid = Number(entry.pid);
+    if (!isProcessAlive(pid)) {
+        try {
+            unlinkSync(advertisePath());
+        }
+        catch { /* gone already */ }
+        return;
+    }
+    const identity = await verifyServerIdentity(entry);
+    if (identity === "mismatch") {
+        console.log(`  Note: a different server answers where pid ${pid} was advertised; leaving it alone.`);
+        try {
+            unlinkSync(advertisePath());
+        }
+        catch { /* stale */ }
+        return;
+    }
+    if (identity === "unreachable") {
+        const corroboration = corroborateByStartTime(pid, Number(entry.startedAt) || undefined);
+        if (corroboration !== "corroborated") {
+            console.log(`  Note: pid ${pid} could not be identified as the ima2 server; not signalling it.`);
+            if (corroboration === "recycled") {
+                try {
+                    unlinkSync(advertisePath());
+                }
+                catch { /* stale */ }
+            }
+            return;
+        }
+    }
+    if (identity === "match" && (await gracefulStop(entry)) && (await waitForExit(pid, 8000))) {
+        try {
+            unlinkSync(advertisePath());
+        }
+        catch { /* server removed it */ }
+        return;
+    }
+    await escalateKill(pid);
+    try {
+        unlinkSync(advertisePath());
+    }
+    catch { /* gone */ }
+}
+async function install() {
+    if (process.platform === "win32") {
+        console.log("\n  Windows service management is not built in yet.");
+        console.log("  Register manually with Task Scheduler: run at logon,");
+        console.log(`  program: ${currentPaths().nodePath}`);
+        console.log(`  arguments: ${currentPaths().serverJs}\n`);
+        return;
+    }
+    // A manually-started server would fight the KeepAlive service over the port.
+    await stopLiveServer();
+    const ok = process.platform === "darwin" ? await macInstall() : linuxInstall();
+    if (!ok) {
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\n  Service installed (${process.platform === "darwin" ? "launchd" : "systemd user unit"}).`);
+    const health = await waitForHealth(12_000);
+    if (health.ok) {
+        console.log(`  Server is up at ${health.entry?.url} (pid ${health.entry?.pid}).`);
+        reportProviderLiveness(health.entry);
+    }
+    else {
+        console.log("  Service registered but the server has not answered /api/health yet.");
+        console.log("  Inspect: ima2 service logs\n");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("");
+}
+async function uninstall() {
+    if (process.platform === "win32") {
+        console.log("\n  Windows service management is not built in yet — nothing to uninstall.\n");
+        return;
+    }
+    if (process.platform === "darwin") {
+        const drained = await macBootout();
+        if (!drained) {
+            console.error("  Warning: launchctl still reports the job registered; artifacts removed anyway.");
+        }
+        try {
+            unlinkSync(plistPath());
+        }
+        catch { /* absent is fine */ }
+    }
+    else if (process.platform === "linux") {
+        run("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT]);
+        try {
+            unlinkSync(unitPath());
+        }
+        catch { /* absent is fine */ }
+        run("systemctl", ["--user", "daemon-reload"]);
+    }
+    try {
+        unlinkSync(stateFile());
+    }
+    catch { /* absent is fine */ }
+    await stopLiveServer();
+    console.log("\n  Service uninstalled. Server stopped.\n");
+}
+async function start() {
+    if (process.platform === "darwin") {
+        if (!existsSync(plistPath())) {
+            console.error("\n  No service installed. Run 'ima2 service install' first.\n");
+            process.exitCode = 1;
+            return;
+        }
+        const boot = await macBootstrapWithRetry();
+        if (!boot.ok && !macRegistered()) {
+            console.error(`\n  launchctl bootstrap failed: ${boot.stderr}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else if (process.platform === "linux") {
+        run("systemctl", ["--user", "start", SYSTEMD_UNIT]);
+    }
+    const health = await waitForHealth(12_000);
+    console.log(health.ok ? `\n  Service started — ${health.entry?.url}\n` : "\n  Start issued; server not answering yet. See 'ima2 service logs'.\n");
+}
+async function stopSvc() {
+    // bootout (not kill): with KeepAlive, killing the pid just respawns it.
+    if (process.platform === "win32") {
+        console.log("\n  Windows service management is not built in yet.\n");
+        process.exitCode = 1;
+        return;
+    }
+    if (process.platform === "darwin") {
+        const drained = await macBootout();
+        if (!drained) {
+            console.error("\n  launchctl bootout did not take — the job is still registered.");
+            console.error(`  Inspect: launchctl print gui/$UID/${LAUNCHD_LABEL}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else if (process.platform === "linux")
+        run("systemctl", ["--user", "stop", SYSTEMD_UNIT]);
+    await stopLiveServer();
+    console.log("\n  Service stopped (registration removed until 'ima2 service start').\n");
+}
+async function status() {
+    if (process.platform === "win32") {
+        console.log("\n  Windows service management is not built in yet; no status to report.\n");
+        return;
+    }
+    const state = readState();
+    const installedArtifact = process.platform === "darwin" ? plistPath() : unitPath();
+    const artifactExists = existsSync(installedArtifact);
+    console.log("\n  ima2 service status\n");
+    console.log(`  Artifact: ${installedArtifact} ${artifactExists ? "✓" : "✗ (not installed)"}`);
+    if (process.platform === "darwin") {
+        console.log(`  launchd registration: ${macRegistered() ? "✓ loaded" : "✗ not loaded"}`);
+    }
+    else if (process.platform === "linux") {
+        const st = run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
+        console.log(`  systemd unit: ${st.stdout.trim() || st.stderr.trim()}`);
+        const linger = run("loginctl", ["show-user", process.env.USER || "", "--property=Linger"]);
+        if (linger.ok && linger.stdout.includes("Linger=no")) {
+            console.log("  Note: lingering is off — the service stops when you log out.");
+            console.log("  Enable with: loginctl enable-linger $USER");
+        }
+    }
+    if (state) {
+        const stale = serviceStateStale(state, { ...currentPaths(), configDir: configDir() });
+        console.log(`  Installed: ${new Date(state.installedAt).toLocaleString()} (node ${state.nodePath})`);
+        for (const issue of stale)
+            console.log(`  Stale: ${issue} — run 'ima2 service repair'`);
+    }
+    else {
+        console.log("  State file: none");
+    }
+    const entry = readAdvertise();
+    if (entry?.pid && isProcessAlive(Number(entry.pid))) {
+        console.log(`  Live server: pid ${entry.pid} at ${entry.url}`);
+        reportProviderLiveness(entry);
+    }
+    else {
+        console.log("  Live server: none");
+    }
+    console.log("");
+}
+function logs(args) {
+    const nFlag = args.indexOf("-n");
+    const n = Math.max(1, (nFlag >= 0 ? Number(args[nFlag + 1]) : NaN) || 50);
+    if (process.platform === "linux") {
+        const r = run("journalctl", ["--user", "-u", SYSTEMD_UNIT, "-n", String(n), "--no-pager"]);
+        console.log(r.stdout || r.stderr);
+        return;
+    }
+    for (const f of ["service.out.log", "service.err.log"]) {
+        const p = join(logDir(), f);
+        if (!existsSync(p))
+            continue;
+        console.log(`\n── ${p} (last ${n} lines) ──`);
+        const lines = readFileSync(p, "utf-8").split("\n");
+        console.log(lines.slice(-n).join("\n"));
+    }
+    console.log("");
+}
+async function repair() {
+    if (!readState() && !existsSync(plistPath()) && !existsSync(unitPath())) {
+        console.error("\n  Nothing to repair — no service installed.\n");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("\n  Re-rendering service artifacts for the current paths...");
+    if (process.platform === "darwin")
+        await macBootout();
+    else if (process.platform === "linux")
+        run("systemctl", ["--user", "stop", SYSTEMD_UNIT]);
+    await install();
+}
+const HELP = `
+  ima2 service — run the server as a background service
+
+  Subcommands:
+    install     Register (launchd/systemd), start now + on login, auto-restart
+    uninstall   Deregister, remove artifacts, stop the server
+    start       Re-register a stopped service
+    stop        Stop and deregister until 'start' (KeepAlive-safe)
+    restart     stop + start
+    status      Artifact / registration / state / live-server report
+    logs [-n N] Show service logs (default 50 lines)
+    repair      Re-render artifacts after node/npm path moves
+`;
+export async function service(args = []) {
+    const sub = args[0];
+    switch (sub) {
+        case "install":
+            await install();
+            break;
+        case "uninstall":
+            await uninstall();
+            break;
+        case "start":
+            await start();
+            break;
+        case "stop":
+            await stopSvc();
+            break;
+        case "restart":
+            await stopSvc();
+            await start();
+            break;
+        case "status":
+            await status();
+            break;
+        case "logs":
+            logs(args.slice(1));
+            break;
+        case "repair":
+            await repair();
+            break;
+        default:
+            console.log(HELP);
+            if (sub && sub !== "-h" && sub !== "--help")
+                process.exitCode = 1;
+    }
+}

package/bin/commands/stop.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { corroborateByStartTime, escalateKill, gracefulStop, isProcessAlive, verifyServerIdentity, waitForExit, } from "../../lib/processControl.js";
+function advertisePath() {
+    return (process.env.IMA2_ADVERTISE_FILE ||
+        join(process.env.IMA2_CONFIG_DIR || join(homedir(), ".ima2"), "server.json"));
+}
+function readAdvertise(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function cleanupAdvertise(path, pid) {
+    try {
+        const cur = readAdvertise(path);
+        if (cur && (pid === undefined || cur.pid === pid))
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort */
+    }
+}
+/**
+ * `ima2 stop [--force]` — stop the running ima2 server safely.
+ *
+ * Sequence: advertise file → pid identity verification (never kill a recycled
+ * pid) → graceful admin-API stop → SIGTERM → SIGKILL escalation → stale-file
+ * cleanup. Idempotent: "not running" exits 0.
+ */
+export async function stop(args = []) {
+    const force = args.includes("--force");
+    const path = advertisePath();
+    const entry = readAdvertise(path);
+    if (!entry || !entry.pid) {
+        if (entry === null && existsSync(path)) {
+            cleanupAdvertise(path, undefined);
+            console.log("\n  Removed unreadable advertise file. No server to stop.\n");
+            return;
+        }
+        console.log("\n  ima2 server is not running.\n");
+        return;
+    }
+    const pid = Number(entry.pid);
+    if (!isProcessAlive(pid)) {
+        cleanupAdvertise(path, pid);
+        console.log(`\n  ima2 server (pid ${pid}) is not running. Cleaned stale advertise file.\n`);
+        return;
+    }
+    if (process.platform === "win32") {
+        console.log("\n  'ima2 stop' is not supported on Windows yet (SIGTERM would orphan");
+        console.log("  the provider proxies). Stop the server from its own terminal (Ctrl+C)");
+        console.log(`  or: taskkill /PID ${pid} /T\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // Service-managed? KeepAlive will resurrect a plain kill — refuse without --force
+    // (ownership refusal, mirroring opencodex's 409 semantics in spirit).
+    const stateFile = join(process.env.IMA2_CONFIG_DIR || join(homedir(), ".ima2"), "service-state.json");
+    if (existsSync(stateFile)) {
+        if (!force) {
+            console.log("\n  ima2 is installed as a background service: KeepAlive would restart");
+            console.log("  the server immediately after this stop, so it would be a lie.");
+            console.log("  Use 'ima2 service stop' — or 'ima2 stop --force' to kill it anyway.\n");
+            process.exitCode = 1;
+            return;
+        }
+        console.log("\n  --force: stopping a service-managed server; KeepAlive may restart it.\n");
+    }
+    const identity = await verifyServerIdentity(entry);
+    if (identity === "mismatch") {
+        cleanupAdvertise(path, pid);
+        console.log(`\n  A different server answers where pid ${pid} was advertised.`);
+        console.log("  Refusing to kill a process the advertise file cannot vouch for.");
+        console.log("  Cleaned the stale advertise file; stop the other server from its own CLI.\n");
+        return;
+    }
+    if (identity === "unreachable") {
+        // HTTP says nothing — corroborate with the process start time before ANY
+        // signal. A recycled pid is provably younger than the advertised boot;
+        // when we cannot tell, we refuse rather than guess (audit blocker 1).
+        const corroboration = corroborateByStartTime(pid, Number(entry.startedAt) || undefined);
+        if (corroboration !== "corroborated") {
+            console.log(`\n  pid ${pid} is alive but the server is unreachable, and its start time`);
+            console.log(corroboration === "recycled"
+                ? "  shows it is NOT the advertised server (the pid was recycled)."
+                : "  could not be corroborated against the advertise file.");
+            console.log("  Refusing to send signals to a process that may not be ours.");
+            if (corroboration === "recycled")
+                cleanupAdvertise(path, pid);
+            else
+                console.log(`  If you are sure, stop it manually: kill ${pid}`);
+            console.log("");
+            process.exitCode = corroboration === "recycled" ? 0 : 1;
+            return;
+        }
+    }
+    if (!force && identity === "match") {
+        const ok = await gracefulStop(entry);
+        if (ok && (await waitForExit(pid, 8000))) {
+            cleanupAdvertise(path, pid);
+            console.log(`\n  Stopped ima2 server (pid ${pid}) gracefully.\n`);
+            return;
+        }
+    }
+    const outcome = await escalateKill(pid);
+    switch (outcome) {
+        case "already-dead":
+            console.log(`\n  ima2 server (pid ${pid}) had already exited.\n`);
+            break;
+        case "term":
+            console.log(`\n  Stopped ima2 server (pid ${pid}) with SIGTERM.\n`);
+            break;
+        case "kill":
+            console.log(`\n  Force-killed ima2 server (pid ${pid}) with SIGKILL.`);
+            console.log("  Note: helper proxies may have been left behind; they exit on their own.\n");
+            break;
+        case "failed":
+            console.error(`\n  Could not stop pid ${pid}. Try: kill -9 ${pid}\n`);
+            process.exitCode = 1;
+            return;
+    }
+    cleanupAdvertise(path, pid);
+}

package/bin/ima2.js

@@ -341,6 +341,8 @@ function showHelp() {
     capabilities   Agent capability metadata       (ima2 capabilities --help)
     tools          Machine tool contracts for agents (ima2 tools --help)
     ping           Ping running server / check health
+    stop           Stop the running server safely (graceful, then signals)
+    service        Background service management (install/status/... ; -h)
 
   Agent skills (SKILL.md + references/):
     skill ls                         List packaged skills (ima2, front, uiux)
@@ -400,7 +402,7 @@ if (args.includes("-v") || args.includes("--version")) {
     console.log(pkg.version);
     exitFlushed(0);
 }
-const helpOwningCommands = ["doctor", "gen", "video", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs"];
+const helpOwningCommands = ["doctor", "gen", "video", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs", "service"];
 if (!command) {
     showHelp();
     exitFlushed(1);
@@ -413,6 +415,18 @@ switch (command) {
     case "serve":
         serve(args.slice(1));
         break;
+    case "stop": {
+        const { stop } = await import("./commands/stop.js");
+        await stop(args.slice(1));
+        exitFlushed(Number(process.exitCode ?? 0));
+        break;
+    }
+    case "service": {
+        const { service } = await import("./commands/service.js");
+        await service(args.slice(1));
+        exitFlushed(Number(process.exitCode ?? 0));
+        break;
+    }
     case "setup":
     case "login":
         setup().then(() => console.log("  Done. Run 'ima2 serve' to start.")).catch((e) => {