ompchamber 3.1.0 → 3.2.0

package/src/server/lib/bundler/nested-at-rules.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Hoist every nested at-rule out of the style rule that contains it.
+ *
+ * Bun's CSS minifier keeps the nesting it is handed, and for a target that is
+ * not the browser (`target: 'bun'`, which this build needs because its
+ * entrypoint is the SERVER) it re-nests a rule's nested at-rule into
+ * `@supports (…) { & { … } }`. Chrome does not apply a nested rule whose parent
+ * selector names a pseudo-element, so `&` under `::placeholder` or
+ * `::-webkit-scrollbar-thumb` is dropped and the rule's earlier fallback
+ * declaration wins instead — measured on the built bundle: the composer
+ * placeholder painted at full ink rather than 40%, every scrollbar thumb opaque
+ * rather than 20%.
+ *
+ * Tailwind v4 emits its colour fallbacks in exactly that shape (`color:
+ * var(--x); @supports (color: color-mix(…)) { color: color-mix(…) }`), so one
+ * minifier decision reached 16 rules: every placeholder utility in the app and
+ * every scrollbar rule, base and xterm included. The rsbuild pipeline this
+ * replaced compiled for browsers and flattened the nesting itself.
+ *
+ * Flattening here is what makes the bundle immune: the emitted CSS is
+ * `@supports (…) { .sel::placeholder { … } }` at the top level, which no
+ * minifier has anything left to re-nest and every browser applies. Declaration
+ * order is preserved exactly — a rule's declarations stay in the segments they
+ * were written in, and each at-rule is hoisted to the position it occupied — so
+ * the cascade is unchanged.
+ */
+
+import postcss from 'postcss';
+import type { AtRule, ChildNode, Container, Plugin, Rule } from 'postcss';
+
+/** Resolve a nested selector against the rule it was written inside. */
+function resolveSelector(parentSelector: string, nestedSelector: string): string {
+  if (nestedSelector.includes('&')) return nestedSelector.replaceAll('&', parentSelector);
+  return `${parentSelector} ${nestedSelector}`;
+}
+
+/**
+ * Resolve `&` in the rules directly inside `container`, descending through
+ * at-rules only: `&` still refers to the nearest enclosing STYLE rule, and an
+ * intermediate one is hoisted on a later pass.
+ *
+ * Runs BEFORE `wrapBareDeclarations` — the rule that wraps bare declarations
+ * already carries the parent's resolved selector, and resolving it again would
+ * turn `::placeholder` into `::placeholder ::placeholder`.
+ */
+function resolveAmpersands(container: Container, parentSelector: string): void {
+  for (const node of container.nodes ?? []) {
+    if (node.type === 'rule') node.selector = resolveSelector(parentSelector, node.selector);
+    else if (node.type === 'atrule') resolveAmpersands(node, parentSelector);
+  }
+}
+
+/** Wrap an at-rule's bare declarations in `parentSelector`, keeping them in place. */
+function wrapBareDeclarations(atRule: AtRule, parentSelector: string): void {
+  const nodes = [...(atRule.nodes ?? [])];
+  if (!nodes.some((node) => node.type === 'decl')) return;
+  const rebuilt: ChildNode[] = [];
+  let declarations: ChildNode[] = [];
+  const flush = () => {
+    if (declarations.length === 0) return;
+    const rule = postcss.rule({ selector: parentSelector });
+    rule.append(declarations);
+    rebuilt.push(rule);
+    declarations = [];
+  };
+  for (const node of nodes) {
+    if (node.type === 'decl') declarations.push(node);
+    else {
+      flush();
+      rebuilt.push(node);
+    }
+  }
+  flush();
+  atRule.removeAll();
+  atRule.append(rebuilt);
+}
+
+/** Hoist `rule`'s nested at-rules into its own container. Reports whether it moved any. */
+function hoistNestedAtRules(rule: Rule): boolean {
+  const container = rule.parent;
+  // Snapshot: reparenting the declarations empties `rule.nodes` mid-iteration.
+  const nodes = [...(rule.nodes ?? [])];
+  if (!container || !nodes.some((node) => node.type === 'atrule')) return false;
+
+  const replacement: ChildNode[] = [];
+  let declarations: ChildNode[] = [];
+  const flush = () => {
+    if (declarations.length === 0) return;
+    const segment = postcss.rule({ selector: rule.selector, raws: { ...rule.raws } });
+    segment.append(declarations);
+    replacement.push(segment);
+    declarations = [];
+  };
+
+  for (const node of nodes) {
+    if (node.type !== 'atrule') {
+      declarations.push(node);
+      continue;
+    }
+    flush();
+    const hoisted = node.clone();
+    resolveAmpersands(hoisted, rule.selector);
+    wrapBareDeclarations(hoisted, rule.selector);
+    replacement.push(hoisted);
+  }
+  flush();
+
+  container.insertBefore(rule, replacement);
+  rule.remove();
+  return true;
+}
+
+/**
+ * PostCSS plugin: hoist nested at-rules out of the rules containing them.
+ *
+ * `OnceExit` rather than `Once` so Tailwind's own pass has already expanded
+ * `@theme` and every utility before there is a rule to flatten; register it
+ * LAST for the same reason.
+ */
+export function flattenNestedAtRules(): Plugin {
+  return {
+    postcssPlugin: 'ompchamber-flatten-nested-at-rules',
+    OnceExit(root) {
+      // A hoist can expose another nested at-rule in the segment that received
+      // it, so repeat until a full pass moves nothing.
+      let hoisted = true;
+      while (hoisted) {
+        hoisted = false;
+        const rules: Rule[] = [];
+        root.walkRules((rule) => {
+          rules.push(rule);
+        });
+        // Reverse document order: a nested rule is walked after its parent, so
+        // the inner one is flattened first and its parent is then still intact.
+        for (let index = rules.length - 1; index >= 0; index -= 1) {
+          if (hoistNestedAtRules(rules[index])) hoisted = true;
+        }
+      }
+    },
+  };
+}

