@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/omp/session/goal-driver.server.ts

@@ -0,0 +1,230 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The goal loop's driver: Kabmo asks the AUDITOR after every turn and
+ * obeys the verdict.
+ *
+ * Ownership moved here from the child's extension deliberately. The extension
+ * can see ceilings and budgets but not whether the objective was met, so with
+ * the loop inside the child the only termination authority was the working
+ * agent's own word. An independent auditor is a model call, which the child
+ * cannot make — and Kabmo is where the session's turn boundaries, the
+ * persisted goal record and the client stream all meet.
+ *
+ * What stays in the child: opening the continuation TURN. Only the extension
+ * can send the hidden message (`display:false`) that re-enters the loop without
+ * leaving a user bubble, and it is also where the hard stops live (token
+ * budget, autoturn ceiling). So the driver PACES the loop — `goal continue` —
+ * and the extension either opens the next turn or reports why it will not.
+ *
+ * Failure handling follows OpenChamber's rule: one unchecked continuation is
+ * allowed, a second consecutive audit failure stops the goal rather than
+ * driving blind to the turn cap.
+ */
+
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { loadPersistedModes } from '@/server/lib/omp/session/modes';
+import { loadSessionModel } from '@/server/lib/omp/session/messages';
+import { modeCommandPrompt } from '@/server/lib/omp/mode/request';
+import { extractTextFromContent } from '@/shared/lib/omp/session/mapper';
+import { decideGoalProgress, runGoalAudit, type GoalAuditAnswers, type GoalAuditRequest } from '@/server/lib/omp/session/goal-auditor.server';
+import { readGoalSettings, type GoalSettings } from '@/server/lib/omp/session/goal-settings.server';
+import type { AgentEvent } from '@/server/lib/omp/rpc/constants';
+import type { GoalContinuationStop, GoalRecord } from '@/shared/lib/omp/mode/types';
+
+/** What the driver needs from the session wrapper it was invoked on.
+ *
+ *  Optional so the frame fold can pass the host it already has: the real host
+ *  (the session wrapper) carries all four, while a test host may carry only the
+ *  fields the fold itself reads. `driveGoalAfterTurn` returns early without the
+ *  ones it cannot work without — a driver that cannot send must not decide. */
+export interface GoalDriverHost {
+  sessionId?: string;
+  cwd?: string;
+  send?(command: Record<string, unknown>): Promise<unknown>;
+  emit?(event: AgentEvent): void;
+}
+
+export interface GoalDriverContext {
+  goal: GoalRecord;
+  /** The loop's standing verdict; a stopped verdict means "do not drive". */
+  continuationStop: GoalContinuationStop | 'complete' | undefined;
+  /** The goal's own automatic-turn ceiling, persisted when it was created. */
+  maxTurns?: number;
+}
+
+export interface GoalDriverDeps {
+  audit?: (request: GoalAuditRequest) => Promise<GoalAuditAnswers | null>;
+  context?: (sessionId: string) => Promise<GoalDriverContext | null>;
+  model?: (sessionId: string) => Promise<string | undefined>;
+  /** The loop's own settings (`goalAuditEnabled` / `goalAuditModel`). */
+  settings?: () => Promise<GoalSettings>;
+}
+
+/** Consecutive "the agent needs the user" verdicts before the goal is stopped:
+ *  one snag is never allowed to end a goal. */
+export const BLOCKED_STRIKE_LIMIT = 3;
+/** Consecutive audits that could not be taken. The first one continues
+ *  unchecked; the second stops the goal. */
+export const AUDIT_FAILURE_LIMIT = 2;
+
+interface DriverState {
+  goalId: string;
+  strikes: number;
+  failures: number;
+  running: boolean;
+}
+
+/** Process-wide like the other server caches: a `bun --hot` reload re-evaluates
+ *  this module while the sessions on the other side stay alive. */
+function store(): Map<string, DriverState> {
+  const global = globalThis as unknown as { __kabmoGoalDriver?: Map<string, DriverState> };
+  global.__kabmoGoalDriver ??= new Map<string, DriverState>();
+  return global.__kabmoGoalDriver;
+}
+
+/** Forget the strikes for a session — an explicit Resume is a fresh start. */
+export function resetGoalDriverState(sessionId: string): void {
+  store().delete(sessionId);
+}
+
+async function defaultContext(sessionId: string): Promise<GoalDriverContext | null> {
+  const file = await findSessionFileById(sessionId);
+  if (!file) return null;
+  const modes = await loadPersistedModes(file);
+  const goal = modes.goalRecord;
+  if (!modes.goal || !goal || goal.status !== 'active') return null;
+  return {
+    goal,
+    continuationStop: modes.goalContinuation?.stopped as GoalDriverContext['continuationStop'],
+    maxTurns: modes.goalMaxTurns ?? undefined,
+  };
+}
+
+async function defaultModel(sessionId: string): Promise<string | undefined> {
+  const file = await findSessionFileById(sessionId);
+  if (!file) return undefined;
+  const model = await loadSessionModel(file);
+  return model ? `${model.provider}/${model.modelId}` : undefined;
+}
+
+/** The last thing the agent said — what the auditor judges. */
+export function lastAssistantText(messages: unknown): string {
+  if (!Array.isArray(messages)) return '';
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const entry = messages[i];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const record = entry as Record<string, unknown>;
+    if (record.role !== 'assistant') continue;
+    const text = extractTextFromContent(record.content).trim();
+    if (text) return text;
+  }
+  return '';
+}
+
+export interface GoalTurnInput {
+  host: GoalDriverHost;
+  /** The frames `agent_end` carried: the turn's messages. */
+  messages: unknown;
+  deps?: GoalDriverDeps;
+}
+
+/**
+ * One decision, after one turn.
+ *
+ * Called from the frame fold's terminal `agent_end`, which is the only moment
+ * that knows a run has genuinely ended.
+ */
+export async function driveGoalAfterTurn({ host, messages, deps = {} }: GoalTurnInput): Promise<void> {
+  const audit = deps.audit ?? runGoalAudit;
+  const readContext = deps.context ?? defaultContext;
+  const readModel = deps.model ?? defaultModel;
+  const readSettings = deps.settings ?? readGoalSettings;
+  const sessionId = host.sessionId;
+  const cwd = host.cwd;
+  // Bound, not destructured: the wrapper's `send` reaches into its own state
+  // (`dispatchSessionCommand(this, …)`), so a bare function reference throws
+  // "undefined is not an object" the moment the driver tries to send.
+  const send = host.send?.bind(host);
+  if (!sessionId || !cwd || !send) return;
+
+  const settings = await readSettings();
+  // Off means a goal still exists and can be paused/resumed by hand, but
+  // nothing advances it on its own — no audit, no continuation.
+  if (!settings.auditEnabled) return;
+
+  const context = await readContext(sessionId);
+  if (!context) {
+    resetGoalDriverState(sessionId);
+    return;
+  }
+  // A standing verdict is the operator's stop (ceiling, budget, blocked,
+  // complete): the loop stays down until Resume clears it.
+  if (context.continuationStop) return;
+
+  const states = store();
+  const previous = states.get(sessionId);
+  const state: DriverState = previous && previous.goalId === context.goal.id
+    ? previous
+    : { goalId: context.goal.id, strikes: 0, failures: 0, running: false };
+  states.set(sessionId, state);
+  if (state.running) return;
+
+  const answer = lastAssistantText(messages);
+  if (!answer) return;
+
+  // The configured auditor wins; the session's own model is the fallback, so a
+  // goal loop never silently costs the operator a provider they did not pick.
+  const model = settings.auditModel || (await readModel(sessionId));
+  state.running = true;
+  host.emit?.({ type: 'goal_evaluating', evaluating: true });
+  let answers: GoalAuditAnswers | null = null;
+  try {
+    answers = await audit({ objective: context.goal.objective, answer, cwd, model });
+  } finally {
+    state.running = false;
+    host.emit?.({ type: 'goal_evaluating', evaluating: false });
+  }
+
+  const command = (action: string, payload?: Record<string, unknown>) => {
+    void send({ type: 'prompt', message: modeCommandPrompt({ scope: 'goal', action, payload }) });
+  };
+  // The child's ceiling map is per-process, and this driver may be talking to a
+  // child that never saw the goal created (a resume, another Kabmo instance).
+  // The persisted number rides every `continue` so the stop stays the goal's.
+  const continueTurn = () => {
+    command('continue', context.maxTurns === undefined ? undefined : { maxTurns: context.maxTurns });
+  };
+
+  if (!answers) {
+    state.failures += 1;
+    if (state.failures >= AUDIT_FAILURE_LIMIT) {
+      // A checker that cannot answer must not drive the loop to the cap.
+      command('done', { stopped: 'audit-failed' });
+      return;
+    }
+    continueTurn();
+    return;
+  }
+
+  state.failures = 0;
+  const verdict = decideGoalProgress(answers);
+  if (verdict === 'complete') {
+    command('done', { stopped: 'complete' });
+    return;
+  }
+  if (verdict === 'blocked') {
+    state.strikes += 1;
+    if (state.strikes >= BLOCKED_STRIKE_LIMIT) {
+      command('done', { stopped: 'blocked' });
+      return;
+    }
+    continueTurn();
+    return;
+  }
+  state.strikes = 0;
+  continueTurn();
+}

