@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/store/artifacts.js

@@ -0,0 +1,173 @@
+/**
+ * Artifact storage: validated submissions and reports under
+ * `<run>/artifacts/<phase>/<wpId>/<stage>-<identity>-<n>.json|.md` (governance-mode
+ * sections 8.3 and 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * IDS ARE STABLE STRINGS: `p1/dev1/review-rev1-1` = phase 1 (1-based, `p` prefix), work
+ * package `dev1`, stage `review`, written by identity `rev1`, its 1st artifact. The id is
+ * also the relative path (minus extension), so `gov_read` can resolve an id without an
+ * index and a human can find the file by eye.
+ *
+ * EVERY ARTIFACT CARRIES A VISIBILITY TAG (`work | review | test | inspector`), derived
+ * from the stage and never from content. `engine/visibility.ts` filters on it; keeping the
+ * tag in the id's stage segment means the information boundary cannot be defeated by an
+ * artifact whose body claims to be something else.
+ *
+ * Phase-level artifacts (settle / integrate reports) have no work package; they use the
+ * reserved wp segment `_phase`.
+ */
+import { GOV_LIMITS } from '../limits.js';
+export const PHASE_WP_SEGMENT = '_phase';
+const TRUNCATION_MARK = '[truncated]';
+/** U+FFFD, built from its code point so this file stays pure ASCII. */
+const TRAILING_REPLACEMENT_CHARS = new RegExp(`${String.fromCharCode(0xfffd)}+$`);
+const SEGMENT = /^[a-z0-9_-]{1,32}$/;
+const FILE_STEM = /^([a-z]+)-([a-z0-9-]+)-(\d+)$/;
+/** The visibility tag of an artifact is a pure function of the stage that produced it. */
+export function artifactKindForStage(stage) {
+    switch (stage) {
+        case 'dev':
+        case 'fix':
+            return 'work';
+        case 'review':
+            return 'review';
+        case 'test':
+            return 'test';
+        case 'settle':
+        case 'integrate':
+            return 'inspector';
+    }
+}
+export function buildArtifactId(ref) {
+    return `p${ref.phase}/${ref.wpId}/${ref.stage}-${ref.identity}-${ref.n}`;
+}
+const STAGES = new Set([
+    'dev',
+    'review',
+    'test',
+    'settle',
+    'integrate',
+    'fix',
+]);
+/** Inverse of `buildArtifactId`. Returns null for anything that is not a well-formed id. */
+export function parseArtifactId(id) {
+    const parts = id.split('/');
+    if (parts.length !== 3)
+        return null;
+    const [phasePart, wpId, file] = parts;
+    const phase = /^p(\d{1,3})$/.exec(phasePart);
+    const stem = FILE_STEM.exec(file);
+    if (!phase || !stem || !SEGMENT.test(wpId))
+        return null;
+    const stage = stem[1];
+    if (!STAGES.has(stage))
+        return null;
+    const ref = {
+        phase: Number(phase[1]),
+        wpId,
+        stage: stage,
+        identity: stem[2],
+        n: Number(stem[3]),
+    };
+    return { ...ref, id: buildArtifactId(ref), kind: artifactKindForStage(ref.stage) };
+}
+/** Cut `text` to at most `maxBytes` UTF-8 bytes without leaving a broken character. */
+export function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    const room = Math.max(0, maxBytes - Buffer.byteLength(`\n${TRUNCATION_MARK}`));
+    const cut = Buffer.from(text, 'utf8').subarray(0, room).toString('utf8');
+    return `${cut.replace(TRAILING_REPLACEMENT_CHARS, '')}\n${TRUNCATION_MARK}`;
+}
+/**
+ * Serialize a machine-form submission within `submissionBytes`. JSON cannot be cut
+ * mid-text, so an oversized body is replaced by a small valid envelope carrying a head
+ * excerpt and the original size; the marker keeps the cut visible to every reader.
+ */
+export function boundedJson(value, maxBytes = GOV_LIMITS.submissionBytes) {
+    const full = JSON.stringify(value, null, 2);
+    if (Buffer.byteLength(full) <= maxBytes)
+        return full;
+    const head = truncateUtf8(full, Math.floor(maxBytes / 2));
+    return JSON.stringify({ truncated: true, originalBytes: Buffer.byteLength(full), head }, null, 2);
+}
+/** Thin domain layer over `RunStore`'s budgeted file primitives. */
+export class ArtifactStore {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Write `.json` (and `.md`) as artifact number n+1 for this (phase, wp, stage, who). */
+    async write(runId, input) {
+        const existing = await this.list(runId);
+        const same = existing.filter((r) => r.phase === input.phase &&
+            r.wpId === input.wpId &&
+            r.stage === input.stage &&
+            r.identity === input.identity);
+        const n = same.reduce((max, r) => Math.max(max, r.n), 0) + 1;
+        const ref = {
+            id: buildArtifactId({ ...input, n }),
+            phase: input.phase,
+            wpId: input.wpId,
+            stage: input.stage,
+            identity: input.identity,
+            n,
+            kind: artifactKindForStage(input.stage),
+        };
+        const base = ref.id;
+        const jsonText = boundedJson(input.json);
+        const jsonResult = await this.store.writeArtifactFile(runId, `${base}.json`, jsonText);
+        if (!jsonResult.ok)
+            return { ok: false, exhausted: true, message: jsonResult.message };
+        let bytes = jsonResult.bytes;
+        if (input.markdown !== undefined) {
+            const md = truncateUtf8(input.markdown, GOV_LIMITS.submissionBytes);
+            const mdResult = await this.store.writeArtifactFile(runId, `${base}.md`, md);
+            if (!mdResult.ok)
+                return { ok: false, exhausted: true, message: mdResult.message };
+            bytes += mdResult.bytes;
+        }
+        return { ok: true, ref, bytes };
+    }
+    /** Every artifact in the run, ordered by phase, wp, stage, identity, n. */
+    async list(runId) {
+        const refs = [];
+        for (const phaseDir of await this.store.listRunDir(runId, 'artifacts')) {
+            if (!phaseDir.isDirectory)
+                continue;
+            for (const wpDir of await this.store.listRunDir(runId, `artifacts/${phaseDir.name}`)) {
+                if (!wpDir.isDirectory)
+                    continue;
+                const dir = `artifacts/${phaseDir.name}/${wpDir.name}`;
+                for (const file of await this.store.listRunDir(runId, dir)) {
+                    if (!file.name.endsWith('.json'))
+                        continue;
+                    const ref = parseArtifactId(`${phaseDir.name}/${wpDir.name}/${file.name.slice(0, -5)}`);
+                    if (ref)
+                        refs.push(ref);
+                }
+            }
+        }
+        return refs.sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+    }
+    /** Resolve an id (never a path) to its content, or null if absent / malformed. */
+    async read(runId, id) {
+        const ref = parseArtifactId(id);
+        if (!ref)
+            return null;
+        const jsonText = await this.store.readRunFile(runId, `artifacts/${ref.id}.json`);
+        if (jsonText === null)
+            return null;
+        let json;
+        try {
+            json = JSON.parse(jsonText);
+        }
+        catch {
+            return null;
+        }
+        const markdown = await this.store.readRunFile(runId, `artifacts/${ref.id}.md`);
+        return { ref, json, markdown };
+    }
+}