package/src/server/lib/db/client.ts

@@ -44,7 +44,11 @@ export function createDb(path: string): DbClient {
       return prep(sql).all(...(params as never[])) as T[];
     },
     async run(sql: string, params: any[] = []) {
-      const result = raw.run(sql, params as never);
+      // Through `prep`, like `get`/`all`: `Database.run` does not cache its
+      // query (it prepares and finalizes per call), which cost every INSERT /
+      // UPDATE / DELETE a compile — measured 0.881 µs/op against 0.627 µs/op
+      // for the cached statement.
+      const result = prep(sql).run(...(params as never[]));
       return { changes: result.changes, lastID: Number(result.lastInsertRowid) };
     },
     async exec(sql: string) {

package/src/server/lib/fs/git-diff.ts

@@ -2,20 +2,32 @@ import path from 'path';
 import type { FileDiffData } from '@/shared/types/git';
 import { runShell, shellOk } from '@/server/lib/fs/shell';
 
+/**
+ * Context lines requested when the reader wants the whole file rather than the
+ * hunks. `--unified` takes any count, so this is a cap on the FILE, not on the
+ * change: git emits every line it can reach around the edits.
+ */
+const FULL_CONTEXT = 1000000;
+
 /** Runs one git diff probe and returns its stdout ('' on failure). */
-async function gitOut(command: string, cwd: string, timeout: number): Promise<string> {
-  const result = await runShell(command, { cwd, timeout, maxBuffer: 1024 * 1024 * 2 });
+async function gitOut(command: string, cwd: string, timeout: number, maxBuffer: number = 1024 * 1024 * 2): Promise<string> {
+  const result = await runShell(command, { cwd, timeout, maxBuffer });
   return shellOk(result) ? result.stdout : '';
 }
 
 /**
  * Fetch git diff for a specific file in the working directory or index.
+ *
+ * `fullContext` asks git for the entire file rather than the surrounding hunks,
+ * which is what the panel's "Full Code" mode renders — the diff comes back in
+ * the same unified format, so no second rendering path exists.
  */
 export async function fetchWorkingFileDiff(
   targetDir: string,
   file: string,
   staged: boolean = false,
-  requestedStatus?: string
+  requestedStatus?: string,
+  fullContext: boolean = false
 ): Promise<FileDiffData> {
   const cleanFile = file.replace(/^[./\\]+/, '').replace(/\\/g, '/');
   const fullPath = path.join(targetDir, cleanFile);
@@ -45,21 +57,33 @@ export async function fetchWorkingFileDiff(
     oldContent = await gitOut(`git show HEAD:"${cleanFile}"`, targetDir, 5000)
       || await gitOut(`git show :0:"${cleanFile}"`, targetDir, 5000);
 
+    // `-U<n>` on every probe: the full-code mode asks for the whole file, and
+    // the diff-only mode keeps git's own default by passing no flag at all.
+    const ctx = fullContext ? ` -U${FULL_CONTEXT}` : '';
+    // Full-context output is the file, not the change, so a fixed buffer would
+    // truncate a large file's diff — and a killed process is not a success, so
+    // `gitOut` reports it as no diff at all and the synthesized whole-file
+    // rewrite below takes over silently. Sized off the content already read, so
+    // it cannot exceed roughly twice the file.
+    const buf = fullContext
+      ? Math.max(1024 * 1024 * 16, (oldContent.length + newContent.length) * 2 + 1024 * 1024)
+      : 1024 * 1024 * 2;
+
     if (staged) {
       // 1. Try staged diff (index vs HEAD), 2. HEAD diff, 3. unstaged diff
-      diff = await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000);
+      diff = await gitOut(`git diff${ctx} --cached -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} HEAD -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} -- "${cleanFile}"`, targetDir, 10000, buf);
     } else if (status === '??' || status === 'U' || status === '?') {
       // Untracked file: --no-index exits 1 when a diff exists, so read stdout
       // directly instead of relying on the exit code.
-      const untracked = await runShell(`git diff --no-index /dev/null "${cleanFile}"`, { cwd: targetDir, timeout: 10000, maxBuffer: 1024 * 1024 * 2 });
+      const untracked = await runShell(`git diff${ctx} --no-index /dev/null "${cleanFile}"`, { cwd: targetDir, timeout: 10000, maxBuffer: buf });
       diff = untracked.stdout.trim() ? untracked.stdout : '';
     } else {
       // 1. Working tree diff, 2. cached diff, 3. HEAD diff
-      diff = await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000);
+      diff = await gitOut(`git diff${ctx} -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} --cached -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} HEAD -- "${cleanFile}"`, targetDir, 10000, buf);
     }
 
     // 4. If git diff is still empty but new content exists:

package/src/server/lib/fs/git-repos.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Nested-repository discovery for the right-panel repo picker.
+ *
+ * A workspace is often a folder OF repositories (`projects/<name>/<sub>/.git`),
+ * so the picker lists every repo under the scoped root. The walk is expensive
+ * on a deep tree, so it runs in the BACKGROUND after the loader has already
+ * answered with the root's own status; the client polls until `pending` clears.
+ * Results are cached per scoped root for the life of the process.
+ *
+ * The `find` prunes `node_modules` (the one directory guaranteed to hold
+ * unrelated `.git` directories, and the one that makes the walk unbounded).
+ */
+
+import { runShell } from '@/server/lib/fs/shell';
+
+const MAX_GIT_DEPTH = 8;
+
+async function getRepos(rootDir: string): Promise<string[]> {
+  try {
+    // Search deep enough to discover nested/child git repos inside a monorepo
+    // workspace (e.g. projects/<name>/<sub>/.git) while pruning node_modules.
+    const result = await runShell(
+      `find . -maxdepth ${MAX_GIT_DEPTH} -name node_modules -prune -o -name .git -type d -print`,
+      { cwd: rootDir, timeout: 12000, maxBuffer: 1024 * 1024 }
+    );
+    const discovered = result.stdout
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map(line => {
+        const cleaned = line.replace(/^\.\//, '').replace(/\/\.git$/, '');
+        return cleaned === '.git' || !cleaned ? '.' : cleaned;
+      });
+
+    const uniqueRepos = Array.from(new Set(discovered));
+    if (uniqueRepos.includes('.')) {
+      return ['.', ...uniqueRepos.filter(r => r !== '.')];
+    }
+    return uniqueRepos.length ? uniqueRepos : ['.'];
+  } catch {
+    return ['.'];
+  }
+}
+
+interface RepoDiscovery {
+  repos: string[];
+  done: boolean;
+}
+
+const repoDiscovery = new Map<string, RepoDiscovery>();
+
+/** Begin the background walk for `rootDir`; a no-op once one has started. */
+export function startRepoScan(rootDir: string): void {
+  if (repoDiscovery.has(rootDir)) return;
+  const d: RepoDiscovery = { repos: ['.'], done: false };
+  repoDiscovery.set(rootDir, d);
+  void getRepos(rootDir)
+    .then(repos => { d.repos = repos; d.done = true; })
+    .catch(() => { d.repos = ['.']; d.done = true; });
+}
+
+/**
+ * Drop the cached result for `rootDir` and start a fresh walk. Used by the
+ * repo-switcher's refresh button, which must not serve the previous answer.
+ */
+export function rescanRepos(rootDir: string): void {
+  repoDiscovery.delete(rootDir);
+  startRepoScan(rootDir);
+}
+
+/** The discovered repos for `rootDir`, and whether the walk is still running. */
+export function discoveredRepos(rootDir: string): { repos: string[]; pending: boolean } {
+  const d = repoDiscovery.get(rootDir);
+  if (!d) return { repos: ['.'], pending: false };
+  return { repos: d.done ? d.repos : ['.'], pending: !d.done };
+}

package/src/server/lib/lifecycle/flock.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `flock(2)` through `bun:ffi`, for the port-handover lock.
+ *
+ * The kernel releases a flock when the holding process dies, which is exactly
+ * the property a startup lock wants — no PID readback, no stale-holder
+ * classification, and no polling loop to detect a dead holder. The previous
+ * PID-file scheme needed all three: it wrote a PID, re-read it on every retry,
+ * asked the OS whether that PID was still OMPChamber (four `sysctl` calls per
+ * question on macOS), and deleted the file to release.
+ *
+ * `flock` is exported by `libc.dylib` / `libSystem.B.dylib` / `libc.so.6`, so it
+ * is reachable the same way `lib/lifecycle/proc/darwin.ts` reaches `sysctl`.
+ * Windows has no `flock`, and a host can refuse `dlopen` or answer `ENOLCK`
+ * (some NFS mounts) — `flockAvailable()` is a real capability probe, and every
+ * caller keeps its own fallback for the false case.
+ *
+ * **The lock file is never unlinked while it may be held.** Removing it is the
+ * classic flock race: another process that already opened the path keeps a
+ * handle on the unlinked inode and acquires it successfully while a third
+ * process creates a fresh file at the same path and also succeeds. Leaving the
+ * file in place makes the inode the lock, which is what flock is for; the file
+ * is an empty marker, one per port.
+ */
+
+import fs from 'fs';
+import { dlopen, FFIType } from 'bun:ffi';
+import type { FFIFunction, Library } from 'bun:ffi';
+
+const LOCK_EX = 2;
+/** Non-blocking: fail immediately rather than waiting inside the syscall. */
+const LOCK_NB = 4;
+
+const FLOCK_SYMBOLS = {
+  flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+} satisfies Record<string, FFIFunction>;
+
+/** Library names to try, in the order each platform resolves them. */
+const LIBC_NAMES = ['libc.dylib', 'libSystem.B.dylib', 'libc.so.6'] as const;
+
+/**
+ * Held leases and the probe result, on `globalThis` rather than in module
+ * bindings.
+ *
+ * A `bun --hot` reload re-evaluates this module while the process (and its open
+ * descriptors) lives on. A fresh module-level Map would forget that this PID
+ * already holds the port's lock, so the reloaded server would open a second fd,
+ * find the lock taken by its own previous fd, and refuse to start.
+ */
+interface FlockHost {
+  /** `lockPath` → the fd holding it and how many acquires it backs. */
+  held: Map<string, { fd: number; refs: number }>;
+  /** Tri-state capability probe: undefined until asked, then lib-or-null. */
+  available: boolean | undefined;
+  /** The opened library, shared across reloads. */
+  lib: Library<typeof FLOCK_SYMBOLS> | null | undefined;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberFlock: FlockHost | undefined;
+}
+
+function host(): FlockHost {
+  return (globalThis.__ompChamberFlock ??= { held: new Map(), available: undefined, lib: undefined });
+}
+
+/** libc with `flock`, or null when this host has none. Cached for the process. */
+function libc(): Library<typeof FLOCK_SYMBOLS> | null {
+  const state = host();
+  if (state.lib !== undefined) return state.lib;
+  state.lib = null;
+  if (process.platform === 'win32') return state.lib;
+  for (const name of LIBC_NAMES) {
+    try {
+      state.lib = dlopen(name, FLOCK_SYMBOLS);
+      return state.lib;
+    } catch {
+      // Try the next name; a host without any of them keeps the null answer.
+    }
+  }
+  return state.lib;
+}
+
+/**
+ * True when `flock(2)` actually works here — the symbol resolving is not
+ * enough, because a filesystem can answer `ENOLCK`. Probed once, on a
+ * throwaway file, so a caller can pick its mechanism up front instead of
+ * discovering mid-wait that the syscall never works.
+ */
+export function flockAvailable(): boolean {
+  const state = host();
+  if (state.available !== undefined) return state.available;
+  state.available = false;
+  const symbols = libc();
+  if (!symbols) return false;
+  const probePath = `${process.env.TMPDIR ?? '/tmp'}/ompchamber-flock-${process.pid}`;
+  let fd: number | null = null;
+  try {
+    fd = fs.openSync(probePath, 'a');
+    const ok = symbols.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0;
+    fs.closeSync(fd);
+    fd = null;
+    fs.rmSync(probePath, { force: true });
+    if (!ok) {
+      // The probe file was somehow already locked — treat the capability as
+      // unproven rather than reporting a lock we do not hold.
+      state.lib = null;
+      return false;
+    }
+    state.available = true;
+    return true;
+  } catch {
+    state.lib = null;
+    return false;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Already closed.
+      }
+    }
+  }
+}
+
+export interface FlockHandle {
+  /** Release the lease. Idempotent. */
+  release: () => void;
+}
+
+/**
+ * Take `LOCK_EX | LOCK_NB` on `lockPath`, or null when another process holds
+ * it. Returns null too when `flock` is unavailable — callers must then use
+ * their own mechanism.
+ *
+ * The fd is kept open for as long as the lease lives: closing it is what
+ * releases the lock, and the kernel does the same on process death.
+ */
+export function tryFlock(lockPath: string): FlockHandle | null {
+  const state = host();
+  const existing = state.held.get(lockPath);
+  if (existing) {
+    // Re-entrant within one process: flock is per open-file-description, so a
+    // second fd here would block against our own lock.
+    existing.refs += 1;
+    return { release: () => releaseFlock(lockPath) };
+  }
+  const symbols = libc();
+  if (!symbols) return null;
+  let fd: number;
+  try {
+    // `a` creates it when absent and never truncates; the file's content is
+    // irrelevant (the inode is the lock), but the PID is useful when a human
+    // looks at the directory.
+    fd = fs.openSync(lockPath, 'a');
+  } catch {
+    return null;
+  }
+  let acquired = false;
+  try {
+    acquired = symbols.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0;
+  } catch {
+    acquired = false;
+  }
+  if (!acquired) {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      // Already closed.
+    }
+    return null;
+  }
+  try {
+    fs.writeFileSync(fd, String(process.pid));
+  } catch {
+    // Informational only.
+  }
+  state.held.set(lockPath, { fd, refs: 1 });
+  return { release: () => releaseFlock(lockPath) };
+}
+
+function releaseFlock(lockPath: string): void {
+  const state = host();
+  const entry = state.held.get(lockPath);
+  if (!entry) return;
+  entry.refs -= 1;
+  if (entry.refs > 0) return;
+  state.held.delete(lockPath);
+  try {
+    fs.closeSync(entry.fd);
+  } catch {
+    // Already closed; the kernel released the lock either way.
+  }
+}

