@cmetech/otto 1.1.0 → 1.2.4

package/packages/coworker-utils/dist/lease.js

@@ -0,0 +1,67 @@
+// Lease helper for global background tasks.
+// Spec §6.4.
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+function isExpired(data) {
+    const acquired = Date.parse(data.acquired_at);
+    if (Number.isNaN(acquired))
+        return true;
+    return Date.now() > acquired + data.ttl_ms;
+}
+function pidAlive(pid, host) {
+    // We can only check pids on the same host.
+    if (host !== os.hostname())
+        return true; // assume alive on other hosts
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readLease(path) {
+    try {
+        const raw = await fs.readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function acquireLease(path, opts) {
+    const existing = await readLease(path);
+    if (existing && !isExpired(existing) && pidAlive(existing.pid, existing.host)) {
+        return false;
+    }
+    const data = {
+        pid: process.pid,
+        host: os.hostname(),
+        acquired_at: new Date().toISOString(),
+        ttl_ms: opts.ttlMs,
+        holder: opts.holder,
+    };
+    await fs.writeFile(path, JSON.stringify(data, null, 2), { mode: 0o600 });
+    return true;
+}
+export async function releaseLease(path) {
+    try {
+        await fs.unlink(path);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+export async function isLeaseHeld(path) {
+    const data = await readLease(path);
+    if (!data)
+        return false;
+    if (isExpired(data))
+        return false;
+    if (!pidAlive(data.pid, data.host))
+        return false;
+    return true;
+}

package/packages/coworker-utils/dist/logger.d.ts

@@ -0,0 +1,13 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LoggerOptions {
+    level?: LogLevel;
+    sink?: (line: string) => void;
+}
+export interface Logger {
+    debug(msg: string, ctx?: Record<string, unknown>): void;
+    info(msg: string, ctx?: Record<string, unknown>): void;
+    warn(msg: string, ctx?: Record<string, unknown>): void;
+    error(msg: string, ctx?: Record<string, unknown>): void;
+    child(suffix: string): Logger;
+}
+export declare function createLogger(namespace: string, opts?: LoggerOptions): Logger;

package/packages/coworker-utils/dist/logger.js

@@ -0,0 +1,26 @@
+// Lightweight logger wrapper. Spec §6.7.
+// Defers to a sink callable so otto-cli can wire it to the existing logger
+// without coworker-utils taking a direct dependency on otto-cli.
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+const DEFAULT_SINK = (line) => {
+    // Phase 0: write to stderr; otto-cli will replace this sink at wire time.
+    process.stderr.write(line + '\n');
+};
+export function createLogger(namespace, opts = {}) {
+    const level = opts.level ?? 'info';
+    const sink = opts.sink ?? DEFAULT_SINK;
+    const threshold = LEVEL_ORDER[level];
+    function emit(at, msg, ctx) {
+        if (LEVEL_ORDER[at] < threshold)
+            return;
+        const ctxPart = ctx ? ' ' + JSON.stringify(ctx) : '';
+        sink(`${new Date().toISOString()} ${at} ${namespace} ${msg}${ctxPart}`);
+    }
+    return {
+        debug: (msg, ctx) => emit('debug', msg, ctx),
+        info: (msg, ctx) => emit('info', msg, ctx),
+        warn: (msg, ctx) => emit('warn', msg, ctx),
+        error: (msg, ctx) => emit('error', msg, ctx),
+        child: (suffix) => createLogger(`${namespace}.${suffix}`, { level, sink }),
+    };
+}

package/packages/coworker-utils/dist/migration-runner.d.ts

@@ -0,0 +1,7 @@
+export type MigrationFn<TIn = unknown, TOut = unknown> = (data: TIn) => Promise<TOut>;
+export declare class MigrationRunner {
+    #private;
+    register<TIn = unknown, TOut = unknown>(kind: string, from: number, to: number, fn: MigrationFn<TIn, TOut>): void;
+    latestVersion(kind: string): number | null;
+    migrate(kind: string, fromVersion: number, data: unknown): Promise<unknown>;
+}

package/packages/coworker-utils/dist/migration-runner.js

@@ -0,0 +1,36 @@
+// Migration framework — forward-only schema migrations per file kind.
+// Spec §6.2, §3.4c.
+export class MigrationRunner {
+    #byKind = new Map();
+    register(kind, from, to, fn) {
+        if (to <= from) {
+            throw new Error(`migration target version (${to}) must be greater than source (${from})`);
+        }
+        const list = this.#byKind.get(kind) ?? [];
+        list.push({ from, to, fn: fn });
+        list.sort((a, b) => a.from - b.from);
+        this.#byKind.set(kind, list);
+    }
+    latestVersion(kind) {
+        const list = this.#byKind.get(kind);
+        if (!list || list.length === 0)
+            return null;
+        return Math.max(...list.map(m => m.to));
+    }
+    async migrate(kind, fromVersion, data) {
+        const target = this.latestVersion(kind);
+        if (target == null || fromVersion >= target)
+            return data;
+        const list = this.#byKind.get(kind);
+        let current = fromVersion;
+        let value = data;
+        while (current < target) {
+            const next = list.find(m => m.from === current);
+            if (!next)
+                throw new Error(`no migration from version ${current} to ${current + 1} for kind ${kind}`);
+            value = await next.fn(value);
+            current = next.to;
+        }
+        return value;
+    }
+}

package/packages/coworker-utils/dist/ndjson-channel.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from 'node:stream';
+export declare function writeNdjson(stream: Writable, message: unknown): Promise<void>;
+export declare function readNdjson(stream: Readable): AsyncGenerator<unknown>;

package/packages/coworker-utils/dist/ndjson-channel.js

@@ -0,0 +1,38 @@
+export async function writeNdjson(stream, message) {
+    const line = JSON.stringify(message) + '\n';
+    await new Promise((resolve, reject) => {
+        stream.write(line, 'utf8', (err) => (err ? reject(err) : resolve()));
+    });
+}
+export async function* readNdjson(stream) {
+    stream.setEncoding('utf8');
+    let buffer = '';
+    let lineNumber = 0;
+    for await (const chunk of stream) {
+        buffer += chunk;
+        let idx;
+        while ((idx = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 1);
+            lineNumber++;
+            if (line.length === 0)
+                continue;
+            try {
+                yield JSON.parse(line);
+            }
+            catch (err) {
+                throw new Error(`NDJSON parse error at line ${lineNumber}: ${err.message}`);
+            }
+        }
+    }
+    // Tail (no trailing newline)
+    if (buffer.length > 0) {
+        lineNumber++;
+        try {
+            yield JSON.parse(buffer);
+        }
+        catch (err) {
+            throw new Error(`NDJSON parse error at line ${lineNumber}: ${err.message}`);
+        }
+    }
+}

package/packages/coworker-utils/dist/secret-scanner.d.ts

@@ -0,0 +1,10 @@
+export interface SecretHit {
+    kind: string;
+    start: number;
+    end: number;
+    preview: string;
+}
+export declare class SecretScanner {
+    scan(text: string): SecretHit[];
+    redact(text: string): string;
+}

package/packages/coworker-utils/dist/secret-scanner.js

@@ -0,0 +1,42 @@
+// SecretScanner — stub gate before any disk write to memory layers A/B.
+// Spec §6.5.
+// Patterns are intentionally conservative — false negatives are OK in v1; false positives in
+// memory are a real cost (user lessons get over-redacted). Tighten or extend as Phase 3 reveals
+// real-world content.
+const PATTERNS = [
+    { kind: 'anthropic_api_key', regex: /sk-ant-api03-[A-Za-z0-9_-]{40,}/g },
+    { kind: 'openai_api_key', regex: /sk-(?:proj-)?[A-Za-z0-9]{40,}/g },
+    { kind: 'aws_access_key_id', regex: /AKIA[0-9A-Z]{16}/g },
+    { kind: 'github_pat', regex: /gh[pous]_[A-Za-z0-9]{36,}/g },
+];
+export class SecretScanner {
+    scan(text) {
+        const hits = [];
+        for (const { kind, regex } of PATTERNS) {
+            regex.lastIndex = 0;
+            let m;
+            while ((m = regex.exec(text)) != null) {
+                hits.push({
+                    kind,
+                    start: m.index,
+                    end: m.index + m[0].length,
+                    preview: m[0].slice(0, 8) + '...',
+                });
+            }
+        }
+        return hits.sort((a, b) => a.start - b.start);
+    }
+    redact(text) {
+        const hits = this.scan(text);
+        if (hits.length === 0)
+            return text;
+        let out = '';
+        let cursor = 0;
+        for (const h of hits) {
+            out += text.slice(cursor, h.start) + `[REDACTED:${h.kind}]`;
+            cursor = h.end;
+        }
+        out += text.slice(cursor);
+        return out;
+    }
+}

package/packages/coworker-utils/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@otto/coworker-utils",
+  "version": "0.0.1",
+  "description": "Otto co-worker package: coworker-utils",
+  "type": "module",
+  "otto": {
+    "linkable": true,
+    "scope": "@otto",
+    "name": "coworker-utils"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:publish": "tsc -p tsconfig.publish.json"
+  },
+  "files": ["dist"]
+}

package/packages/coworker-utils/src/audit-log.test.ts

@@ -0,0 +1,140 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { appendFileSync, mkdtempSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AuditLog, type AuditRecord } from './audit-log.js';
+
+function tmp(): string { return mkdtempSync(join(tmpdir(), 'audit-')); }
+
+describe('AuditLog', () => {
+  it('appends a record as one JSONL line', () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl') });
+    const rec: AuditRecord = {
+      _schema: 1, ts: '2026-06-01T00:00:00.000Z',
+      producer: 'vault', action: 'set', detail: { engine: 'jira', name: 'prod' },
+    };
+    log.append(rec);
+    const text = readFileSync(join(dir, 'audit.jsonl'), 'utf8');
+    const lines = text.split('\n').filter(Boolean);
+    assert.equal(lines.length, 1);
+    const parsed = JSON.parse(text.trim());
+    assert.deepEqual(parsed, rec);
+  });
+
+  it('reads records back, newest first, with filters', async () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl') });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:00.000Z', producer: 'vault', action: 'set', detail: {} });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:01.000Z', producer: 'secret-scanner', action: 'redact', severity: 'warn', detail: {} });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:02.000Z', producer: 'vault', action: 'get', detail: {} });
+    const all: AuditRecord[] = [];
+    for await (const r of log.read({})) all.push(r);
+    assert.deepEqual(all.map(r => r.action), ['get', 'redact', 'set']);
+    const vaultOnly: AuditRecord[] = [];
+    for await (const r of log.read({ producer: 'vault' })) vaultOnly.push(r);
+    assert.deepEqual(vaultOnly.map(r => r.action), ['get', 'set']);
+  });
+
+  it('rotates at maxBytes threshold', () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl'), maxBytes: 200 });
+    const big = 'x'.repeat(60);
+    for (let i = 0; i < 5; i++) {
+      log.append({ _schema: 1, ts: `2026-06-01T00:00:0${i}.000Z`, producer: 'vault', action: 'set', detail: { pad: big } });
+    }
+    assert.equal(existsSync(join(dir, 'audit.1.jsonl')), true);
+    assert.ok(statSync(join(dir, 'audit.jsonl')).size < 200);
+  });
+
+  it('keeps at most 5 rotated tails', () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl'), maxBytes: 100, maxTails: 5 });
+    const pad = 'x'.repeat(40);
+    for (let i = 0; i < 50; i++) {
+      log.append({ _schema: 1, ts: `2026-06-01T00:00:${String(i).padStart(2,'0')}.000Z`, producer: 'vault', action: 'set', detail: { pad } });
+    }
+    for (let n = 1; n <= 5; n++) assert.equal(existsSync(join(dir, `audit.${n}.jsonl`)), true);
+    assert.equal(existsSync(join(dir, 'audit.6.jsonl')), false);
+  });
+
+  it('filters by since (inclusive lower bound)', async () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl') });
+    const t0 = '2026-06-01T00:00:00.000Z';
+    const t1 = '2026-06-01T00:00:01.000Z';
+    const t2 = '2026-06-01T00:00:02.000Z';
+    log.append({ _schema: 1, ts: t0, producer: 'vault', action: 'set', detail: {} });
+    log.append({ _schema: 1, ts: t1, producer: 'vault', action: 'set', detail: {} });
+    log.append({ _schema: 1, ts: t2, producer: 'vault', action: 'set', detail: {} });
+    const got: AuditRecord[] = [];
+    for await (const r of log.read({ since: t1 })) got.push(r);
+    assert.deepEqual(got.map(r => r.ts), [t2, t1]);
+  });
+
+  it('filters by severity', async () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl') });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:00.000Z', producer: 'vault', action: 'set', severity: 'info', detail: {} });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:01.000Z', producer: 'vault', action: 'set', severity: 'warn', detail: {} });
+    const got: AuditRecord[] = [];
+    for await (const r of log.read({ severity: 'warn' })) got.push(r);
+    assert.equal(got.length, 1);
+    assert.equal(got[0].severity, 'warn');
+  });
+
+  it('filters by engineId via detail.engine', async () => {
+    const dir = tmp();
+    const log = new AuditLog({ path: join(dir, 'audit.jsonl') });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:00.000Z', producer: 'vault', action: 'set', detail: { engine: 'jira' } });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:01.000Z', producer: 'vault', action: 'set', detail: { engine: 'datadog' } });
+    const got: AuditRecord[] = [];
+    for await (const r of log.read({ engineId: 'jira' })) got.push(r);
+    assert.equal(got.length, 1);
+    assert.equal((got[0].detail as { engine?: string }).engine, 'jira');
+  });
+
+  it('silently skips malformed lines', async () => {
+    const dir = tmp();
+    const path = join(dir, 'audit.jsonl');
+    const log = new AuditLog({ path });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:00.000Z', producer: 'vault', action: 'set', detail: { tag: 'first' } });
+    appendFileSync(path, '{bad json\n', { mode: 0o600 });
+    log.append({ _schema: 1, ts: '2026-06-01T00:00:01.000Z', producer: 'vault', action: 'set', detail: { tag: 'second' } });
+    const got: AuditRecord[] = [];
+    for await (const r of log.read({})) got.push(r);
+    assert.equal(got.length, 2);
+    assert.deepEqual(got.map(r => (r.detail as { tag: string }).tag), ['second', 'first']);
+  });
+
+  it('reads records from rotated tail files alongside current file', async () => {
+    const dir = tmp();
+    const path = join(dir, 'audit.jsonl');
+    const log = new AuditLog({ path, maxBytes: 200 });
+    const pad = 'x'.repeat(60);
+    // Write enough records to force at least one rotation.
+    for (let i = 0; i < 8; i++) {
+      log.append({
+        _schema: 1,
+        ts: `2026-06-01T00:00:0${i}.000Z`,
+        producer: 'vault',
+        action: 'set',
+        detail: { idx: i, pad },
+      });
+    }
+    // Confirm rotation actually happened (records exist in both files).
+    assert.equal(existsSync(join(dir, 'audit.1.jsonl')), true);
+    const currentLines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    const tailLines = readFileSync(join(dir, 'audit.1.jsonl'), 'utf8').split('\n').filter(Boolean);
+    assert.ok(currentLines.length > 0, 'current file should have records');
+    assert.ok(tailLines.length > 0, 'rotated tail should have records');
+
+    const got: AuditRecord[] = [];
+    for await (const r of log.read({})) got.push(r);
+    // All 8 appended records must come back, newest first.
+    assert.equal(got.length, 8);
+    const indices = got.map(r => (r.detail as { idx: number }).idx);
+    assert.deepEqual(indices, [7, 6, 5, 4, 3, 2, 1, 0]);
+  });
+});