package/dist/governance/store/atomic.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Atomic file replacement and durable line append for the governance store
+ * (governance-mode section 12.1 "write discipline").
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY THIS LIVES HERE AND IS NOT BORROWED FROM `session/`. The two trees must not couple:
+ * a change to session persistence (different retry table, different permissions) must not
+ * silently alter how the governance TRUTH file is written. Recorded here so nobody
+ * "helpfully" deduplicates it.
+ *
+ * ATOMIC REPLACE = same-directory temp file + rename. Same directory because `rename`
+ * is only atomic within one filesystem. On Windows an antivirus scanner or the search
+ * indexer routinely holds a freshly written file for a few milliseconds, which makes
+ * `rename` fail with EPERM / EBUSY / EACCES; those three are retried 3 times at
+ * 25 / 50 / 100 ms. Anything else is a real failure and is thrown at once.
+ *
+ * The filesystem is injected (`GovFs`) so a test can make `rename` fail on demand
+ * without touching the real disk - the only honest way to cover the retry path.
+ */
+/** The slice of a file handle the store needs. `fs.promises.FileHandle` satisfies it. */
+export interface GovFileHandle {
+    write(data: string): Promise<unknown>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface GovStat {
+    size: number;
+    mtimeMs: number;
+    isDirectory(): boolean;
+}
+/** The filesystem seam. Defaults to `node:fs/promises`; tests substitute a wrapper. */
+export interface GovFs {
+    mkdir(path: string, options: {
+        recursive: true;
+        mode: number;
+    }): Promise<unknown>;
+    open(path: string, flags: string, mode: number): Promise<GovFileHandle>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rm(path: string, options: {
+        recursive: true;
+        force: true;
+    }): Promise<void>;
+    readFile(path: string): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<GovStat>;
+}
+export declare const nodeGovFs: GovFs;
+/** Directories 0700, files 0600 (POSIX; ignored by Windows). */
+export declare const DIR_MODE = 448;
+export declare const FILE_MODE = 384;
+/** Backoff for the Windows rename race: 3 retries. */
+export declare const RENAME_RETRY_DELAYS_MS: readonly number[];
+export interface AtomicOptions {
+    fs?: GovFs;
+    /** Defaults to `process.platform`; injected so the retry path is testable anywhere. */
+    platform?: NodeJS.Platform;
+    /** Defaults to a real timer; tests pass a no-op or a recorder. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** mkdir -p with the store's directory mode. */
+export declare function ensureDir(path: string, fs?: GovFs): Promise<void>;
+/**
+ * Replace `path` with `data` atomically. Creates the parent directory if missing.
+ * On failure the temp file is removed (best effort) and the ORIGINAL error is thrown,
+ * so the previous content of `path` is never lost.
+ */
+export declare function atomicWriteFile(path: string, data: string, options?: AtomicOptions): Promise<void>;
+/**
+ * Append one line (a trailing newline is added) and fsync before returning. This is the
+ * durability point of `events.jsonl`: a returned promise means the line is on disk.
+ * `leadingNewline` repairs a log whose last line was torn by a crash (no final newline),
+ * so the new row does not get glued onto the fragment.
+ */
+export declare function appendLineFsync(path: string, line: string, options?: {
+    fs?: GovFs;
+    leadingNewline?: boolean;
+}): Promise<void>;

package/dist/governance/store/atomic.js

@@ -0,0 +1,119 @@
+/**
+ * Atomic file replacement and durable line append for the governance store
+ * (governance-mode section 12.1 "write discipline").
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY THIS LIVES HERE AND IS NOT BORROWED FROM `session/`. The two trees must not couple:
+ * a change to session persistence (different retry table, different permissions) must not
+ * silently alter how the governance TRUTH file is written. Recorded here so nobody
+ * "helpfully" deduplicates it.
+ *
+ * ATOMIC REPLACE = same-directory temp file + rename. Same directory because `rename`
+ * is only atomic within one filesystem. On Windows an antivirus scanner or the search
+ * indexer routinely holds a freshly written file for a few milliseconds, which makes
+ * `rename` fail with EPERM / EBUSY / EACCES; those three are retried 3 times at
+ * 25 / 50 / 100 ms. Anything else is a real failure and is thrown at once.
+ *
+ * The filesystem is injected (`GovFs`) so a test can make `rename` fail on demand
+ * without touching the real disk - the only honest way to cover the retry path.
+ */
+import { randomBytes } from 'node:crypto';
+import * as nodeFs from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const nodeGovFs = {
+    mkdir: (path, options) => nodeFs.mkdir(path, options),
+    open: (path, flags, mode) => nodeFs.open(path, flags, mode),
+    rename: (from, to) => nodeFs.rename(from, to),
+    unlink: (path) => nodeFs.unlink(path),
+    rm: (path, options) => nodeFs.rm(path, options),
+    readFile: (path) => nodeFs.readFile(path, 'utf8'),
+    readdir: (path) => nodeFs.readdir(path),
+    stat: (path) => nodeFs.stat(path),
+};
+/** Directories 0700, files 0600 (POSIX; ignored by Windows). */
+export const DIR_MODE = 0o700;
+export const FILE_MODE = 0o600;
+/** Backoff for the Windows rename race: 3 retries. */
+export const RENAME_RETRY_DELAYS_MS = [25, 50, 100];
+const RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorCode(error) {
+    if (error && typeof error === 'object' && 'code' in error) {
+        const code = error.code;
+        return typeof code === 'string' ? code : undefined;
+    }
+    return undefined;
+}
+/** mkdir -p with the store's directory mode. */
+export async function ensureDir(path, fs = nodeGovFs) {
+    await fs.mkdir(path, { recursive: true, mode: DIR_MODE });
+}
+async function writeTempFile(fs, tempPath, data) {
+    const handle = await fs.open(tempPath, 'w', FILE_MODE);
+    try {
+        await handle.write(data);
+        // fsync BEFORE rename: otherwise a power loss can leave the renamed name pointing
+        // at a zero-length file, which is the exact torn state this helper exists to prevent.
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function renameWithRetry(fs, from, to, options) {
+    const delays = options.retry ? RENAME_RETRY_DELAYS_MS : [];
+    for (let attempt = 0;; attempt++) {
+        try {
+            await fs.rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            const canRetry = attempt < delays.length && code !== undefined && RETRYABLE_CODES.has(code);
+            if (!canRetry)
+                throw error;
+            await options.sleep(delays[attempt]);
+        }
+    }
+}
+/**
+ * Replace `path` with `data` atomically. Creates the parent directory if missing.
+ * On failure the temp file is removed (best effort) and the ORIGINAL error is thrown,
+ * so the previous content of `path` is never lost.
+ */
+export async function atomicWriteFile(path, data, options = {}) {
+    const fs = options.fs ?? nodeGovFs;
+    const platform = options.platform ?? process.platform;
+    const sleep = options.sleep ?? realSleep;
+    await ensureDir(dirname(path), fs);
+    const tempPath = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        await writeTempFile(fs, tempPath, data);
+        await renameWithRetry(fs, tempPath, path, { retry: platform === 'win32', sleep });
+    }
+    catch (error) {
+        await fs.unlink(tempPath).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Append one line (a trailing newline is added) and fsync before returning. This is the
+ * durability point of `events.jsonl`: a returned promise means the line is on disk.
+ * `leadingNewline` repairs a log whose last line was torn by a crash (no final newline),
+ * so the new row does not get glued onto the fragment.
+ */
+export async function appendLineFsync(path, line, options = {}) {
+    const fs = options.fs ?? nodeGovFs;
+    await ensureDir(dirname(path), fs);
+    const handle = await fs.open(path, 'a', FILE_MODE);
+    try {
+        await handle.write(`${options.leadingNewline ? '\n' : ''}${line}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/governance/store/events-log.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `events.jsonl` parsing and the post-cap retention rule (governance-mode section 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The event log is the TRUTH; `run.json` / `ledger.json` are checkpoints rebuilt from it.
+ * Parsing is therefore tolerant in exactly one way: a line that does not parse is skipped
+ * and counted, never fatal. A crash mid-append leaves a torn LAST line, which is normal
+ * and must not stop a resume; a corrupt MIDDLE line is surfaced via `badLines` so the
+ * caller can decide whether the log is still trustworthy.
+ *
+ * RETENTION PAST THE BYTE CAP. The spec says "keep only ledger / stage_* / escalation
+ * types". Taken literally that would drop `escrow`, `eliminated`, `respawned`, `claim`,
+ * `ruling` and `resolution` rows, each of which changes the replayed ledger or run state,
+ * so a literal reading would make a compacted log replay to a DIFFERENT ledger than its
+ * checkpoint (breaks I-G2). The kept set therefore includes every type that replay folds;
+ * what is dropped are the audit-only rows: `view_*`, `ownership_violation`, `budget` and
+ * `submission` (the submission itself lives in the artifact store).
+ */
+import type { StoredEvent, StoredEventType } from '../types.js';
+/** Types that survive once `events.jsonl` has passed `GOV_LIMITS.eventsFileBytes`. */
+export declare const EVENTS_KEPT_AFTER_CAP: ReadonlySet<StoredEventType>;
+export interface ParsedEvents {
+    events: StoredEvent[];
+    /** Lines that were non-empty but did not parse into an event row. */
+    badLines: number;
+    lastSeq: number;
+    /** True when the file does not end with a newline (a torn tail). */
+    tornTail: boolean;
+    hasCompacted: boolean;
+}
+/** Parse the whole log. Order is file order; `lastSeq` is the maximum seen. */
+export declare function parseEventsText(text: string): ParsedEvents;
+/** One event row exactly as stored (single line, no trailing newline). */
+export declare function serializeEvent(event: StoredEvent): string;

package/dist/governance/store/events-log.js

@@ -0,0 +1,86 @@
+/**
+ * `events.jsonl` parsing and the post-cap retention rule (governance-mode section 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The event log is the TRUTH; `run.json` / `ledger.json` are checkpoints rebuilt from it.
+ * Parsing is therefore tolerant in exactly one way: a line that does not parse is skipped
+ * and counted, never fatal. A crash mid-append leaves a torn LAST line, which is normal
+ * and must not stop a resume; a corrupt MIDDLE line is surfaced via `badLines` so the
+ * caller can decide whether the log is still trustworthy.
+ *
+ * RETENTION PAST THE BYTE CAP. The spec says "keep only ledger / stage_* / escalation
+ * types". Taken literally that would drop `escrow`, `eliminated`, `respawned`, `claim`,
+ * `ruling` and `resolution` rows, each of which changes the replayed ledger or run state,
+ * so a literal reading would make a compacted log replay to a DIFFERENT ledger than its
+ * checkpoint (breaks I-G2). The kept set therefore includes every type that replay folds;
+ * what is dropped are the audit-only rows: `view_*`, `ownership_violation`, `budget` and
+ * `submission` (the submission itself lives in the artifact store).
+ */
+/** Types that survive once `events.jsonl` has passed `GOV_LIMITS.eventsFileBytes`. */
+export const EVENTS_KEPT_AFTER_CAP = new Set([
+    'run_started',
+    'stage_started',
+    'stage_ended',
+    'ledger',
+    'claim',
+    'ruling',
+    'escrow',
+    'eliminated',
+    'respawned',
+    'escalation',
+    'resolution',
+    'run_paused',
+    'run_resumed',
+    'run_closed',
+    'compacted',
+]);
+function isEventRow(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return (typeof row.seq === 'number' &&
+        typeof row.at === 'number' &&
+        typeof row.type === 'string' &&
+        typeof row.actor === 'string' &&
+        typeof row.payload === 'object' &&
+        row.payload !== null);
+}
+/** Parse the whole log. Order is file order; `lastSeq` is the maximum seen. */
+export function parseEventsText(text) {
+    const events = [];
+    let badLines = 0;
+    let lastSeq = 0;
+    let hasCompacted = false;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!isEventRow(parsed)) {
+                badLines += 1;
+                continue;
+            }
+            events.push(parsed);
+            if (parsed.seq > lastSeq)
+                lastSeq = parsed.seq;
+            if (parsed.type === 'compacted')
+                hasCompacted = true;
+        }
+        catch {
+            badLines += 1;
+        }
+    }
+    return {
+        events,
+        badLines,
+        lastSeq,
+        tornTail: text.length > 0 && !text.endsWith('\n'),
+        hasCompacted,
+    };
+}
+/** One event row exactly as stored (single line, no trailing newline). */
+export function serializeEvent(event) {
+    return JSON.stringify(event);
+}

package/dist/governance/store/run-lock.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `run.lock` primitives (governance-mode sections 8.4 and 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * A lock file is `{pid, startedAt, heartbeatAt}`. The owner refreshes `heartbeatAt` every
+ * `GOV_LIMITS.lockHeartbeatMs` while a stage runs. A lock is LIVE only when BOTH the
+ * heartbeat is fresher than `lockStaleMs` AND the holder pid still exists: a crash
+ * followed by an immediate restart is the common case, and making the user wait a minute
+ * for a lock whose owner is provably dead would be a pointless papercut. The pid check
+ * only ever ENABLES a takeover (a recycled pid can at worst delay one until the
+ * heartbeat goes stale), so it cannot cause a double-owner.
+ *
+ * Cross-process mutual exclusion cannot rely on the in-process FIFO mutex, hence the
+ * exclusive-create (`wx`) first attempt: two processes racing on a missing lock file
+ * cannot both win it. Two processes racing to take over a STALE lock can, so a takeover
+ * re-reads the file after writing and yields if somebody else's pid is in it.
+ */
+import { type GovFs } from './atomic.js';
+export interface LockInfo {
+    pid: number;
+    startedAt: number;
+    heartbeatAt: number;
+}
+export interface LockDeps {
+    fs?: GovFs;
+    now: () => number;
+    pid: number;
+    isPidAlive: (pid: number) => boolean;
+    staleMs: number;
+}
+export type AcquireResult = {
+    ok: true;
+    takenOver: boolean;
+} | {
+    ok: false;
+    holderPid: number;
+    message: string;
+};
+/** `kill(pid, 0)`: ESRCH means gone, EPERM means alive but not ours. */
+export declare function defaultIsPidAlive(pid: number): boolean;
+/** Parse a lock file; a missing or corrupt file reads as `null` (treated as stale). */
+export declare function readLock(path: string, fs?: GovFs): Promise<LockInfo | null>;
+/** True when a lock must be honoured: fresh heartbeat AND a living holder. */
+export declare function isLockLive(info: LockInfo | null, deps: LockDeps): boolean;
+/** Take the lock, or explain who holds it. Never throws for contention. */
+export declare function acquireLock(path: string, deps: LockDeps): Promise<AcquireResult>;
+/** Refresh `heartbeatAt`. Returns false when the lock is no longer ours (lost or removed). */
+export declare function refreshLock(path: string, deps: LockDeps): Promise<boolean>;
+/** Remove the lock only if it is ours; a foreign lock is left untouched. */
+export declare function removeLock(path: string, deps: LockDeps): Promise<void>;

package/dist/governance/store/run-lock.js

@@ -0,0 +1,122 @@
+/**
+ * `run.lock` primitives (governance-mode sections 8.4 and 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * A lock file is `{pid, startedAt, heartbeatAt}`. The owner refreshes `heartbeatAt` every
+ * `GOV_LIMITS.lockHeartbeatMs` while a stage runs. A lock is LIVE only when BOTH the
+ * heartbeat is fresher than `lockStaleMs` AND the holder pid still exists: a crash
+ * followed by an immediate restart is the common case, and making the user wait a minute
+ * for a lock whose owner is provably dead would be a pointless papercut. The pid check
+ * only ever ENABLES a takeover (a recycled pid can at worst delay one until the
+ * heartbeat goes stale), so it cannot cause a double-owner.
+ *
+ * Cross-process mutual exclusion cannot rely on the in-process FIFO mutex, hence the
+ * exclusive-create (`wx`) first attempt: two processes racing on a missing lock file
+ * cannot both win it. Two processes racing to take over a STALE lock can, so a takeover
+ * re-reads the file after writing and yields if somebody else's pid is in it.
+ */
+import { atomicWriteFile, nodeGovFs } from './atomic.js';
+/** `kill(pid, 0)`: ESRCH means gone, EPERM means alive but not ours. */
+export function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function isLockInfo(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (typeof record.pid === 'number' &&
+        typeof record.startedAt === 'number' &&
+        typeof record.heartbeatAt === 'number');
+}
+/** Parse a lock file; a missing or corrupt file reads as `null` (treated as stale). */
+export async function readLock(path, fs = nodeGovFs) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path));
+        return isLockInfo(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a lock must be honoured: fresh heartbeat AND a living holder. */
+export function isLockLive(info, deps) {
+    if (!info)
+        return false;
+    if (info.pid === deps.pid)
+        return false;
+    const fresh = deps.now() - info.heartbeatAt < deps.staleMs;
+    return fresh && deps.isPidAlive(info.pid);
+}
+function refusal(info, deps) {
+    const ageSec = Math.max(0, Math.round((deps.now() - info.heartbeatAt) / 1000));
+    const waitSec = Math.max(1, Math.ceil((deps.staleMs - (deps.now() - info.heartbeatAt)) / 1000));
+    return {
+        ok: false,
+        holderPid: info.pid,
+        message: `NOT ACCEPTED: this governance run is in use by another process (pid ${info.pid}, ` +
+            `last heartbeat ${ageSec}s ago). Close that session, or wait about ${waitSec}s ` +
+            'for its lock to expire.',
+    };
+}
+function freshLockText(deps, startedAt = deps.now()) {
+    const info = { pid: deps.pid, startedAt, heartbeatAt: deps.now() };
+    return JSON.stringify(info);
+}
+async function tryExclusiveCreate(path, deps) {
+    const fs = deps.fs ?? nodeGovFs;
+    let handle;
+    try {
+        handle = await fs.open(path, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        await handle.write(freshLockText(deps));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return true;
+}
+/** Take the lock, or explain who holds it. Never throws for contention. */
+export async function acquireLock(path, deps) {
+    const fs = deps.fs ?? nodeGovFs;
+    if (await tryExclusiveCreate(path, deps))
+        return { ok: true, takenOver: false };
+    const existing = await readLock(path, fs);
+    if (isLockLive(existing, deps))
+        return refusal(existing, deps);
+    await atomicWriteFile(path, freshLockText(deps), { fs });
+    const confirmed = await readLock(path, fs);
+    if (confirmed && confirmed.pid !== deps.pid)
+        return refusal(confirmed, deps);
+    return { ok: true, takenOver: existing !== null };
+}
+/** Refresh `heartbeatAt`. Returns false when the lock is no longer ours (lost or removed). */
+export async function refreshLock(path, deps) {
+    const fs = deps.fs ?? nodeGovFs;
+    const existing = await readLock(path, fs);
+    if (!existing || existing.pid !== deps.pid)
+        return false;
+    await atomicWriteFile(path, freshLockText(deps, existing.startedAt), { fs });
+    return true;
+}
+/** Remove the lock only if it is ours; a foreign lock is left untouched. */
+export async function removeLock(path, deps) {
+    const fs = deps.fs ?? nodeGovFs;
+    const existing = await readLock(path, fs);
+    if (existing && existing.pid !== deps.pid)
+        return;
+    await fs.unlink(path).catch(() => undefined);
+}