@cmetech/otto 1.1.0 → 1.2.4

package/packages/coworker-scratchpad/src/kernel-protocol.ts

@@ -0,0 +1,230 @@
+// NDJSON wire protocol between the scratchpad parent runtime and the kernel child.
+// One JSON object per line (\n terminated). See spec §2.4 + §6.3.
+
+export type { SkippedKey } from './namespace-codec.js';
+import type { SkippedKey } from './namespace-codec.js';
+
+export interface RunRequest {
+  id: number;
+  type: 'run';
+  code: string;
+}
+export interface SnapshotRequest {
+  id: number;
+  type: 'snapshot';
+}
+export type KernelRequest = RunRequest | SnapshotRequest;
+
+export interface ResultOk {
+  id: number;
+  type: 'result';
+  ok: true;
+  value: unknown;
+  stdout: string;
+}
+export interface ResultErr {
+  id: number;
+  type: 'result';
+  ok: false;
+  error: { name: string; message: string; stack?: string };
+}
+export type ResultResponse = ResultOk | ResultErr;
+
+// 1d2 — snapshot request/response. Parent triggers, kernel sync-writes
+// <scratchpadDir>/namespace.json and ACKs. Parent records the result into
+// meta.json before disposing the kernel.
+export interface SnapshotResultOk {
+  id: number;
+  type: 'snapshot_result';
+  ok: true;
+  skipped: SkippedKey[];
+  snapshotted_at: string;
+}
+export interface SnapshotResultErr {
+  id: number;
+  type: 'snapshot_result';
+  ok: false;
+  error: { name: string; message: string; stack?: string };
+}
+export type SnapshotResult = SnapshotResultOk | SnapshotResultErr;
+
+export type RecoveryNote =
+  | { kind: 'namespace-absent' }
+  | { kind: 'namespace-corrupt'; message: string }
+  | { kind: 'cells-since-snapshot'; n: number }
+  | { kind: 'snapshot-failed'; message: string };
+
+// Layer-B drawer payload recorded when a cell loads data through a collector.
+// `schema` is always null in Phase 1b; real schema introspection arrives with
+// DuckDB in sub-plan 1d.
+export interface DataLoadDrawer {
+  kind: 'data_load';
+  collector: string;
+  uri: string;
+  bytes: number | null;
+  rows_loaded: number | null;
+  loaded_at: string;
+  schema: null;
+}
+
+export interface ReadyEvent {
+  type: 'event';
+  event: 'ready';
+  recovery_notes?: RecoveryNote[];
+}
+export interface DataLoadEvent {
+  type: 'event';
+  event: 'data_load';
+  drawer: DataLoadDrawer;
+}
+export interface ProgressEvent {
+  type: 'event';
+  event: 'progress';
+  message?: string;
+}
+export interface StartupErrorEvent {
+  type: 'event';
+  event: 'startup_error';
+  kind: string;
+  error: { name: string; message: string; stack?: string };
+}
+// Phase 4 Task 9 — artifact RPC + event
+
+// Layer-B drawer payload recorded when a cell creates an artifact. Mirrors the
+// shape of DataLoadDrawer; persisted to memory by the manager (Task 10).
+export interface ArtifactCreateDrawer {
+  kind: 'artifact';
+  slug: string;
+  artifact_kind: string; // 'report' in v1
+  uri: string;
+  primary_path: string;
+  created_at: string;
+}
+
+// Kernel→manager request to create an artifact. Manager constructs the
+// ArtifactStore and writes the response back to kernel stdin.
+export interface ArtifactCreateRequest {
+  type: 'request';
+  request: 'artifact_create';
+  id: string;
+  kind: string; // 'report'
+  name: string;
+}
+export interface ArtifactCreateResponseOk {
+  type: 'response';
+  request: 'artifact_create';
+  id: string;
+  ok: true;
+  slug: string;
+  uri: string;
+  primary_path: string;
+}
+export interface ArtifactCreateResponseErr {
+  type: 'response';
+  request: 'artifact_create';
+  id: string;
+  ok: false;
+  error: string;
+}
+export type ArtifactCreateResponse = ArtifactCreateResponseOk | ArtifactCreateResponseErr;
+
+// Kernel→manager request to write files into an existing artifact dir.
+export interface ArtifactUpdateRequest {
+  type: 'request';
+  request: 'artifact_update';
+  id: string;
+  slug: string;
+  files: Array<{ path: string; content: string }>;
+}
+export interface ArtifactUpdateResponseOk {
+  type: 'response';
+  request: 'artifact_update';
+  id: string;
+  ok: true;
+  files_touched: string[];
+}
+export interface ArtifactUpdateResponseErr {
+  type: 'response';
+  request: 'artifact_update';
+  id: string;
+  ok: false;
+  error: string;
+}
+export type ArtifactUpdateResponse = ArtifactUpdateResponseOk | ArtifactUpdateResponseErr;
+
+// Event the kernel emits after a successful artifact_create RPC so the manager
+// can record the drawer into memory (mirrors DataLoadEvent).
+export interface ArtifactCreateEvent {
+  type: 'event';
+  event: 'artifact_create';
+  drawer: ArtifactCreateDrawer;
+}
+
+export type KernelRpcRequest = ArtifactCreateRequest | ArtifactUpdateRequest;
+export type KernelRpcResponse = ArtifactCreateResponse | ArtifactUpdateResponse;
+
+export type KernelEvent =
+  | ReadyEvent
+  | DataLoadEvent
+  | ProgressEvent
+  | StartupErrorEvent
+  | ArtifactCreateEvent;
+
+// Phase 4 Task 10: widened to include KernelRpcRequest so the manager-side
+// dispatch (child-process-runtime.ts readLoop) can narrow inbound artifact
+// RPC requests alongside results/events/snapshot_results. The dispatcher must
+// guard the ResultResponse branch with a discriminant check on `type === 'result'`
+// before touching `frame.id` (which is `string` on RPC frames and `number`
+// elsewhere).
+export type KernelFrame = ResultResponse | KernelEvent | SnapshotResult | KernelRpcRequest;
+
+export function isDataLoadEvent(frame: KernelFrame): frame is DataLoadEvent {
+  return frame.type === 'event' && frame.event === 'data_load';
+}
+
+export function isProgressEvent(frame: KernelFrame): frame is ProgressEvent {
+  return frame.type === 'event' && frame.event === 'progress';
+}
+
+export function isStartupErrorEvent(frame: KernelFrame): frame is StartupErrorEvent {
+  return frame.type === 'event' && frame.event === 'startup_error';
+}
+
+export function isSnapshotResult(frame: KernelFrame): frame is SnapshotResult {
+  return frame.type === 'snapshot_result';
+}
+
+export function isArtifactCreateEvent(frame: unknown): frame is ArtifactCreateEvent {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as { type?: unknown; event?: unknown };
+  return f.type === 'event' && f.event === 'artifact_create';
+}
+
+export function isArtifactCreateRequest(frame: unknown): frame is ArtifactCreateRequest {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as { type?: unknown; request?: unknown };
+  return f.type === 'request' && f.request === 'artifact_create';
+}
+
+export function isArtifactUpdateRequest(frame: unknown): frame is ArtifactUpdateRequest {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as { type?: unknown; request?: unknown };
+  return f.type === 'request' && f.request === 'artifact_update';
+}
+
+export function isArtifactCreateResponse(frame: unknown): frame is ArtifactCreateResponse {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as { type?: unknown; request?: unknown };
+  return f.type === 'response' && f.request === 'artifact_create';
+}
+
+export function isArtifactUpdateResponse(frame: unknown): frame is ArtifactUpdateResponse {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as { type?: unknown; request?: unknown };
+  return f.type === 'response' && f.request === 'artifact_update';
+}
+
+/** True for any `{type:'response'}` frame addressed to the kernel. */
+export function isKernelRpcResponse(frame: unknown): frame is KernelRpcResponse {
+  return isArtifactCreateResponse(frame) || isArtifactUpdateResponse(frame);
+}