package/packages/coworker-utils/src/audit-log.ts

@@ -0,0 +1,107 @@
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface AuditRecord {
+  _schema: 1;
+  ts: string;
+  producer: string;
+  action: string;
+  severity?: 'info' | 'warn';
+  sessionId?: string;
+  scratchpadName?: string;
+  pid?: number;
+  detail: Record<string, unknown>;
+}
+
+export interface AuditLogOptions {
+  path: string;
+  maxBytes?: number;
+  maxTails?: number;
+}
+
+export interface AuditFilter {
+  since?: string;             // ISO-8601 lower bound (inclusive)
+  producer?: string;
+  action?: string;
+  severity?: 'info' | 'warn';
+  engineId?: string;          // matches detail.engine if present
+}
+
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_TAILS = 5;
+
+export class AuditLog {
+  private readonly path: string;
+  private readonly maxBytes: number;
+  private readonly maxTails: number;
+
+  constructor(opts: AuditLogOptions) {
+    this.path = opts.path;
+    this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.maxTails = opts.maxTails ?? DEFAULT_MAX_TAILS;
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+  }
+
+  append(record: AuditRecord): void {
+    this.rotateIfNeeded();
+    const line = JSON.stringify(record) + '\n';
+    try {
+      appendFileSync(this.path, line, { mode: 0o600 });
+    } catch (err) {
+      process.stderr.write(`audit: write failed (${(err as Error).message}); continuing\n`);
+    }
+  }
+
+  async *read(filter: AuditFilter): AsyncIterable<AuditRecord> {
+    const files = this.listLogFiles();
+    const records: AuditRecord[] = [];
+    for (const f of files) {
+      if (!existsSync(f)) continue;
+      const text = readFileSync(f, 'utf8');
+      for (const line of text.split('\n')) {
+        if (!line) continue;
+        try {
+          const rec = JSON.parse(line) as AuditRecord;
+          if (!this.matches(rec, filter)) continue;
+          records.push(rec);
+        } catch { /* skip malformed line */ }
+      }
+    }
+    records.sort((a, b) => (a.ts === b.ts ? 0 : a.ts < b.ts ? 1 : -1));
+    for (const r of records) yield r;
+  }
+
+  private listLogFiles(): string[] {
+    const out = [this.path];
+    for (let n = 1; n <= this.maxTails; n++) {
+      out.push(`${this.path.replace(/\.jsonl$/, '')}.${n}.jsonl`);
+    }
+    return out;
+  }
+
+  private matches(rec: AuditRecord, f: AuditFilter): boolean {
+    if (f.producer && rec.producer !== f.producer) return false;
+    if (f.action && rec.action !== f.action) return false;
+    if (f.severity && rec.severity !== f.severity) return false;
+    if (f.since && rec.ts < f.since) return false;
+    if (f.engineId && (rec.detail as { engine?: string }).engine !== f.engineId) return false;
+    return true;
+  }
+
+  private rotateIfNeeded(): void {
+    if (!existsSync(this.path)) return;
+    const size = statSync(this.path).size;
+    if (size < this.maxBytes) return;
+    // Find next available tail slot; if maxTails full, drop tail N (delete) before shifting.
+    const base = this.path.replace(/\.jsonl$/, '');
+    const tailN = `${base}.${this.maxTails}.jsonl`;
+    if (existsSync(tailN)) unlinkSync(tailN);
+    for (let n = this.maxTails - 1; n >= 1; n--) {
+      const src = `${base}.${n}.jsonl`;
+      const dst = `${base}.${n + 1}.jsonl`;
+      if (existsSync(src)) renameSync(src, dst);
+    }
+    renameSync(this.path, `${base}.1.jsonl`);
+    closeSync(openSync(this.path, 'w', 0o600));
+  }
+}