package/src/server/lib/omp/session/goal-driver.test.ts

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The goal driver: what Kabmo does after every finished turn.
+ *
+ * The rules worth pinning are the ones a naive loop gets wrong — a single
+ * "blocked" verdict must NOT end a goal (three in a row do), a check that could
+ * not run must not drive the loop blind to the ceiling, and a goal whose loop
+ * already stood down must stay down until the operator resumes it.
+ *
+ * The auditor and the goal context are injected: this suite must not spawn omp
+ * or read session files (same reason `runScheduledTask` takes its deps).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  driveGoalAfterTurn,
+  lastAssistantText,
+  resetGoalDriverState,
+  type GoalDriverContext,
+  type GoalDriverDeps,
+} from '@/server/lib/omp/session/goal-driver.server';
+import type { GoalAuditAnswers } from '@/server/lib/omp/session/goal-auditor.server';
+import type { GoalRecord } from '@/shared/lib/omp/mode/types';
+
+const goal: GoalRecord = {
+  id: 'g1',
+  objective: 'Ship the exporter',
+  status: 'active',
+  tokensUsed: 10,
+  timeUsedSeconds: 3,
+  createdAt: 0,
+  updatedAt: 0,
+};
+
+const SAY = (allDone: boolean, remaining: boolean, needsUser: boolean): GoalAuditAnswers => ({
+  allDone,
+  remaining,
+  needsUser,
+});
+
+interface Harness {
+  sent: string[];
+  events: Array<Record<string, unknown>>;
+  deps: GoalDriverDeps;
+  run: () => Promise<void>;
+}
+
+function harness(options: {
+  answers?: GoalAuditAnswers | null | Array<GoalAuditAnswers | null>;
+  context?: GoalDriverContext | null;
+  messages?: unknown;
+  sessionId?: string;
+  /** The loop's own settings; the auditor is ON unless a test says otherwise. */
+  auditEnabled?: boolean;
+  auditModel?: string;
+  /** Observe each audit request (model selection). */
+  onAudit?: (request: { model?: string; objective: string; answer: string }) => void;
+} = {}): Harness {
+  const sent: string[] = [];
+  const events: Array<Record<string, unknown>> = [];
+  const sessionId = options.sessionId ?? `s-${Math.random().toString(36).slice(2)}`;
+  resetGoalDriverState(sessionId);
+  const answers = Array.isArray(options.answers) ? options.answers : [options.answers ?? SAY(false, true, false)];
+  let call = 0;
+  const deps: GoalDriverDeps = {
+    audit: async (request) => {
+      options.onAudit?.(request);
+      return answers[Math.min(call++, answers.length - 1)] ?? null;
+    },
+    context: async () => (options.context === undefined ? { goal, continuationStop: undefined } : options.context),
+    model: async () => 'test/model',
+    settings: async () => ({ auditEnabled: options.auditEnabled !== false, auditModel: options.auditModel ?? '' }),
+  };
+  const host = {
+    sessionId,
+    cwd: '/tmp',
+    send: async (command: Record<string, unknown>) => {
+      sent.push(String(command.message));
+      return null;
+    },
+    emit: (event: Record<string, unknown>) => {
+      events.push(event);
+    },
+  };
+  return {
+    sent,
+    events,
+    deps,
+    run: () =>
+      driveGoalAfterTurn({
+        host,
+        messages: options.messages ?? [{ role: 'assistant', content: [{ type: 'text', text: 'done and verified' }] }],
+        deps,
+      }),
+  };
+}
+
+describe('driveGoalAfterTurn', () => {
+  test('asks the auditor and continues when it says keep going', async () => {
+    const h = harness({ answers: SAY(false, true, false) });
+    await h.run();
+
+    expect(h.sent).toEqual(['/kabmo-mode goal continue']);
+    // The spinner's window is exactly the audit: on before, off after.
+    expect(h.events.map((e) => e.evaluating)).toEqual([true, false]);
+  });
+
+  test('a complete verdict closes the loop', async () => {
+    const h = harness({ answers: SAY(true, false, false) });
+    await h.run();
+    expect(h.sent).toEqual([`/kabmo-mode goal done ${JSON.stringify({ stopped: 'complete' })}`]);
+  });
+
+  test('one blocked verdict does not end the goal, three do', async () => {
+    const blocked = SAY(false, true, true);
+    const h = harness({ answers: [blocked, blocked, blocked] });
+
+    await h.run();
+    await h.run();
+    // A one-off snag is not a verdict: the loop keeps going.
+    expect(h.sent).toEqual(['/kabmo-mode goal continue', '/kabmo-mode goal continue']);
+
+    await h.run();
+    expect(h.sent.at(-1)).toBe(`/kabmo-mode goal done ${JSON.stringify({ stopped: 'blocked' })}`);
+  });
+
+  test('an audit that could not run continues once, then stops', async () => {
+    const h = harness({ answers: [null, null] });
+    await h.run();
+    expect(h.sent).toEqual(['/kabmo-mode goal continue']);
+
+    await h.run();
+    expect(h.sent.at(-1)).toBe(`/kabmo-mode goal done ${JSON.stringify({ stopped: 'audit-failed' })}`);
+  });
+
+  test('a standing verdict keeps the loop down until Resume', async () => {
+    const h = harness({ context: { goal, continuationStop: 'max-turns' } });
+    await h.run();
+    expect(h.sent).toEqual([]);
+    expect(h.events).toEqual([]);
+  });
+
+  test('a goal that is not active is not driven at all', async () => {
+    const h = harness({ context: null });
+    await h.run();
+    expect(h.sent).toEqual([]);
+  });
+
+  test('a turn with no assistant report is not auditable', async () => {
+    const h = harness({ messages: [{ role: 'assistant', content: [{ type: 'text', text: '   ' }] }] });
+    await h.run();
+    expect(h.sent).toEqual([]);
+    expect(h.events).toEqual([]);
+  });
+
+  test("a host whose send needs its receiver is still called with one", async () => {
+    // The live bug: the driver destructured `host.send`, so the wrapper's own
+    // `dispatchSessionCommand(this, …)` ran with `this === undefined` and threw
+    // the moment the loop tried to continue. A method must be called on its
+    // object, or bound to it.
+    const calls: string[] = [];
+    const host = {
+      sessionId: `s-${Math.random().toString(36).slice(2)}`,
+      cwd: '/tmp',
+      calls,
+      send(this: { calls: string[] }, command: Record<string, unknown>) {
+        this.calls.push(String(command.message));
+        return Promise.resolve(null);
+      },
+      emit: () => {},
+    };
+    resetGoalDriverState(host.sessionId);
+
+    await driveGoalAfterTurn({
+      host,
+      messages: [{ role: 'assistant', content: [{ type: 'text', text: 'done and verified' }] }],
+      deps: {
+        audit: async () => SAY(false, true, false),
+        context: async () => ({ goal, continuationStop: undefined }),
+      },
+    });
+
+    expect(calls).toEqual(['/kabmo-mode goal continue']);
+  });
+
+  test('with the auditor switched off nothing is audited or advanced', async () => {
+    const h = harness({ answers: SAY(false, true, false), auditEnabled: false });
+    await h.run();
+    // A goal still exists (pause/resume, the objective, the budget) — the loop
+    // simply never continues on its own.
+    expect(h.sent).toEqual([]);
+    expect(h.events).toEqual([]);
+  });
+
+  test('a configured auditor model is asked instead of the session model', async () => {
+    const asked: Array<string | undefined> = [];
+    const h = harness({
+      answers: SAY(false, true, false),
+      auditModel: 'kenari/agnes-2-0-flash:free',
+      onAudit: (request) => asked.push(request.model),
+    });
+    await h.run();
+    expect(asked).toEqual(['kenari/agnes-2-0-flash:free']);
+  });
+});
+
+describe('lastAssistantText', () => {
+  test('takes the last assistant message, not a tool result or an earlier one', () => {
+    const text = lastAssistantText([
+      { role: 'assistant', content: [{ type: 'text', text: 'first' }] },
+      { role: 'toolResult', content: [{ type: 'text', text: 'output' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'the report' }] },
+    ]);
+    expect(text).toBe('the report');
+  });
+});