package/packages/coworker-scratchpad/src/kernel-spawn.test.ts

@@ -0,0 +1,60 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { basename, isAbsolute } from 'node:path';
+import { filterEnv, kernelExecArgv, resolveKernelEntry } from './kernel-spawn.js';
+
+describe('filterEnv', () => {
+  it('keeps allowlisted vars, allow-prefixed vars, and strips everything else', () => {
+    const out = filterEnv({
+      PATH: '/usr/bin',
+      HOME: '/home/x',
+      LC_ALL: 'en_US.UTF-8',
+      OTTO_DS_servicenow_prod__token: 'injected',
+      NODE_OPTIONS: '--max-old-space-size=512',
+      RANDOM_THING: 'nope',
+      ANTHROPIC_API_KEY: 'secret',
+    });
+    assert.equal(out.PATH, '/usr/bin');
+    assert.equal(out.HOME, '/home/x');
+    assert.equal(out.LC_ALL, 'en_US.UTF-8');
+    assert.equal(out.OTTO_DS_servicenow_prod__token, 'injected');
+    assert.equal(out.NODE_OPTIONS, '--max-old-space-size=512');
+    assert.equal(out.RANDOM_THING, undefined);
+    assert.equal(out.ANTHROPIC_API_KEY, undefined);
+  });
+
+  it('strips denylisted API keys even though no allow-rule would admit them', () => {
+    const out = filterEnv({ OPENAI_API_KEY: 'x', LOOP24_GATEWAY_KEY: 'y' });
+    assert.equal(out.OPENAI_API_KEY, undefined);
+    assert.equal(out.LOOP24_GATEWAY_KEY, undefined);
+  });
+});
+
+describe('kernelExecArgv', () => {
+  it('forwards loader flags (with their values) and drops --test', () => {
+    const out = kernelExecArgv([
+      '--import',
+      './src/resources/extensions/workflow/tests/resolve-ts.mjs',
+      '--experimental-strip-types',
+      '--test',
+    ]);
+    assert.deepEqual(out, [
+      '--import',
+      './src/resources/extensions/workflow/tests/resolve-ts.mjs',
+      '--experimental-strip-types',
+    ]);
+  });
+
+  it('handles --flag=value form and returns empty for a bare --test', () => {
+    assert.deepEqual(kernelExecArgv(['--import=./x.mjs', '--test']), ['--import=./x.mjs']);
+    assert.deepEqual(kernelExecArgv(['--test']), []);
+  });
+});
+
+describe('resolveKernelEntry', () => {
+  it('returns an absolute path to a kernel-entry module', () => {
+    const entry = resolveKernelEntry();
+    assert.equal(isAbsolute(entry), true);
+    assert.ok(['kernel-entry.js', 'kernel-entry.ts'].includes(basename(entry)));
+  });
+});