package/packages/coworker-utils/src/index.ts

@@ -0,0 +1,6 @@
+export * from './ndjson-channel.js';
+export * from './lease.js';
+export * from './migration-runner.js';
+export * from './secret-scanner.js';
+export * from './logger.js';
+export * from './audit-log.js';

package/packages/coworker-utils/src/lease.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { acquireLease, releaseLease, isLeaseHeld } from './lease.js';
+
+let tmpdir: string;
+
+describe('lease helper', () => {
+  beforeEach(async () => {
+    tmpdir = await fs.mkdtemp(path.join(os.tmpdir(), 'lease-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpdir, { recursive: true, force: true });
+  });
+
+  it('acquires a free lease and writes PID + acquired_at + ttl_ms', async () => {
+    const lockPath = path.join(tmpdir, 'task.lock');
+    const ok = await acquireLease(lockPath, { ttlMs: 60_000 });
+    assert.equal(ok, true);
+    const raw = await fs.readFile(lockPath, 'utf8');
+    const data = JSON.parse(raw);
+    assert.equal(data.pid, process.pid);
+    assert.equal(typeof data.acquired_at, 'string');
+    assert.equal(data.ttl_ms, 60_000);
+  });
+
+  it('blocks a second acquire while the first is held', async () => {
+    const lockPath = path.join(tmpdir, 'task.lock');
+    await acquireLease(lockPath, { ttlMs: 60_000 });
+    const ok = await acquireLease(lockPath, { ttlMs: 60_000 });
+    assert.equal(ok, false);
+  });
+
+  it('release allows re-acquire', async () => {
+    const lockPath = path.join(tmpdir, 'task.lock');
+    await acquireLease(lockPath, { ttlMs: 60_000 });
+    await releaseLease(lockPath);
+    const ok = await acquireLease(lockPath, { ttlMs: 60_000 });
+    assert.equal(ok, true);
+  });
+
+  it('expired lease (past ttl) is auto-cleared on next acquire', async () => {
+    const lockPath = path.join(tmpdir, 'task.lock');
+    await acquireLease(lockPath, { ttlMs: 50 });
+    await new Promise(r => setTimeout(r, 100));
+    const ok = await acquireLease(lockPath, { ttlMs: 60_000 });
+    assert.equal(ok, true, 'expected expired lease to be reclaimable');
+  });
+
+  it('isLeaseHeld returns false for missing file', async () => {
+    const lockPath = path.join(tmpdir, 'missing.lock');
+    assert.equal(await isLeaseHeld(lockPath), false);
+  });
+
+  it('isLeaseHeld returns false for expired lease without clearing it', async () => {
+    const lockPath = path.join(tmpdir, 'task.lock');
+    await acquireLease(lockPath, { ttlMs: 50 });
+    await new Promise(r => setTimeout(r, 100));
+    assert.equal(await isLeaseHeld(lockPath), false);
+  });
+});

package/packages/coworker-utils/src/lease.ts

@@ -0,0 +1,76 @@
+// Lease helper for global background tasks.
+// Spec §6.4.
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+
+export interface LeaseOptions {
+  ttlMs: number;
+  holder?: string;
+}
+
+interface LeaseData {
+  pid: number;
+  host: string;
+  acquired_at: string;
+  ttl_ms: number;
+  holder?: string;
+}
+
+function isExpired(data: LeaseData): boolean {
+  const acquired = Date.parse(data.acquired_at);
+  if (Number.isNaN(acquired)) return true;
+  return Date.now() > acquired + data.ttl_ms;
+}
+
+function pidAlive(pid: number, host: string): boolean {
+  // We can only check pids on the same host.
+  if (host !== os.hostname()) return true;       // assume alive on other hosts
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readLease(path: string): Promise<LeaseData | null> {
+  try {
+    const raw = await fs.readFile(path, 'utf8');
+    return JSON.parse(raw) as LeaseData;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function acquireLease(path: string, opts: LeaseOptions): Promise<boolean> {
+  const existing = await readLease(path);
+  if (existing && !isExpired(existing) && pidAlive(existing.pid, existing.host)) {
+    return false;
+  }
+  const data: LeaseData = {
+    pid: process.pid,
+    host: os.hostname(),
+    acquired_at: new Date().toISOString(),
+    ttl_ms: opts.ttlMs,
+    holder: opts.holder,
+  };
+  await fs.writeFile(path, JSON.stringify(data, null, 2), { mode: 0o600 });
+  return true;
+}
+
+export async function releaseLease(path: string): Promise<void> {
+  try {
+    await fs.unlink(path);
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+}
+
+export async function isLeaseHeld(path: string): Promise<boolean> {
+  const data = await readLease(path);
+  if (!data) return false;
+  if (isExpired(data)) return false;
+  if (!pidAlive(data.pid, data.host)) return false;
+  return true;
+}