package/src/server/lib/lifecycle/identity.ts

@@ -37,7 +37,11 @@ export type ProcessState = 'dead' | 'matched' | 'mismatched' | 'unknown';
  */
 export function isProcessAlive(pid: number): boolean {
   if (!Number.isFinite(pid) || pid <= 0) return false;
-  return processProbe.isAlive(pid) && !processProbe.isZombie(pid);
+  const liveness = processProbe.liveness(pid);
+  // A zombie is NOT alive: it holds no port and will never run again. An
+  // `unknown` (a probe that could not answer) keeps the previous bias and
+  // counts as alive, so a sandboxed host cannot make a live server look dead.
+  return liveness === 'alive' || liveness === 'unknown';
 }
 
 /**

package/src/server/lib/lifecycle/launch-mode.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { launchModeArg, resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
+import { isCliManaged, launchModeArg, resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
 
 const ENTRY = '/repo/src/server/index.ts';
 
@@ -30,3 +30,22 @@ describe('resolveLaunchMode', () => {
     }
   });
 });
+
+// Every command that would END a server decides with this predicate:
+// `restart`/`update` may replace it, and `stop` stops it by default. Guessing
+// wrong here kills a `bun run dev` the user owns — that launcher exits with its
+// child — or leaves a daemon serving the build that was just replaced.
+describe('isCliManaged', () => {
+  test('owns the instances the CLI started', () => {
+    expect(isCliManaged('daemon')).toBe(true);
+    expect(isCliManaged('foreground')).toBe(true);
+  });
+
+  test('leaves every instance OMPChamber did not start alone', () => {
+    // `bun run dev`, `bun run start`, a manual run, a systemd/pm2 unit.
+    expect(isCliManaged('direct')).toBe(false);
+    // A probed or unreadable record never authorises a kill either.
+    expect(isCliManaged('unknown')).toBe(false);
+    expect(isCliManaged(undefined)).toBe(false);
+  });
+});

package/src/server/lib/lifecycle/launch-mode.ts

@@ -38,3 +38,29 @@ export function resolveLaunchMode(argv: readonly string[] = Bun.argv): InstanceL
   const value = flag?.slice(LAUNCH_MODE_FLAG.length);
   return value === 'daemon' || value === 'foreground' ? value : 'direct';
 }
+
+/**
+ * Whether the CLI owns this instance's lifecycle — the one question every
+ * command that would end a server asks: `restart`/`update` may replace it, and
+ * `stop` stops it by default.
+ *
+ * A `direct` server runs under a launcher the CLI does not own, and that
+ * launcher exits with its child: `bun run dev` is a supervisor process whose
+ * only job is to mirror the script it spawned, so signalling the server ends
+ * the user's dev loop with it. Leaving those alone by default is what keeps
+ * `ompchamber stop` from killing a loop it did not start; an explicit
+ * `--port <port>` (or `--all`) still ends one, deliberately.
+ */
+export function isCliManaged(launchMode: string | null | undefined): boolean {
+  return launchMode === 'daemon' || launchMode === 'foreground';
+}
+
+/**
+ * Why an instance the CLI does not own is left alone, without the action. Each
+ * command that would end a server appends its own next step, so the two cannot
+ * describe the same `launchMode` differently.
+ */
+export function unmanagedReason(launchMode: string | null | undefined): string {
+  if (launchMode === 'direct') return 'runs from source (`bun run dev` / `bun run start`)';
+  return 'is not managed by the ompchamber CLI';
+}