package/packages/coworker-scratchpad/src/kernel-spawn.ts

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const ENV_ALLOW = new Set([
+  'PATH', 'HOME', 'TERM', 'SHELL', 'TMPDIR', 'TMP', 'TEMP',
+  'LANG', 'LANGUAGE', 'PWD', 'USER', 'LOGNAME',
+]);
+const ENV_ALLOW_PREFIXES = ['LC_', 'XDG_', 'OTTO_', 'NODE_'];
+const ENV_DENY = new Set([
+  'LOOP24_GATEWAY_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY',
+  'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'GITHUB_TOKEN',
+]);
+
+export function filterEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (ENV_DENY.has(key)) continue; // denylist overrides any allow-rule
+    if (ENV_ALLOW.has(key) || ENV_ALLOW_PREFIXES.some((p) => key.startsWith(p))) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+const FORWARD_FLAGS_WITH_VALUE = new Set([
+  '--import', '--loader', '--experimental-loader', '--require', '-r', '--conditions',
+]);
+const FORWARD_FLAGS_BOOLEAN = new Set([
+  '--experimental-strip-types', '--experimental-transform-types', '--no-warnings',
+]);
+
+export function kernelExecArgv(execArgv: string[] = process.execArgv): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < execArgv.length; i++) {
+    const arg = execArgv[i];
+    const eq = arg.indexOf('=');
+    const flag = eq >= 0 ? arg.slice(0, eq) : arg;
+    if (FORWARD_FLAGS_WITH_VALUE.has(flag)) {
+      out.push(arg);
+      if (eq < 0 && i + 1 < execArgv.length) out.push(execArgv[++i]);
+    } else if (FORWARD_FLAGS_BOOLEAN.has(flag)) {
+      out.push(arg);
+    }
+    // Everything else (--test, --watch, --test-*, …) is dropped.
+  }
+  return out;
+}
+
+export function resolveKernelEntry(): string {
+  const js = fileURLToPath(new URL('./kernel-entry.js', import.meta.url));
+  if (existsSync(js)) return js;
+  return fileURLToPath(new URL('./kernel-entry.ts', import.meta.url));
+}

