@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/cli/lib/commands/restart.js

@@ -0,0 +1,94 @@
+// `kabmo restart` — stop live instances, then serve again.
+//
+// Scoping matches `status` and `stop`: without `--port` every live instance is
+// considered, and `--port <port>` restricts the restart to that one. With
+// nothing running, the command is simply `serve`.
+//
+// Instances the CLI did not start are left alone, exactly as `kabmo update`
+// leaves them: `bun run dev` and `bun run start` own their own process, so
+// replacing it would break a loop Kabmo does not manage. `kabmo stop
+// --port <port>` (or `--all`) is the deliberate way to end one.
+
+import { findLiveInstance, listLiveInstances } from '@/cli/lib/runtime.js';
+import { stopInstance } from '@/cli/lib/stop-instance.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { log, warn, isJson, isQuiet } from '@/cli/lib/output.js';
+import { run as runServe } from '@/cli/lib/commands/serve.js';
+import { restartAuthWarning, restartServeOptions } from '@/cli/lib/restart-scope.js';
+import { skipRestartNote } from '@/server/lib/lifecycle/restart';
+import { isCliManaged } from '@/server/lib/lifecycle/launch-mode';
+import { PASSWORD_HANDOVER_ENV, PASSWORD_HANDOVER_STDIN } from '@/shared/lib/auth/handover';
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * The credential payload a restarting server wrote to our stdin, verbatim.
+ *
+ * Null when no marker was set — a plain `kabmo restart` from a shell has a
+ * terminal there, and reading it would hang the command. `Bun.stdin.text()`
+ * ends at EOF, which the writer always produces.
+ */
+async function readStdinHandoverPayload() {
+  if (Bun.env[PASSWORD_HANDOVER_ENV] !== PASSWORD_HANDOVER_STDIN) return null;
+  delete Bun.env[PASSWORD_HANDOVER_ENV];
+  try {
+    const text = await Bun.stdin.text();
+    return text.trim().length > 0 ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function run(options, ctx) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const requested = explicitPort(options);
+
+  // A restarting SERVER hands its already-hashed credential over on stdin (see
+  // `lib/lifecycle/restart.ts`). It must survive this process and reach the
+  // server spawned below, or every restart would silently drop authentication:
+  // measured, a run started with `--ui-password` came back `required: false`.
+  // The payload is forwarded verbatim — this process never needs to parse it.
+  const handoverPayload = await readStdinHandoverPayload();
+
+  const targets = requested !== null
+    ? [await findLiveInstance(requested)].filter(Boolean)
+    : await listLiveInstances();
+
+  if (targets.length === 0) return runServe({ ...options, handoverPayload }, ctx);
+
+  let failures = 0;
+  for (const live of targets) {
+    if (!isCliManaged(live.launchMode)) {
+      if (!json && !quiet) log(`Skipping Kabmo on port ${live.port}: ${skipRestartNote(live.launchMode)}.`);
+      continue;
+    }
+
+    if (!json && !quiet) log(`Stopping Kabmo on port ${live.port} (pid ${live.pid})...`);
+    // A stop that did not take must not be followed by a start: the port is
+    // still held, so `serve` would fail on the port guard and read as the
+    // restart's own failure. Report it here, where the cause is.
+    const gone = await stopInstance(live, { timeoutMs: STOP_TIMEOUT_MS });
+    if (!gone) {
+      warn(`Kabmo on port ${live.port} (pid ${live.pid}) is still running — not restarting it.`);
+      failures += 1;
+      continue;
+    }
+
+    // Reuse the recorded port/host/mode/flags so an instance started on a
+    // non-default port, bound to the LAN, serving TLS or showing a tray icon
+    // comes back the way it was found. Production is the default, so only a
+    // recorded dev instance asks for `--dev`.
+    const authWarning = restartAuthWarning(live, handoverPayload);
+    if (authWarning && !json) warn(authWarning);
+
+    await runServe({ ...restartServeOptions(live, options), handoverPayload }, ctx);
+  }
+
+  if (failures > 0) process.exitCode = 1;
+}

package/src/cli/lib/commands/serve.js

@@ -0,0 +1,278 @@
+// `kabmo serve` — start Kabmo server.
+//
+// Two flags live here beyond the server's own options, and both are about the
+// process tree rather than about the listener:
+//
+//   --tray       the server raises a menu-bar/notification-area icon for itself
+//   --startup    the server is registered to start at login (implying --tray now)
+//   --no-startup the login entry is removed
+//
+// `--startup`/`--no-startup` are handled by the CLI rather than by the server,
+// because they write a file outside the data directory (`~/Library/LaunchAgents`,
+// `$XDG_CONFIG_HOME/autostart`, `HKCU\...\Run`) — the one thing a running server
+// has no business doing behind the operator's back. The entry it writes runs the
+// SERVER in the foreground with `--tray`, so the login-started instance is a
+// first-class one: `status`, `logs` and `stop` all find it.
+
+import { joinPath, resolvePath } from '@/cli/lib/path-utils.js';
+import {
+  spawnDetachedServer,
+  buildServeInvocation,
+  waitForHealth,
+  findLiveInstance,
+  resolveBunBin,
+} from '@/cli/lib/runtime.js';
+import { buildProductionBundle } from '@/cli/lib/build.js';
+import { probeHost } from '@/server/lib/lifecycle/probe';
+import { log, ok, warn, fail, printJson, isJson, isQuiet } from '@/cli/lib/output.js';
+import { wireChildProcessLifecycle } from '@/cli/lib/process-lifecycle.js';
+import { reportUiAuth, resolveUiPassword, uiPasswordHandover } from '@/cli/lib/ui-password.js';
+import { PASSWORD_HANDOVER_ENV, PASSWORD_HANDOVER_STDIN } from '@/shared/lib/auth/handover';
+import { UI_PASSWORD_ENV } from '@/shared/lib/auth/password';
+import { getLogFilePath } from '@/cli/lib/paths.js';
+import { resolveServeMode } from '@/cli/lib/serve-mode.js';
+import { ompStartupError } from '@/server/lib/omp/core/startup';
+import { installAutostart, removeLegacyAutostart, uninstallAutostart, getAutostartEntryPath } from '@/server/lib/tray/autostart';
+import { getAutostartCredentialPath, removeAutostartCredential, writeAutostartCredential } from '@/server/lib/tray/credential';
+import { buildLoginEntryArgv } from '@/server/lib/tray/entry';
+
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOST = '127.0.0.1';
+
+export function resolvePort(options) {
+  const raw = options?.port;
+  if (raw !== null && raw !== undefined) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const env = Bun.env.KABMO_PORT;
+  if (typeof env === 'string' && env.trim().length > 0) {
+    const parsed = Number(env.trim());
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return DEFAULT_PORT;
+}
+
+export function resolveHost(options) {
+  if (options?.lan) return '0.0.0.0';
+  const raw = options?.host;
+  if (typeof raw === 'string' && raw.length > 0) return raw;
+  const env = Bun.env.KABMO_HOST;
+  if (typeof env === 'string' && env.length > 0) return env;
+  return DEFAULT_HOST;
+}
+
+/**
+ * Store the credential a login entry will read, returning its path or null.
+ *
+ * Null when the file could not be written: the caller then warns that the entry
+ * will start without a password, which is the honest outcome — an entry that
+ * names a file nobody wrote would start open with no explanation at all.
+ */
+function storeStartupCredential(password) {
+  return writeAutostartCredential(password) ? getAutostartCredentialPath() : null;
+}
+
+/**
+ * Whether this start raises a tray icon.
+ *
+ * `--startup` IMPLIES it: a login entry that started a headless console would
+ * leave the user with no way to see or stop it from the desktop. So
+ * `--startup --tray` is redundant, never wrong — and `--tray` alone does NOT
+ * register anything, which is the asymmetry worth keeping: an icon is a
+ * property of the run, a login entry is a change to the machine.
+ */
+export function trayForOptions(options) {
+  return options?.tray === true || options?.startup === true;
+}
+
+export async function run(options, ctx) {
+  const port = resolvePort(options);
+  const host = resolveHost(options);
+  const mode = resolveServeMode(options);
+  const json = isJson();
+  const quiet = isQuiet();
+  const pkgRoot = ctx?.pkgRoot ?? process.cwd();
+  const tls = options?.tls === true;
+  const tray = trayForOptions(options);
+
+  // The same gate the server entry applies, run here first so a missing omp
+  // binary fails immediately — with no detached child spawned, no log file to
+  // read and no registry entry left pointing at a process that already exited.
+  const ompError = ompStartupError();
+  if (ompError) fail(ompError);
+
+  // `--no-startup` is a REGISTRATION change, not a server start, so it runs
+  // before the port check and returns: asking to stop starting at login must
+  // work whether or not something is already serving the port (measured: with
+  // the flag below the port guard, `serve --no-startup` on a busy port failed
+  // with "already served" and left the entry in place).
+  if (options?.startup === false) {
+    const removed = uninstallAutostart();
+    // A pre-rename entry names a CLI file this release does not ship, so it
+    // would fail at every login and no command would reach it: `--no-startup`
+    // removes the CURRENT entry. Dropped here, on the one command that is
+    // about the registration at all.
+    removeLegacyAutostart();
+    // The credential exists only to serve the entry that was just removed.
+    removeAutostartCredential();
+    if (json) printJson({ startup: false, removed, entry: getAutostartEntryPath() });
+    else if (removed) ok(`Removed the login entry${getAutostartEntryPath() ? `: ${getAutostartEntryPath()}` : ''}.`);
+    else warn('No login entry was registered.');
+    return;
+  }
+
+  if (mode === 'prod') {
+    const builtServer = joinPath(pkgRoot, 'dist', 'client', 'index.js');
+    // Bun.file().exists() is file-only (false for directories) — correct here,
+    // where the target is always a regular file. For directory guards use
+    // pathExists() in src/server/lib/omp/core/paths.ts.
+    //
+    // The built server, not `dist/client/index.html`: the production bundle is
+    // the server itself (its HTML route is what emits the markup), and running
+    // it is what serves the assets beside it.
+    if (!(await Bun.file(builtServer).exists())) {
+      if (!quiet && !json) log('No production build found — building it (this runs once)...');
+      try {
+        buildProductionBundle(pkgRoot, {
+          onLine: quiet || json ? undefined : (chunk) => process.stdout.write(chunk),
+        });
+      } catch (err) {
+        fail(`${err?.message ?? String(err)}\n  Or start the dev server from source:  kabmo serve --dev`);
+      }
+      if (!(await Bun.file(builtServer).exists())) {
+        fail(`Build finished but ${builtServer} is still missing.\n  Or start the dev server from source:  kabmo serve --dev`);
+      }
+    }
+  }
+
+  const existing = await findLiveInstance(port);
+  if (existing) {
+    // Refused here as well as in the server (lib/lifecycle/port-guard) so the
+    // CLI reports it immediately instead of spawning a child that exits during
+    // the health wait. Nothing is stopped: freeing a port is `kabmo stop`.
+    fail(
+      `Port ${port} is already served by Kabmo (pid ${existing.pid}, ${existing.mode}).`
+      + '\n  Nothing was stopped — a starting instance never stops another one.'
+      + `\n  Stop it first:  kabmo stop --port ${port}`
+      + '\n  Or start on another port:  kabmo serve --port <port>',
+    );
+  }
+
+  // Resolved before the spawn and handed over through the environment: a value
+  // on the command line would be readable through `ps`. The server hashes it for
+  // its own process and erases the variable, so nothing durable holds it.
+  // A restarting SERVER has already hashed its credential; the CLI must pass it
+  // through rather than resolve a password of its own. See
+  // `lib/lifecycle/restart.ts` for why the plaintext is never respawned.
+  const handoverPayload = typeof options?.handoverPayload === 'string' && options.handoverPayload.length > 0
+    ? options.handoverPayload
+    : null;
+  const resolvedPassword = handoverPayload ? null : await resolveUiPassword(options);
+  if (!handoverPayload) reportUiAuth({ resolved: resolvedPassword, host, tls });
+
+  // `--startup` implies the tray (a login entry with no icon would start a
+  // console the user cannot see from the desktop), so the registration is
+  // written here and the spawn below carries `--tray`.
+  if (options?.startup === true) {
+    // A login entry is a world-readable command line that outlives this run, so
+    // it carries a PATH to the credential rather than the secret. The file
+    // lives beside `auth.json` at 0600, and the CLI reads it on the way in and
+    // hands it to the server through the stdin handover — never argv, never the
+    // environment.
+    const credentialPath = resolvedPassword?.password
+      ? storeStartupCredential(resolvedPassword.password)
+      : null;
+    const argv = buildLoginEntryArgv({
+      bun: resolveBunBin(),
+      cli: resolvePath(pkgRoot, 'src', 'cli', `${ctx?.bin ?? 'kabmo'}.js`),
+      port,
+      host,
+      tray: true,
+      tls,
+      lan: host === '0.0.0.0',
+      credentialPath,
+    });
+    // The old entry cannot work after the rename (its program is gone), and
+    // leaving it registered would start a failing job beside the new one.
+    removeLegacyAutostart();
+    const written = installAutostart({ argv, port, logFile: getLogFilePath(port) });
+    if (json) printJson({ startup: true, entry: written.path ?? 'windows-run-key' });
+    else if (written.path) ok(`Registered login entry: ${written.path}`);
+    else ok('Registered Kabmo tray to start at login (Windows Run key).');
+    if (resolvedPassword?.password && !credentialPath) {
+      warn(
+        `The login entry could not store your UI password, so it will start WITHOUT one.`
+        + ` Set ${UI_PASSWORD_ENV} in the environment launchd/systemd starts it in.`,
+      );
+    } else if (credentialPath) {
+      log(`  credential: stored for the login entry (${credentialPath}, mode 0600)`);
+    }
+  }
+
+  if (options?.foreground) {
+    return runForeground({ pkgRoot, mode, port, host, quiet, resolvedPassword, tls, tray, handoverPayload });
+  }
+
+  const { entry } = spawnDetachedServer({
+    pkgRoot,
+    mode,
+    port,
+    host,
+    launchMode: 'daemon',
+    resolvedPassword,
+    tls,
+    tray,
+    handoverPayload,
+  });
+
+  if (!quiet && !json) {
+    log(`Starting Kabmo (${mode}) on ${entry.url} (pid ${entry.pid})...`);
+  }
+
+  const health = await waitForHealth(port, host, undefined, tls);
+
+  if (json) {
+    printJson(entry);
+    return;
+  }
+
+  if (!health) {
+    warn(`Server started (pid ${entry.pid}) but the health check did not pass.\nCheck logs: ${entry.logFile}`);
+    return;
+  }
+
+  ok(`Kabmo ${mode} server ready`);
+  log(`  url:   ${entry.url}`);
+  log(`  pid:   ${entry.pid}`);
+  log(`  logs:  ${entry.logFile}`);
+}
+
+function runForeground({ pkgRoot, mode, port, host, quiet, resolvedPassword, tls = false, tray = false, handoverPayload = null }) {
+  const invocation = buildServeInvocation({ pkgRoot, mode, port, host, launchMode: 'foreground', tls, tray });
+  const { env, payload } = handoverPayload
+    ? { env: { ...invocation.env, [PASSWORD_HANDOVER_ENV]: PASSWORD_HANDOVER_STDIN }, payload: handoverPayload }
+    : uiPasswordHandover(resolvedPassword, invocation.env);
+  const url = `${tls ? 'https' : 'http'}://${probeHost(host)}:${port}`;
+  if (!quiet) {
+    log(`Running Kabmo (${mode}) in the foreground on ${url} (Ctrl+C to stop)...`);
+  }
+  const child = Bun.spawn({
+    cmd: [invocation.file, ...invocation.args],
+    cwd: invocation.cwd,
+    // The credential rides stdin, never the environment — see
+    // `uiPasswordHandover`. Without one the child keeps the terminal.
+    stdin: payload ? 'pipe' : 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env,
+  });
+  if (payload && child.stdin) {
+    child.stdin.write(payload);
+    child.stdin.end();
+  }
+  wireChildProcessLifecycle(child, process, 5000);
+  return new Promise((resolve) => {
+    void child.exited.then(resolve);
+  });
+}

package/src/cli/lib/commands/serve.test.js

@@ -0,0 +1,58 @@
+// `kabmo serve`'s flag rules that decide the process tree.
+//
+// Only the pure decisions are tested here: the command itself spawns a server,
+// writes a login entry outside the data directory and blocks on a health check,
+// none of which a unit test should perform. What IS worth pinning is the
+// asymmetry below, because getting it backwards is silent — a missing icon, or
+// a login entry the user never asked for.
+
+import { describe, expect, test } from 'bun:test';
+
+import { resolveHost, resolvePort, trayForOptions } from '@/cli/lib/commands/serve.js';
+
+describe('trayForOptions', () => {
+  // `--startup` implies the tray: a login-started console with no icon would be
+  // invisible and unstoppable from the desktop. Measured: `serve --startup`
+  // alone wrote a plist containing `--tray` and the running server logged
+  // `tray: icon shown`.
+  test('--startup raises an icon on its own', () => {
+    expect(trayForOptions({ startup: true })).toBe(true);
+  });
+
+  // Which makes spelling both redundant — supported, never required.
+  test('--startup --tray is the same request, not a different one', () => {
+    expect(trayForOptions({ startup: true, tray: true })).toBe(true);
+  });
+
+  test('--tray alone raises an icon and registers nothing', () => {
+    expect(trayForOptions({ tray: true })).toBe(true);
+  });
+
+  test('neither flag means no icon', () => {
+    expect(trayForOptions({})).toBe(false);
+    expect(trayForOptions(undefined)).toBe(false);
+    // `--no-startup` is a REMOVAL, and must not turn an icon on for the run.
+    expect(trayForOptions({ startup: false })).toBe(false);
+  });
+});
+
+describe('resolvePort / resolveHost', () => {
+  test('an explicit flag wins over the environment', () => {
+    const previous = Bun.env.KABMO_PORT;
+    Bun.env.KABMO_PORT = '5555';
+    try {
+      expect(resolvePort({ port: 6000 })).toBe(6000);
+      expect(resolvePort({})).toBe(5555);
+      expect(resolvePort({ port: null })).toBe(5555);
+    } finally {
+      if (previous === undefined) delete Bun.env.KABMO_PORT;
+      else Bun.env.KABMO_PORT = previous;
+    }
+  });
+
+  test('--lan is the bind-any address, and beats --host', () => {
+    expect(resolveHost({ lan: true, host: '127.0.0.1' })).toBe('0.0.0.0');
+    expect(resolveHost({ host: '192.168.1.4' })).toBe('192.168.1.4');
+    expect(resolveHost({})).toBe('127.0.0.1');
+  });
+});

package/src/cli/lib/commands/status.js

@@ -0,0 +1,130 @@
+// `kabmo status` — report the live instances, their health and log paths.
+//
+// Without `--port` every live instance is reported: a CLI server on one port, a
+// `bun run dev` server on another and a production server on a third are three
+// separate processes, and a status command that showed only the first would
+// hide the two you forgot about. `--port <port>` narrows the report to that
+// instance.
+
+import { findLiveInstance, listLiveInstances, waitForHealth } from '@/cli/lib/runtime.js';
+import { isLoopbackHost, probeHost } from '@/server/lib/lifecycle/probe';
+import { log, ok, printJson, isJson } from '@/cli/lib/output.js';
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function formatUptime(startedAt) {
+  const started = Date.parse(startedAt);
+  if (!Number.isFinite(started)) return 'unknown';
+  let seconds = Math.max(0, Math.floor((Date.now() - started) / 1000));
+  const hours = Math.floor(seconds / 3600);
+  seconds -= hours * 3600;
+  const minutes = Math.floor(seconds / 60);
+  seconds -= minutes * 60;
+  if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+function formatHealth(health) {
+  if (!health) return 'unreachable';
+  const version = health.version ?? 'unknown';
+  const mock = health.mock ? ', mock' : '';
+  return `ok (version ${version}${mock})`;
+}
+
+/**
+ * The URL to print for an instance.
+ *
+ * The scheme comes from the health payload, not from a guess: a TLS listener
+ * answers nothing on HTTP, so printing `http://` for it would hand the user a URL
+ * that cannot connect.
+ */
+function instanceUrl(entry) {
+  const scheme = entry.health?.tls ? 'https' : 'http';
+  return `${scheme}://${probeHost(entry.host)}:${entry.port}`;
+}
+
+/**
+ * The UI-auth verdict, as one line.
+ *
+ * Reported beside the bind address because those two facts decide the risk: a
+ * network-exposed instance with no password is reachable by anyone who can route
+ * to the host, and before this line the only way to learn that was to open a
+ * browser and look. `null` (an older server that does not report the field) is
+ * said out loud rather than guessed at.
+ */
+function formatAuth(health, entry) {
+  const enabled = health?.authEnabled;
+  const host = entry?.host ?? '';
+  if (enabled === true) return 'enabled (password required)';
+  if (enabled === false) {
+    return isLoopbackHost(host)
+      ? 'disabled (loopback only)'
+      : `disabled — ${host} is network-reachable and anyone can connect`;
+  }
+  return 'unknown (server does not report it)';
+}
+
+/** One block per instance; the field names match the single-instance output. */
+function printInstance(entry) {
+  log(`  instance: ${entry.port}`);
+  log(`  pid:      ${entry.pid}`);
+  log(`  port:     ${entry.port}`);
+  log(`  url:      ${instanceUrl(entry)}`);
+  log(`  mode:     ${entry.mode ?? 'unknown'}`);
+  log(`  launch:   ${entry.launchMode ?? 'unknown'}${entry.source ? ` (${entry.source})` : ''}`);
+  log(`  uptime:   ${formatUptime(entry.startedAt)}`);
+  log(`  health:   ${formatHealth(entry.health)}`);
+  log(`  auth:     ${formatAuth(entry.health, entry)}`);
+  log(`  tls:      ${entry.health?.tls ? 'on (self-signed)' : 'off — traffic is cleartext'}`);
+  // Descriptor pressure, when the server can measure it. A dev server climbs
+  // toward 10,240 by holding the client module graph across rebuilds, and past
+  // that point every `Bun.spawn` in the process fails at once (the terminal
+  // shell, the omp child, git) — this line is the warning that arrives before
+  // the breakage instead of after it.
+  const fds = entry.health?.fds;
+  if (fds) log(`  fds:      ${fds.open}/${fds.limit}${fds.nearCliff ? '  (near the spawn limit — restart this instance)' : ''}`);
+  log(`  log:      ${entry.logFile}`);
+}
+
+export async function run(options) {
+  const json = isJson();
+  const requested = explicitPort(options);
+
+  const instances = requested !== null
+    ? [await findLiveInstance(requested)].filter(Boolean)
+    : await listLiveInstances();
+
+  if (instances.length === 0) {
+    if (json) {
+      printJson(requested !== null ? { running: false, port: requested } : { running: false, instances: [] });
+      return;
+    }
+    log(requested !== null ? `No Kabmo instance on port ${requested}.` : 'Kabmo is not running.');
+    return;
+  }
+
+  const reported = [];
+  for (const entry of instances) {
+    // `'auto'`, not `false`: `status` is asking about an instance it did not
+    // start, so it cannot know whether that listener speaks TLS. Trying HTTPS
+    // first and falling back to HTTP is the only way to answer for either.
+    reported.push({ ...entry, health: await waitForHealth(entry.port, entry.host, 4000, 'auto') });
+  }
+
+  if (json) {
+    printJson(requested !== null ? { ...reported[0], running: true } : { running: true, instances: reported });
+    return;
+  }
+
+  ok(reported.length === 1 ? 'Kabmo is running' : `Kabmo is running — ${reported.length} instances`);
+  for (const [index, entry] of reported.entries()) {
+    if (index > 0) log('');
+    printInstance(entry);
+  }
+}

package/src/cli/lib/commands/stop.js

@@ -0,0 +1,95 @@
+// `kabmo stop` — stop Kabmo instances.
+//
+// Scope follows OWNERSHIP, the same rule `restart` and `update` apply. By
+// default only the instances the CLI started are stopped, because a server
+// running from source is supervised by a launcher the CLI does not own and
+// that launcher exits with the child it spawned: `bun run dev` is a process
+// whose whole job is to mirror the script under it, so signalling the server
+// takes the user's dev loop down with it. `--port <port>` and `--all` are the
+// explicit forms that do end one — naming an instance is a deliberate call,
+// not a default.
+
+import { listLiveInstances, findLiveInstance } from '@/cli/lib/runtime.js';
+import { stopInstance } from '@/cli/lib/stop-instance.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { ok, warn, error, log, printJson, isJson, isQuiet } from '@/cli/lib/output.js';
+import { unmanagedReason } from '@/server/lib/lifecycle/launch-mode';
+import { partitionStopTargets } from '@/cli/lib/stop-scope.js';
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** How to end an instance the default scope leaves alone. */
+function stopHint(port) {
+  return `stop it with \`kabmo stop --port ${port}\` or \`kabmo stop --all\``;
+}
+
+export async function run(options) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const requested = explicitPort(options);
+  // `--all` is the explicit spelling of "every instance, whoever started it".
+  const explicitScope = requested !== null || Boolean(options?.all);
+
+  const live = requested !== null
+    ? [await findLiveInstance(requested)].filter(Boolean)
+    : await listLiveInstances();
+  const { targets, skipped } = partitionStopTargets(live, explicitScope);
+  const skippedReport = skipped.map((entry) => ({ port: entry.port, pid: entry.pid, launchMode: entry.launchMode }));
+
+  if (!json && !quiet) {
+    for (const entry of skipped) {
+      log(`Skipping Kabmo on port ${entry.port} (pid ${entry.pid}): it ${unmanagedReason(entry.launchMode)} — ${stopHint(entry.port)}.`);
+    }
+  }
+
+  if (targets.length === 0) {
+    if (json) {
+      printJson({ stopped: [], skipped: skippedReport });
+      return;
+    }
+    if (skipped.length === 0) {
+      warn(requested === null
+        ? 'No running Kabmo instances found.'
+        : `No running Kabmo instance on port ${requested}.`);
+    }
+    return;
+  }
+
+  const stopped = [];
+  let failures = 0;
+  for (const entry of targets) {
+    const gone = await stopInstance(entry, { timeoutMs: STOP_TIMEOUT_MS });
+    stopped.push({ port: entry.port, pid: entry.pid, stopped: gone });
+    if (json) continue;
+    if (gone) {
+      ok(`Stopped Kabmo on port ${entry.port} (pid ${entry.pid}).`);
+    } else {
+      // A failure the caller must be able to see: the instance is still
+      // serving, its record is still on disk (so the next `status` finds it),
+      // and this command's exit code says the stop did not happen. Verified
+      // before the fix: this branch was unreachable on Windows, because
+      // `stopInstance` answered `true` for a process it never signalled.
+      failures += 1;
+      warn(`Kabmo on port ${entry.port} (pid ${entry.pid}) is still running — the stop did not take.`);
+    }
+  }
+
+  if (json) {
+    printJson({ stopped, skipped: skippedReport });
+    if (failures > 0) process.exitCode = 1;
+    return;
+  }
+
+  if (failures > 0) {
+    error(
+      `Could not stop ${failures} instance${failures === 1 ? '' : 's'}.`
+      + ` The instance record is kept, so \`kabmo status\` still reports it.`,
+    );
+    process.exitCode = 1;
+  }
+}