package/src/server/lib/omp/session/goal-settings.server.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The goal loop's own settings, read where the loop runs.
+ *
+ * They live in Kabmo settings blob beside the other Kabmo keys and
+ * `autoSessionTitle`, and the server reads them straight from SQLite on every
+ * decision — a goal can run for an hour across several turns, so a cached read
+ * would keep an old choice alive for exactly the window the operator was
+ * changing it in.
+ *
+ * Every value has a default and every read swallows its errors: a settings
+ * lookup must never be the reason a turn's settle path throws.
+ */
+
+import { readSettingsJson } from '@/server/lib/db/settings-store';
+import { getDb } from '@/server/db.server';
+
+const SETTINGS_BLOB_KEY = 'kabmo_settings';
+
+/** The auditor runs by default: a goal loop with no independent check is the
+ *  behaviour this setting exists to avoid. */
+const GOAL_AUDIT_DEFAULT = true;
+
+export interface GoalSettings {
+  /** Whether the auditor drives the loop at all. */
+  auditEnabled: boolean;
+  /** `provider/modelId` for the audit calls; empty = the session's own model. */
+  auditModel: string;
+}
+
+export async function readGoalSettings(): Promise<GoalSettings> {
+  try {
+    const db = await getDb();
+    const blob = await readSettingsJson<Record<string, unknown> | null>(db, SETTINGS_BLOB_KEY, null);
+    const enabled = blob?.goalAuditEnabled;
+    const model = blob?.goalAuditModel;
+    return {
+      auditEnabled: typeof enabled === 'boolean' ? enabled : GOAL_AUDIT_DEFAULT,
+      auditModel: typeof model === 'string' ? model.trim() : '',
+    };
+  } catch {
+    return { auditEnabled: GOAL_AUDIT_DEFAULT, auditModel: '' };
+  }
+}