package/packages/coworker-scratchpad/src/namespace-codec.test.ts

@@ -0,0 +1,102 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  NAMESPACE_SCHEMA_VERSION,
+  encodeNamespace,
+  decodeNamespace,
+} from './namespace-codec.js';
+
+describe('namespace-codec', () => {
+  it('round-trips primitives and plain objects', () => {
+    const { envelope } = encodeNamespace({ x: 1, s: 'hi', o: { a: [1, 2, 3] } }, () => 0);
+    assert.equal(envelope.schema_version, NAMESPACE_SCHEMA_VERSION);
+    assert.equal(typeof envelope.snapshot_b64, 'string');
+    assert.deepEqual(envelope.skipped, []);
+    const { values, skipped } = decodeNamespace(JSON.stringify(envelope));
+    assert.equal(values.x, 1);
+    assert.equal(values.s, 'hi');
+    assert.deepEqual(values.o, { a: [1, 2, 3] });
+    assert.deepEqual(skipped, []);
+  });
+
+  it('round-trips Date / Map / Set / BigInt with type identity preserved', () => {
+    const m = new Map<string, number>([['a', 1], ['b', 2]]);
+    const s = new Set<number>([10, 20, 30]);
+    const d = new Date(1717180800000);
+    const big = 9007199254740993n; // > Number.MAX_SAFE_INTEGER
+    const { envelope } = encodeNamespace({ m, s, d, big }, () => 0);
+    const { values } = decodeNamespace(JSON.stringify(envelope));
+    assert.ok(values.m instanceof Map);
+    assert.equal((values.m as Map<string, number>).get('b'), 2);
+    assert.ok(values.s instanceof Set);
+    assert.equal((values.s as Set<number>).has(20), true);
+    assert.ok(values.d instanceof Date);
+    assert.equal((values.d as Date).getTime(), 1717180800000);
+    assert.equal(values.big, 9007199254740993n);
+  });
+
+  it('records non-serializable values in skipped[] without aborting', () => {
+    // A function is not v8-serializable.
+    const fn = (): number => 1;
+    const { envelope, skipped } = encodeNamespace({ ok: 1, badFn: fn }, () => 0);
+    assert.equal(skipped.length, 1);
+    assert.equal(skipped[0].key, 'badFn');
+    assert.equal(skipped[0].ctor, 'Function');
+    assert.match(skipped[0].reason, /./); // non-empty reason
+    assert.equal(envelope.skipped.length, 1);
+    assert.equal(envelope.skipped[0].key, 'badFn');
+    assert.equal(envelope.skipped[0].ctor, 'Function');
+    const { values } = decodeNamespace(JSON.stringify(envelope));
+    assert.equal(values.ok, 1);
+    assert.equal('badFn' in values, false);
+  });
+
+  it('encodes ts from the injected clock', () => {
+    const { envelope } = encodeNamespace({ x: 1 }, () => 1717180800000);
+    assert.equal(envelope.ts, new Date(1717180800000).toISOString());
+  });
+
+  it('decodeNamespace throws on a wrong schema_version', () => {
+    const bad = JSON.stringify({ schema_version: 99, snapshot_b64: 'AAAA', skipped: [], ts: '...' });
+    assert.throws(() => decodeNamespace(bad), /schema_version/);
+  });
+
+  it('decodeNamespace throws on a malformed envelope (not JSON)', () => {
+    assert.throws(() => decodeNamespace('{not json'), /./);
+  });
+
+  it('decodeNamespace throws on a base64 payload that is not a valid v8 buffer', () => {
+    const bad = JSON.stringify({
+      schema_version: NAMESPACE_SCHEMA_VERSION,
+      snapshot_b64: Buffer.from('not-a-v8-buffer').toString('base64'),
+      skipped: [],
+      ts: '2026-05-31T00:00:00.000Z',
+    });
+    assert.throws(() => decodeNamespace(bad), /./);
+  });
+
+  it('demotes survivors to skipped[] when bulk serialize throws (defensive — never throws)', () => {
+    // A getter that throws only on its second invocation: passes the per-key probe,
+    // explodes on the final bulk serialize. The codec must demote all survivors and
+    // return cleanly rather than letting the exception propagate.
+    const evilObj: Record<string, unknown> = {};
+    let calls = 0;
+    Object.defineProperty(evilObj, 'x', {
+      enumerable: true,
+      configurable: true,
+      get() {
+        calls++;
+        if (calls > 1) throw new Error('second-call boom');
+        return 1;
+      },
+    });
+    const result = encodeNamespace({ evil: evilObj, plain: 42 }, () => 0);
+    assert.ok(result.skipped.length >= 1);
+    assert.ok(result.skipped.some((s) => s.reason.startsWith('bulk-serialize-failed')));
+    // The envelope is still well-formed — empty snapshot, well-typed.
+    assert.equal(typeof result.envelope.snapshot_b64, 'string');
+    const { values } = decodeNamespace(JSON.stringify(result.envelope));
+    assert.equal('evil' in values, false);
+    assert.equal('plain' in values, false); // demoted alongside in the bulk fallback
+  });
+});

