@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/cli/lib/runtime.js

@@ -0,0 +1,279 @@
+// Runtime helpers for Kabmo CLI: instance discovery, process identity,
+// server entry resolution, health probing and detached spawning.
+//
+// The instance record is written by the server that owns the port (see
+// src/server/lib/lifecycle/instance.ts), not by the CLI that spawned it, so a
+// server started by `bun run dev` or by `--foreground` is as discoverable as a
+// detached one. Discovery combines that record with a live `/api/health` probe:
+// the probe covers servers started outside the CLI, the record covers servers
+// that are alive but deaf (starting up, hung).
+
+import fs from 'node:fs';
+
+import { ensureDataDirs, getLogFilePath } from '@/cli/lib/paths.js';
+import { uiPasswordHandover } from '@/cli/lib/ui-password.js';
+import { PASSWORD_HANDOVER_ENV, PASSWORD_HANDOVER_STDIN } from '@/shared/lib/auth/handover';
+import { getProcessState, isProcessAlive } from '@/server/lib/lifecycle/identity';
+import { launchModeArg } from '@/server/lib/lifecycle/launch-mode';
+import { TLS_FLAG } from '@/server/lib/lifecycle/tls';
+import { TRAY_FLAG } from '@/server/lib/lifecycle/argv-flags';
+import { listInstanceRecords, readInstanceRecord, removeInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { fetchHealth, probeHost } from '@/server/lib/lifecycle/probe';
+import { joinPath, homeDir } from '@/cli/lib/path-utils.js';
+
+const HEALTH_INTERVAL_MS = 500;
+const HEALTH_TIMEOUT_MS = 30_000;
+
+/**
+ * CLI shape of a live instance, so records and probed servers print the same.
+ *
+ * No `url`: the scheme depends on whether the listener speaks TLS, which is only
+ * knowable from its health payload — so `status` builds the URL from that rather
+ * than trusting a value assembled before the probe ran.
+ */
+function toLiveInstance({ pid, port, host, mode, launchMode, tray, tls, auth, startedAt, source }) {
+  const resolvedHost = host || 'localhost';
+  return {
+    pid,
+    port,
+    host: resolvedHost,
+    mode: mode ?? 'unknown',
+    launchMode: launchMode ?? 'unknown',
+    // Carried so a restart can reproduce the invocation: `restart` and `update`
+    // spawn a NEW `serve`, and their own argv says nothing about the flags the
+    // original run had. Without these, an update dropped the tray icon (and TLS)
+    // of an instance started with `--tray` / `--tls`.
+    tray: tray === true,
+    tls: tls === true,
+    auth: auth === true,
+    startedAt,
+    source: source ?? 'registry',
+    logFile: getLogFilePath(port),
+  };
+}
+
+/**
+ * A recorded PID counts as the instance only while it is alive *and* still
+ * identifiable: a recycled PID must not resurrect a dead instance. `unknown`
+ * (identity unreadable on this platform) is accepted so Windows keeps working.
+ */
+function isRecordLive(record) {
+  if (!record) return false;
+  return isProcessAlive(record.pid) && getProcessState(record.pid) !== 'mismatched';
+}
+
+/**
+ * Every recorded instance whose process is still alive. Records left behind by
+ * a killed server (SIGKILL skips its cleanup handler) are pruned here, so a
+ * recycled PID can never be reported as a running instance.
+ */
+export async function listLiveInstances() {
+  const live = [];
+  for (const record of listInstanceRecords()) {
+    if (isRecordLive(record)) live.push(toLiveInstance(record));
+    else removeInstanceRecord(record.port);
+  }
+  // Directory order is filesystem-dependent; a port-ordered report is stable
+  // across runs and keeps multi-instance output readable.
+  live.sort((a, b) => a.port - b.port);
+  return live;
+}
+
+/**
+ * The live instance on `port`, or the first live instance when no port is
+ * given. Falls back to a health probe for servers that never wrote a record.
+ */
+export async function findLiveInstance(port) {
+  if (port === null || port === undefined) {
+    const [live] = await listLiveInstances();
+    return live ?? null;
+  }
+
+  const record = readInstanceRecord(port);
+  if (isRecordLive(record)) return toLiveInstance(record);
+  if (record) removeInstanceRecord(port);
+
+  const health = await fetchHealth(port, record?.host);
+  if (!health || typeof health.pid !== 'number' || !isProcessAlive(health.pid)) return null;
+  return toLiveInstance({
+    pid: health.pid,
+    port,
+    host: health.host ?? record?.host,
+    mode: health.mode,
+    launchMode: health.launchMode ?? record?.launchMode,
+    // A server started outside the CLI writes no record the CLI trusts, but it
+    // still reports its own flags. Absent means false, never inherited.
+    tray: health.tray ?? record?.tray,
+    tls: health.tls ?? record?.tls,
+    auth: health.authEnabled ?? record?.auth,
+    startedAt: health.startedAt,
+    source: 'probe',
+  });
+}
+
+function isBun(candidate) {
+  if (!candidate || !fs.existsSync(candidate)) return false;
+  const probe = Bun.spawnSync([candidate, '--version']);
+  return probe.success;
+}
+
+/**
+ * Locate the Bun runtime. The server imports `@/...` path aliases and ships as
+ * TypeScript, so it must run under Bun rather than whatever Node happens to be
+ * executing this CLI.
+ */
+export function resolveBunBin() {
+  const override = Bun.env.KABMO_BUN;
+  if (isBun(override)) return override;
+
+  const execDir = process.execPath;
+  // `bun` and `bun.exe`: on Windows the launcher carries the extension, and the
+  // path separator there is `\` — both already covered by the character class.
+  if (/(^|[\\/])bun(\.exe)?$/.test(execDir) && isBun(execDir)) return execDir;
+
+  const candidates = [
+    joinPath(homeDir(), '.bun', 'bin', 'bun'),
+    joinPath(homeDir(), '.bun', 'bin', 'bun.exe'),
+    '/opt/homebrew/bin/bun',
+    '/usr/local/bin/bun',
+    '/usr/bin/bun',
+  ];
+  for (const candidate of candidates) {
+    if (isBun(candidate)) return candidate;
+  }
+
+  const found = Bun.which('bun');
+  if (isBun(found)) return found;
+
+  throw new Error('Could not locate the Bun runtime. Install it from https://bun.sh and retry.');
+}
+
+/**
+ * Build the executable + args + env for a dev or prod server run.
+ *
+ * Bun executes the TypeScript entry directly in both modes, so dev and prod
+ * differ only by NODE_ENV — the client bundle in `dist/client` is required by
+ * the SSR shell either way. `--kabmo-server` is an identity marker: it
+ * makes this process recognizable in `ps` output, which is how a starting
+ * server decides whether a busy port belongs to Kabmo before signalling
+ * anything. The launch mode rides along as argv (`--launch-mode=`), never as an
+ * environment variable: env is inherited by descendants, so a `bun run dev`
+ * started from a Kabmo shell would otherwise be labelled `daemon` and
+ * replaced by the next update.
+ */
+export function buildServeInvocation({ pkgRoot, mode, port, host, launchMode = 'daemon', tls = false, tray = false }) {
+  // Production runs the built server: `bun run build` bundles `src/server/index.ts`
+  // into `dist/client/index.js`, and that bundle carries the HTML route and the
+  // hashed assets beside it. Development runs the source, which is what gives
+  // `--hot` something to reload.
+  const entry = mode === 'prod'
+    ? joinPath(pkgRoot, 'dist', 'client', 'index.js')
+    : joinPath(pkgRoot, 'src', 'server', 'index.ts');
+  if (!fs.existsSync(entry)) {
+    throw new Error(mode === 'prod'
+      ? `No production build found at ${entry}. Run \`bun run build\` and retry.`
+      : `Could not locate the server entry at ${entry}.`);
+  }
+  return {
+    file: resolveBunBin(),
+    // `--tls` and `--tray` travel as argv, like `--launch-mode`: env is inherited
+    // by every descendant, so a server started inside Kabmo's own terminal
+    // would otherwise inherit the choice.
+    args: [entry, '--kabmo-server', launchModeArg(launchMode), ...(tls ? [TLS_FLAG] : []), ...(tray ? [TRAY_FLAG] : [])],
+    // Both modes run from the package root. The built server's HTML bundle
+    // resolves its asset paths against the cwd, and the build emits them under
+    // `dist/client/` from that same root — while everything else the server
+    // does (the SQLite file, workspace roots, `public/`) is cwd-relative too,
+    // so moving the cwd into the output directory would relocate all of it.
+    cwd: pkgRoot,
+    env: {
+      ...Bun.env,
+      NODE_ENV: mode === 'prod' ? 'production' : 'development',
+      PORT: String(port),
+      HOST: host,
+    },
+  };
+}
+
+/**
+ * Spawn a detached server, stream its output to the per-port log file and
+ * return the CLI-facing entry description.
+ *
+ * The instance record is *not* written here: the server writes it once it
+ * actually owns the port, so a spawn that fails (port lost to something else)
+ * cannot leave a record pointing at a process that never served.
+ */
+export function spawnDetachedServer({ pkgRoot, mode, port, host, launchMode = 'daemon', resolvedPassword = null, tls = false, tray = false, handoverPayload = null }) {
+  ensureDataDirs();
+  const logFile = getLogFilePath(port);
+  const fd = fs.openSync(logFile, 'a');
+  const invocation = buildServeInvocation({ pkgRoot, mode, port, host, launchMode, tls, tray });
+  // A payload from a restarting server wins: it is already hashed, and the
+  // plaintext it stands for no longer exists anywhere.
+  const { env, payload } = handoverPayload
+    ? { env: { ...invocation.env, [PASSWORD_HANDOVER_ENV]: PASSWORD_HANDOVER_STDIN }, payload: handoverPayload }
+    : uiPasswordHandover(resolvedPassword, invocation.env);
+
+  let child;
+  try {
+    child = Bun.spawn({
+      cmd: [invocation.file, ...invocation.args],
+      cwd: invocation.cwd,
+      // A pipe, not `ignore`: the credential arrives on stdin. `ignore` here
+      // would leave a run with a password starting unauthenticated.
+      stdin: payload ? 'pipe' : 'ignore',
+      stdout: fd,
+      stderr: fd,
+      // Never argv: a value on the command line is readable by every user on the
+      // machine through `ps`, and on Linux through `/proc/<pid>/cmdline`. Never
+      // the environment either — the server's `delete Bun.env.X` does not reach
+      // the OS environ, so every grandchild would inherit it.
+      env,
+    });
+    if (payload && child.stdin) {
+      child.stdin.write(payload);
+      // Closed so the server's read ends: it waits for EOF, not a newline.
+      child.stdin.end();
+    }
+    child.unref();
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return {
+    child,
+    entry: {
+      pid: child.pid,
+      port,
+      host,
+      mode,
+      launchMode,
+      startedAt: new Date().toISOString(),
+      logFile,
+      url: `${tls ? 'https' : 'http'}://${probeHost(host)}:${port}`,
+    },
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Poll `/api/health` until a 200 with a JSON body arrives, else null.
+ */
+export async function waitForHealth(port, host, timeoutMs = HEALTH_TIMEOUT_MS, tls = 'auto') {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+
+  while (Date.now() < deadline) {
+    // `fetchHealth` carries the scheme: an explicit boolean when the caller knows
+    // (the CLI that just spawned the server), `'auto'` when it does not (status,
+    // discovery) — a server started with `--tls` answers nothing on HTTP, so
+    // assuming plain HTTP would report a healthy instance as never becoming ready.
+    const body = await fetchHealth(port, host, 2000, tls);
+    if (body) return body;
+    if (Date.now() >= deadline) break;
+    await sleep(HEALTH_INTERVAL_MS);
+  }
+  return null;
+}

package/src/cli/lib/serve-mode.js

@@ -0,0 +1,20 @@
+/**
+ * Serve-mode selection for `kabmo serve`.
+ *
+ * The CLI always runs the production build: it is what a user of the command
+ * wants (no HMR client, no unminified dev bundle re-downloaded per page load),
+ * and `bun run dev` remains the source-checkout dev loop with `--hot`.
+ *
+ * `--dev` is the escape hatch that keeps the source entry servable through the
+ * CLI — a build is required to serve production, so a checkout that cannot
+ * build still has a way to start.
+ *
+ * Kept apart from `commands/serve.js` for the reason `restart-scope.js` and
+ * `stop-scope.js` are: the rule is testable without importing the server
+ * modules the command needs.
+ */
+
+/** `'prod'` unless `--dev` was passed. */
+export function resolveServeMode(options) {
+  return options?.dev === true ? 'dev' : 'prod';
+}

package/src/cli/lib/serve-mode.test.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { resolveServeMode } from '@/cli/lib/serve-mode.js';
+
+describe('resolveServeMode', () => {
+  // The reported behavior: the CLI's own command served the dev entry, so a
+  // global install ran the unminified bundle with HMR wired up.
+  test('defaults to the production build', () => {
+    expect(resolveServeMode({})).toBe('prod');
+    expect(resolveServeMode(undefined)).toBe('prod');
+  });
+
+  // A server started with `--dev` must come back as one after `restart`, which
+  // re-runs `serve` with the mode it found recorded.
+  test('--dev serves the source entry', () => {
+    expect(resolveServeMode({ dev: true })).toBe('dev');
+  });
+
+  // `--prod` is accepted for compatibility and no longer selects anything.
+  test('--prod is a no-op, and --dev wins when both are given', () => {
+    expect(resolveServeMode({ prod: true })).toBe('prod');
+    expect(resolveServeMode({ prod: true, dev: true })).toBe('dev');
+  });
+});

package/src/cli/lib/stop-instance.js

@@ -0,0 +1,120 @@
+// Ending one live instance: signal it, confirm it is gone, then clear its
+// record.
+//
+// Kept apart from `runtime.js` (discovery, health probing, spawning) because the
+// two defects this module exists to prevent are both about IDENTITY and
+// OWNERSHIP, and a reader looking for "what happens when I run `kabmo stop`"
+// should land here rather than in the middle of the discovery helpers.
+
+import { killChildTree, STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { getProcessState, isProcessAlive } from '@/server/lib/lifecycle/identity';
+import { removeInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { findOccupant } from '@/server/lib/lifecycle/occupant';
+
+/**
+ * The questions this module asks about the world, injectable for the same
+ * reason `ScheduleDeps` exists. Two of them cannot be produced honestly on a
+ * POSIX host — the Windows identity answer (`proc/win32.ts` reads no command
+ * line, so `getProcessState` answers `unknown` for every PID there) and a
+ * process that refuses to die — and `mock.module` is not an option: it swaps the
+ * probe for the WHOLE `bun test` run, which broke eight unrelated suites when it
+ * was tried.
+ *
+ * `signal` is a seam rather than a direct `process.kill` for a blunter reason:
+ * on POSIX the kill is a GROUP kill (`-pid`), so a test that lets it run reaches
+ * the test runner's own process group. A caller never passes this; the defaults
+ * are the real functions.
+ */
+export const stopDeps = {
+  getProcessState,
+  findOccupant,
+  isAlive: isProcessAlive,
+  signal: (pid, force) => {
+    killChildTree({ pid, kill: (signal) => process.kill(pid, signal) }, force);
+  },
+};
+
+function waitForProcessExit(pid, timeoutMs, isAlive) {
+  if (!isAlive(pid)) return Promise.resolve(true);
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (!isAlive(pid)) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        resolve(false);
+        return;
+      }
+      setTimeout(tick, 100);
+    };
+    tick();
+  });
+}
+
+/**
+ * SIGTERM the process, escalate to SIGKILL after the timeout, then drop the
+ * instance record — but only once the process is actually gone. Resolves true
+ * only when nothing of ours is left running.
+ *
+ * Two defects made this command lie on Windows, and both are fixed here.
+ *
+ * 1. Identity could not be read, and that was read as "not ours". The Windows
+ *    probe cannot read another process's command line (`proc/win32.ts`), so
+ *    `getProcessState` answers `unknown` for every PID there — including the
+ *    server's own. The guard treated anything but `matched` as a stranger, so a
+ *    record-only entry took the early return: the record was deleted, `true` was
+ *    returned, and `kabmo stop` printed "✓ Stopped" while the server kept
+ *    listening on the port. Measured on Windows: the process was never
+ *    signalled at all.
+ *
+ *    The port is the witness that was missing. `findOccupant` combines the
+ *    record with a `/api/health` probe, so it answers who is serving the port
+ *    even when the OS cannot say who a PID is. Only when it names a DIFFERENT
+ *    PID — another instance, or nothing at all — is the record stale and the
+ *    entry dropped without a signal. A server that is alive but deaf (hung,
+ *    still starting) still answers from its own record, which is the case that
+ *    would otherwise be unstoppable.
+ *
+ * 2. The record was dropped unconditionally, even when the escalation could not
+ *    end the process. That is what turned a failed stop into a deadlock: the
+ *    record is the only source `listLiveInstances` has, so `status` and a plain
+ *    `stop` then reported "not running" while `serve` — which probes the port —
+ *    refused to start. Keeping the record is what makes the instance findable
+ *    again; the caller reports the failure from the returned value.
+ */
+export async function stopInstance(entry, { timeoutMs = STOP_TIMEOUT_MS, deps = stopDeps } = {}) {
+  const port = entry?.port;
+  const pid = Number(entry?.pid);
+  const dropRecord = async () => {
+    if (port !== undefined && port !== null) removeInstanceRecord(port);
+  };
+
+  if (!Number.isInteger(pid) || pid <= 0 || !deps.isAlive(pid)) {
+    await dropRecord();
+    return true;
+  }
+
+  const confirmedByProbe = entry?.source === 'probe' || entry?.source === 'registry+probe';
+  if (!confirmedByProbe && deps.getProcessState(pid) !== 'matched') {
+    const occupant = port === undefined || port === null ? null : await deps.findOccupant(port, entry?.host);
+    if (occupant?.pid !== pid) {
+      // The PID is alive but is not Kabmo serving this port (a
+      // recycled PID, a foreign listener, or a port nothing holds): a stranger
+      // is never signalled, and the stale record is the only thing to remove.
+      await dropRecord();
+      return true;
+    }
+  }
+
+  deps.signal(pid, false);
+  let gone = await waitForProcessExit(pid, timeoutMs, deps.isAlive);
+  if (!gone) {
+    deps.signal(pid, true);
+    gone = await waitForProcessExit(pid, timeoutMs, deps.isAlive);
+  }
+
+  if (gone) await dropRecord();
+  return gone;
+}

package/src/cli/lib/stop-instance.test.js

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `stopInstance` — the one place a running server is ended, and the one place
+ * the CLI could report a stop that never happened.
+ *
+ * Two failures are pinned here, both measured on Windows and both invisible to
+ * a test that only checks the returned boolean:
+ *
+ *   1. Identity could not be read (`getProcessState` answers `unknown` on every
+ *      Windows PID) and that was read as "not ours", so the early return deleted
+ *      the record and answered `true` without signalling anything.
+ *      `kabmo stop` printed "✓ Stopped" while the port stayed bound.
+ *   2. The record was dropped even when the process survived, which removed the
+ *      only handle `listLiveInstances` has: `status` then said "not running"
+ *      while `serve` — which probes the port — refused to start.
+ *
+ * The world is injected (`deps`), never mocked and never signalled. That is not
+ * only about `mock.module` swapping the probe for the whole `bun test` run: on
+ * POSIX the real kill is a GROUP kill (`-pid`), so a test that lets it run
+ * reaches the runner's own process group — which it did, and it is why every
+ * case below drives `signal` instead of a real process. The cases that must
+ * touch the real mechanism (a listener answering `/api/health`, the escalation
+ * past a signal a child ignores) live in `process-lifecycle.test.js`.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { stopInstance } from '@/cli/lib/stop-instance.js';
+import { readInstanceRecord, writeInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { win32Probe } from '@/server/lib/lifecycle/proc/win32';
+
+let workRoot = '';
+let originalDataDir;
+
+beforeAll(() => {
+  workRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-stop-test-'));
+  originalDataDir = Bun.env.KABMO_DATA_DIR;
+  Bun.env.KABMO_DATA_DIR = workRoot;
+});
+
+afterAll(() => {
+  if (originalDataDir === undefined) delete Bun.env.KABMO_DATA_DIR;
+  else Bun.env.KABMO_DATA_DIR = originalDataDir;
+  fs.rmSync(workRoot, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  fs.rmSync(path.join(workRoot, 'run'), { recursive: true, force: true });
+});
+
+/**
+ * A fake process table: liveness is whatever the case set, and `signal` records
+ * what was asked of it. `diesOn` names the signal that ends it, so the
+ * escalation path is exercised without a real kill.
+ */
+function fakeWorld({ pid, alive = true, diesOn = 'SIGTERM', occupantPid = pid } = {}) {
+  const signals = [];
+  const state = { alive };
+  return {
+    signals,
+    state,
+    deps: {
+      // Windows: no command line is reachable, so identity is never `matched`.
+      getProcessState: () => 'unknown',
+      findOccupant: async () => (occupantPid === null ? null : { pid: occupantPid }),
+      isAlive: () => state.alive,
+      signal: (_pid, force) => {
+        const signal = force ? 'SIGKILL' : 'SIGTERM';
+        signals.push(signal);
+        if (diesOn && signal === diesOn) state.alive = false;
+      },
+    },
+  };
+}
+
+function writeRecord(port, pid) {
+  writeInstanceRecord({
+    pid, port, host: '127.0.0.1', mode: 'prod', launchMode: 'daemon',
+    startedAt: new Date().toISOString(), version: '0.0.0',
+  });
+}
+
+describe('stopInstance', () => {
+  test('the Windows premise: identity is unreadable, so it is never `matched`', () => {
+    // Everything below exists because of this one fact about `proc/win32.ts`.
+    expect(win32Probe.commandLine(process.pid)).toBeNull();
+  });
+
+  test('stops a record-only entry when identity is unreadable (the Windows case)', async () => {
+    const port = 4931;
+    writeRecord(port, 5001);
+    const world = fakeWorld({ pid: 5001 });
+
+    const gone = await stopInstance({ port, pid: 5001, source: 'registry' }, { timeoutMs: 300, deps: world.deps });
+
+    expect(gone).toBe(true);
+    // The regression: before the fix this returned true having sent NOTHING,
+    // because `unknown` was read as "not ours".
+    expect(world.signals).toEqual(['SIGTERM']);
+    expect(readInstanceRecord(port)).toBeNull();
+  });
+
+  test('never signals a stranger holding a recycled PID, and drops the stale record', async () => {
+    const port = 4932;
+    writeRecord(port, 5002);
+    // The port answers for a DIFFERENT PID: the record is stale, and the live
+    // PID it names belongs to something else.
+    const world = fakeWorld({ pid: 5002, occupantPid: 9999 });
+
+    const gone = await stopInstance({ port, pid: 5002, source: 'registry' }, { timeoutMs: 300, deps: world.deps });
+
+    expect(gone).toBe(true);
+    expect(world.signals).toEqual([]);
+    expect(readInstanceRecord(port)).toBeNull();
+  });
+
+  test('never signals a record-only entry when nothing occupies the port', async () => {
+    const port = 4933;
+    writeRecord(port, 5003);
+    const world = fakeWorld({ pid: 5003, occupantPid: null });
+
+    const gone = await stopInstance({ port, pid: 5003, source: 'registry' }, { timeoutMs: 300, deps: world.deps });
+
+    expect(gone).toBe(true);
+    expect(world.signals).toEqual([]);
+    expect(readInstanceRecord(port)).toBeNull();
+  });
+
+  test('stops the instance when the port names the same PID', async () => {
+    const port = 4934;
+    writeRecord(port, 5004);
+    const world = fakeWorld({ pid: 5004 });
+
+    const gone = await stopInstance({ port, pid: 5004, source: 'registry' }, { timeoutMs: 300, deps: world.deps });
+
+    expect(gone).toBe(true);
+    expect(world.signals).toEqual(['SIGTERM']);
+  });
+
+  test('escalates to SIGKILL when the graceful signal does not take', async () => {
+    const port = 4935;
+    writeRecord(port, 5005);
+    const world = fakeWorld({ pid: 5005, diesOn: 'SIGKILL' });
+
+    const gone = await stopInstance({ port, pid: 5005, source: 'registry' }, { timeoutMs: 0, deps: world.deps });
+
+    expect(gone).toBe(true);
+    expect(world.signals).toEqual(['SIGTERM', 'SIGKILL']);
+    expect(readInstanceRecord(port)).toBeNull();
+  });
+
+  test('keeps the record when the process survives, so the next status still finds it', async () => {
+    const port = 4936;
+    writeRecord(port, 5006);
+    // `diesOn: null` models the process nothing can end: both signals are sent,
+    // neither takes, and the record must survive so `status` still reports it.
+    const world = fakeWorld({ pid: 5006, diesOn: null });
+
+    const gone = await stopInstance({ port, pid: 5006, source: 'registry' }, { timeoutMs: 0, deps: world.deps });
+
+    expect(gone).toBe(false);
+    expect(world.signals).toEqual(['SIGTERM', 'SIGKILL']);
+    expect(readInstanceRecord(port)).not.toBeNull();
+  });
+
+  test('an entry confirmed by the port probe needs no identity', async () => {
+    const port = 4937;
+    writeRecord(port, 5007);
+    // `source: 'probe'` is the server itself having answered /api/health: the
+    // guard is skipped entirely, which is why `stop --port <port>` still worked
+    // on Windows while the record-only path did not.
+    const world = fakeWorld({ pid: 5007, occupantPid: null });
+
+    const gone = await stopInstance({ port, pid: 5007, source: 'probe' }, { timeoutMs: 300, deps: world.deps });
+
+    expect(gone).toBe(true);
+    expect(world.signals).toEqual(['SIGTERM']);
+  });
+
+  test('an already-dead PID just clears the record', async () => {
+    const port = 4938;
+    writeRecord(port, 5008);
+    const world = fakeWorld({ pid: 5008, alive: false });
+
+    expect(await stopInstance({ port, pid: 5008, source: 'registry' }, { timeoutMs: 100, deps: world.deps })).toBe(true);
+    expect(world.signals).toEqual([]);
+    expect(readInstanceRecord(port)).toBeNull();
+  });
+
+  test('an entry with no port is never signalled, since nothing can confirm it', async () => {
+    const world = fakeWorld({ pid: 5009, occupantPid: null });
+
+    // Degenerate input: every real caller passes an instance entry, which always
+    // carries a port. With no port there is nothing to check the PID against, so
+    // the conservative direction is kept — an unconfirmed PID is not signalled.
+    expect(await stopInstance({ pid: 5009 }, { timeoutMs: 300, deps: world.deps })).toBe(true);
+    expect(world.signals).toEqual([]);
+  });
+});

package/src/cli/lib/stop-scope.js

@@ -0,0 +1,23 @@
+// Ownership scope for `kabmo stop`.
+//
+// Kept separate from the command so the rule is testable without a live
+// server: the default scope is the instances the CLI started, and only an
+// explicit `--port <port>` / `--all` widens it to the ones it did not. That
+// distinction is the whole reason this module exists — a server running from
+// source sits under a launcher that exits with its child, so stopping it by
+// default takes a `bun run dev` loop down with it.
+
+import { isCliManaged } from '@/server/lib/lifecycle/launch-mode';
+
+/**
+ * Split the live instances into the ones `stop` acts on and the ones it leaves
+ * alone. `explicit` is true when the user named a port or passed `--all`:
+ * naming an instance is a deliberate call, so ownership no longer gates it.
+ */
+export function partitionStopTargets(instances, explicit) {
+  if (explicit) return { targets: instances, skipped: [] };
+  return {
+    targets: instances.filter((entry) => isCliManaged(entry.launchMode)),
+    skipped: instances.filter((entry) => !isCliManaged(entry.launchMode)),
+  };
+}