package/src/server/lib/omp/session/goal-settings.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The goal loop's settings and the one value they share with the composer.
+ *
+ * `normalizeGoalBudget` is the load-bearing part: three surfaces accept a budget
+ * (the dialog field, the default in Settings, the wire payload), and "no budget"
+ * has to be `null` everywhere — omp refuses a non-positive budget, and a `0`
+ * that slipped through as "unlimited" would be read as "already spent" by the
+ * loop's own guard.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { normalizeGoalBudget } from '@/shared/lib/omp/mode/budget';
+import { readGoalSettings } from '@/server/lib/omp/session/goal-settings.server';
+
+describe('normalizeGoalBudget', () => {
+  test('a positive integer is a budget, whatever shape it arrived in', () => {
+    expect(normalizeGoalBudget(200000)).toBe(200000);
+    expect(normalizeGoalBudget(' 1500 ')).toBe(1500);
+  });
+
+  test('everything else means "no budget", never zero', () => {
+    expect(normalizeGoalBudget('')).toBeNull();
+    expect(normalizeGoalBudget('off')).toBeNull();
+    expect(normalizeGoalBudget(0)).toBeNull();
+    expect(normalizeGoalBudget(-5)).toBeNull();
+    expect(normalizeGoalBudget('1.5')).toBeNull();
+    expect(normalizeGoalBudget(null)).toBeNull();
+    expect(normalizeGoalBudget(undefined)).toBeNull();
+  });
+});
+
+describe('readGoalSettings', () => {
+  test('the auditor is on by default, on the session model', async () => {
+    // No database in this process: the read must still answer its defaults
+    // rather than throw into a turn's settle path.
+    const settings = await readGoalSettings();
+    expect(settings.auditEnabled).toBe(true);
+    expect(settings.auditModel).toBe('');
+  });
+});