package/packages/coworker-scratchpad/src/namespace-codec.ts

@@ -0,0 +1,90 @@
+import { serialize, deserialize } from 'node:v8';
+
+export const NAMESPACE_SCHEMA_VERSION = 1;
+
+export interface SkippedKey {
+  key: string;
+  ctor: string | null;
+  reason: string;
+}
+
+export interface NamespaceEnvelope {
+  schema_version: number;
+  snapshot_b64: string;
+  skipped: SkippedKey[];
+  ts: string;
+}
+
+export interface EncodeResult {
+  envelope: NamespaceEnvelope;
+  skipped: SkippedKey[];
+}
+
+export interface DecodeResult {
+  values: Record<string, unknown>;
+  skipped: SkippedKey[];
+}
+
+function ctorName(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  const c = (value as { constructor?: { name?: string } }).constructor;
+  return c?.name ?? null;
+}
+
+export function encodeNamespace(
+  values: Record<string, unknown>,
+  now: () => number,
+): EncodeResult {
+  const survivors: Record<string, unknown> = {};
+  const skipped: SkippedKey[] = [];
+  for (const key of Object.keys(values)) {
+    const value = values[key];
+    try {
+      // Probe by serializing a single-key wrapper. Cheaper than per-key buffers
+      // because the survivors map is re-serialized once below.
+      serialize({ [key]: value });
+      survivors[key] = value;
+    } catch (err) {
+      skipped.push({
+        key,
+        ctor: ctorName(value),
+        reason: (err as Error).message,
+      });
+    }
+  }
+  let snapshot_b64: string;
+  try {
+    snapshot_b64 = serialize(survivors).toString('base64');
+  } catch (err) {
+    // A value passed the per-key probe but threw on bulk serialize (e.g. a getter
+    // that throws on its second invocation). Demote every survivor to skipped so
+    // the caller still gets a usable envelope; the snapshot for this round is empty.
+    const reason = `bulk-serialize-failed: ${(err as Error).message}`;
+    for (const key of Object.keys(survivors)) {
+      skipped.push({ key, ctor: ctorName(survivors[key]), reason });
+    }
+    snapshot_b64 = serialize({}).toString('base64');
+  }
+  const envelope: NamespaceEnvelope = {
+    schema_version: NAMESPACE_SCHEMA_VERSION,
+    snapshot_b64,
+    skipped,
+    ts: new Date(now()).toISOString(),
+  };
+  return { envelope, skipped };
+}
+
+export function decodeNamespace(json: string): DecodeResult {
+  const parsed = JSON.parse(json) as Partial<NamespaceEnvelope>;
+  if (parsed.schema_version !== NAMESPACE_SCHEMA_VERSION) {
+    throw new Error(
+      `namespace-codec: unsupported schema_version ${String(parsed.schema_version)} (expected ${NAMESPACE_SCHEMA_VERSION})`,
+    );
+  }
+  if (typeof parsed.snapshot_b64 !== 'string') {
+    throw new Error('namespace-codec: missing snapshot_b64');
+  }
+  const buf = Buffer.from(parsed.snapshot_b64, 'base64');
+  const values = deserialize(buf) as Record<string, unknown>;
+  return { values, skipped: Array.isArray(parsed.skipped) ? parsed.skipped : [] };
+}