package/src/server/lib/lifecycle/port-guard.ts

@@ -22,6 +22,7 @@
 
 import fs from 'fs';
 
+import { flockAvailable, tryFlock } from '@/server/lib/lifecycle/flock';
 import { getProcessState } from '@/server/lib/lifecycle/identity';
 import { describeOccupant, findOccupant } from '@/server/lib/lifecycle/occupant';
 import { getLockPath } from '@/server/lib/lifecycle/paths';
@@ -48,13 +49,27 @@ export interface PortLock {
  * Two starters racing on one free port would each probe it as free and then
  * fight over the bind, with the loser reporting a bare `EADDRINUSE` against a
  * process it cannot identify yet. Holding the lock across probe-and-bind makes
- * the loser fail with a message that names the actual situation. A lock whose
- * holder is dead (or is not OMPChamber, i.e. a recycled PID) is reclaimed.
+ * the loser fail with a message that names the actual situation.
  *
- * Returns null when another starter holds the lock through the wait window.
+ * The mechanism is `flock(2)` when the host has it (see `flock.ts`): the kernel
+ * releases it on process death, so there is no stale-holder case to detect and
+ * no polling loop. The PID-file path below stays as the fallback for a host
+ * without `flock` (Windows, a filesystem answering `ENOLCK`); it needs the
+ * extra machinery — PID readback, `getProcessState` classification, and
+ * reclaiming a lock whose holder died or whose PID was recycled.
  */
 export async function acquirePortLock(port: number, waitMs = LOCK_WAIT_MS): Promise<PortLock | null> {
   const lockPath = getLockPath(port);
+  if (flockAvailable()) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      const handle = tryFlock(lockPath);
+      if (handle) return handle;
+      if (Date.now() >= deadline) return null;
+      await Bun.sleep(150);
+    }
+  }
+
   const deadline = Date.now() + waitMs;
   for (;;) {
     try {