package/src/server/lib/omp/session/lease-flock.server.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Is a session's omp ownership lease held by another process?
+ *
+ * omp takes an OS `flock` on `<session-owners>/<id>.lock` for the life of the
+ * omp process that opened the session (`tryAcquireSessionLease`). Asking
+ * "is it held" is therefore a `flock` question, and this asks it with the same
+ * primitive rather than shelling out to `lsof`.
+ *
+ * ## Why not a subprocess
+ *
+ * `lsof -t <file>` answers the same question, but it costs a process spawn plus
+ * a full descriptor-table scan — the exact cost `libproc`/`/proc` exist in
+ * `lifecycle/proc` to avoid (measured there: 32 ms for a spawn against 0.001 ms
+ * for a direct call). A spawn at spawn-time also makes the guard's own failure
+ * mode worse: an exhausted descriptor table fails `lsof` the same way it fails
+ * the omp spawn it was meant to protect.
+ *
+ * ## The probe acquires, briefly
+ *
+ * `flock` has no "test without taking". The probe takes `LOCK_EX | LOCK_NB`,
+ * which fails IMMEDIATELY (never blocks) when another holder exists, and
+ * releases at once when it succeeds. The window in which this process holds the
+ * lock is microseconds, and only ever when the lease was free — the same
+ * acquire-and-release omp itself performs, so no new race is introduced.
+ *
+ * A missing lease file is NOT "unknown": omp creates it on the first claim and
+ * never deletes it, so its absence means the session was never claimed — free.
+ */
+
+import fs from 'fs';
+import { dlopen, FFIType, type FFIFunction, type Library } from 'bun:ffi';
+
+/** `open(2)` access mode; `flock(2)` locking modes. */
+const O_RDONLY = 0;
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+
+const SYMBOLS = {
+  open: { args: [FFIType.cstring, FFIType.i32], returns: FFIType.i32 },
+  close: { args: [FFIType.i32], returns: FFIType.i32 },
+  flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+} satisfies Record<string, FFIFunction>;
+
+/** libc path per platform; null where `flock` does not exist (Windows). */
+function libcPath(): string | null {
+  if (process.platform === 'darwin') return '/usr/lib/libSystem.B.dylib';
+  if (process.platform === 'linux') return 'libc.so.6';
+  return null;
+}
+
+let cached: Library<typeof SYMBOLS> | null | undefined;
+
+/** Open libc once; a host that cannot is remembered as unavailable. */
+function bindLibc(): Library<typeof SYMBOLS> | null {
+  if (cached !== undefined) return cached;
+  const path = libcPath();
+  if (path === null) {
+    cached = null;
+    return null;
+  }
+  try {
+    cached = dlopen(path, SYMBOLS);
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+/**
+ * `true` when another process holds `leasePath`, `false` when it is free, and
+ * `null` when this host cannot answer (Windows, or a libc that would not open).
+ *
+ * A `null` is not "free": callers must fall back to another signal rather than
+ * spawn into a session that may be owned elsewhere.
+ */
+export function leaseHeldByAnother(leasePath: string): boolean | null {
+  if (!fs.existsSync(leasePath)) return false;
+  const libc = bindLibc();
+  if (libc === null) return null;
+  const fd = libc.symbols.open(Buffer.from(`${leasePath}\0`), O_RDONLY);
+  if (fd < 0) return null;
+  try {
+    const acquired = libc.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0;
+    if (acquired) libc.symbols.flock(fd, LOCK_UN);
+    return !acquired;
+  } finally {
+    libc.symbols.close(fd);
+  }
+}
+
+/**
+ * Hold an exclusive lock on `leasePath` for as long as the returned handle is
+ * alive. Exported for tests, which need a REAL second holder to prove the probe
+ * distinguishes held from free without spawning anything.
+ */
+export function holdLeaseForTest(leasePath: string): { release: () => void } {
+  const libc = bindLibc();
+  if (libc === null) throw new Error('flock unavailable on this host');
+  const fd = libc.symbols.open(Buffer.from(`${leasePath}\0`), O_RDONLY);
+  if (fd < 0) throw new Error(`could not open ${leasePath}`);
+  if (libc.symbols.flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+    libc.symbols.close(fd);
+    throw new Error(`could not lock ${leasePath}`);
+  }
+  return {
+    release: () => {
+      libc.symbols.flock(fd, LOCK_UN);
+      libc.symbols.close(fd);
+    },
+  };
+}