package/packages/coworker-scratchpad/src/scratchpad-lock.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { tmpdir, hostname } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import {
+  acquireLock,
+  releaseLock,
+  readLock,
+  isStaleLock,
+  ScratchpadBusyError,
+} from './scratchpad-lock.js';
+import type { LockInfo } from './scratchpad-lock.js';
+
+let root: string;
+let dir: string;
+
+// A real, definitely-dead PID: spawn a node that exits immediately, await its exit, reuse its PID.
+async function deadPid(): Promise<number> {
+  const c = spawn(process.execPath, ['-e', '']);
+  const pid = c.pid as number;
+  await new Promise<void>((r) => c.on('exit', () => r()));
+  return pid;
+}
+
+describe('scratchpad-lock', () => {
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'sp-lock-'));
+    dir = join(root, 'p1');
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('acquires a fresh lock holding this pid + host', () => {
+    const lock = acquireLock(dir);
+    assert.equal(lock.pid, process.pid);
+    assert.equal(lock.host, hostname());
+    assert.ok(existsSync(join(dir, 'lock.json')));
+  });
+
+  it('throws ScratchpadBusyError when a live holder already owns the lock', () => {
+    acquireLock(dir);
+    assert.throws(() => acquireLock(dir), (err: unknown) => {
+      assert.ok(err instanceof ScratchpadBusyError);
+      assert.match((err as Error).message, /scratchpad p1 is busy in another session/);
+      return true;
+    });
+  });
+
+  it('clears a stale lock (dead holder pid) and re-acquires', async () => {
+    await mkdir(dir, { recursive: true });
+    const stale: LockInfo = { pid: await deadPid(), host: hostname(), acquired_at: '2026-01-01T00:00:00.000Z' };
+    await writeFile(join(dir, 'lock.json'), JSON.stringify(stale));
+    const lock = acquireLock(dir);
+    assert.equal(lock.pid, process.pid);
+    assert.equal(JSON.parse(readFileSync(join(dir, 'lock.json'), 'utf8')).pid, process.pid);
+  });
+
+  it('force-takeover overwrites a live lock and records takeover_from', () => {
+    const prior = acquireLock(dir);
+    const taken = acquireLock(dir, { forceTakeover: true, takeoverReason: 'unit-test' });
+    assert.equal(taken.pid, process.pid);
+    assert.ok(taken.takeover_from);
+    assert.equal(taken.takeover_from!.pid, prior.pid);
+    assert.equal(taken.takeover_from!.reason, 'unit-test');
+  });
+
+  it('releaseLock removes our own lock so it can be re-acquired', () => {
+    acquireLock(dir);
+    releaseLock(dir);
+    assert.equal(existsSync(join(dir, 'lock.json')), false);
+    assert.doesNotThrow(() => acquireLock(dir));
+  });
+
+  it('releaseLock leaves a lock owned by another holder', async () => {
+    await mkdir(dir, { recursive: true });
+    const other: LockInfo = { pid: await deadPid(), host: hostname(), acquired_at: '2026-01-01T00:00:00.000Z' };
+    await writeFile(join(dir, 'lock.json'), JSON.stringify(other));
+    releaseLock(dir);
+    assert.ok(existsSync(join(dir, 'lock.json'))); // not ours -> untouched
+  });
+
+  it('isStaleLock is true for a dead holder and false for a live one', async () => {
+    const dead: LockInfo = { pid: await deadPid(), host: hostname(), acquired_at: '2026-01-01T00:00:00.000Z' };
+    const live: LockInfo = { pid: process.pid, host: hostname(), acquired_at: '2026-01-01T00:00:00.000Z' };
+    assert.equal(isStaleLock(dead), true);
+    assert.equal(isStaleLock(live), false);
+  });
+
+  it('readLock returns null when no lock exists', () => {
+    assert.equal(readLock(dir), null);
+  });
+});