myshell-tools 1.0.0 → 2.0.0

package/dist/core/review.d.ts

@@ -0,0 +1,46 @@
+/**
+ * src/core/review.ts — pure review prompt builder and verdict parser.
+ *
+ * Provides utilities for building manager-style review prompts and parsing
+ * the structured review verdict returned by the reviewing model.
+ *
+ * Honesty Contract: parseReviewVerdict never throws and never fabricates a
+ * verdict — on any parse failure it defaults to fail-open `approve` with
+ * confidence null so a broken reviewer cannot block the user.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+/**
+ * The structured verdict returned by a reviewing model.
+ *
+ * - `approve`   : IC output is acceptable; proceed to final.
+ * - `revise`    : IC output needs changes; retry IC with the reviewer's notes.
+ * - `escalate`  : The issue is beyond IC scope; escalate to manager tier.
+ */
+export interface ReviewVerdict {
+    readonly verdict: 'approve' | 'revise' | 'escalate';
+    readonly notes: string;
+    readonly confidence: number | null;
+}
+/**
+ * Build a manager-style prompt asking the reviewer to critically assess the
+ * IC's work for correctness, quality, security, and completeness.
+ *
+ * The prompt instructs the model to end its response with a JSON verdict
+ * envelope on its own line:
+ *   {"verdict": "approve|revise|escalate", "notes": "...", "confidence": 0.0-1.0}
+ *
+ * @param task     - The original user task description.
+ * @param icOutput - The IC's full output text being reviewed.
+ */
+export declare function buildReviewPrompt(task: string, icOutput: string): string;
+/**
+ * Robustly parse the trailing JSON verdict envelope from a reviewer's output.
+ *
+ * Fail-open contract: if the envelope is absent or malformed, returns
+ * `{ verdict: 'approve', notes: '', confidence: null }`. A broken reviewer
+ * must never block the user. This function NEVER throws.
+ *
+ * @param output - The full text output from the reviewing model.
+ */
+export declare function parseReviewVerdict(output: string): ReviewVerdict;

package/dist/core/review.js

@@ -0,0 +1,148 @@
+/**
+ * src/core/review.ts — pure review prompt builder and verdict parser.
+ *
+ * Provides utilities for building manager-style review prompts and parsing
+ * the structured review verdict returned by the reviewing model.
+ *
+ * Honesty Contract: parseReviewVerdict never throws and never fabricates a
+ * verdict — on any parse failure it defaults to fail-open `approve` with
+ * confidence null so a broken reviewer cannot block the user.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a manager-style prompt asking the reviewer to critically assess the
+ * IC's work for correctness, quality, security, and completeness.
+ *
+ * The prompt instructs the model to end its response with a JSON verdict
+ * envelope on its own line:
+ *   {"verdict": "approve|revise|escalate", "notes": "...", "confidence": 0.0-1.0}
+ *
+ * @param task     - The original user task description.
+ * @param icOutput - The IC's full output text being reviewed.
+ */
+export function buildReviewPrompt(task, icOutput) {
+    return `\
+You are a senior-manager / staff-engineer reviewer performing a critical quality gate.
+
+You are reviewing the work of an individual-contributor (IC) engineer who was given the
+following task. Your job is to identify any issues with correctness, quality, security,
+or completeness in the IC's output before it reaches the user.
+
+Original task:
+${task}
+
+IC output to review:
+${icOutput}
+
+Review checklist (assess each dimension):
+1. CORRECTNESS — Does the output actually solve the task? Are there logic errors, off-by-ones,
+   or wrong assumptions?
+2. QUALITY — Is the code/output clean, idiomatic, and maintainable? Are there obvious smells?
+3. SECURITY — Are there any injection risks, secret leaks, missing input validation, or
+   privilege-escalation paths?
+4. COMPLETENESS — Does the output address all parts of the task, or does it miss edge cases?
+
+For any finding, anchor it to a specific file path and line range when applicable.
+
+After your review, append EXACTLY the following JSON object on its own line at the very end
+of your response (no trailing text after it):
+{"verdict": "approve|revise|escalate", "notes": "<specific, file-anchored feedback>", "confidence": <0.0-1.0>}
+
+verdict choices:
+  approve   — the IC output is correct, complete, and safe; ship it.
+  revise    — the IC output has fixable issues; provide actionable notes so the IC can retry.
+  escalate  — the task requires architectural judgement or has critical defects beyond IC scope.
+
+confidence: your honest estimate that your review is complete and correct (1.0 = certain).`;
+}
+const VALID_VERDICTS = new Set(['approve', 'revise', 'escalate']);
+/** Fail-open default used whenever the envelope is absent or malformed. */
+const FAIL_OPEN = { verdict: 'approve', notes: '', confidence: null };
+/**
+ * Attempt to extract the last JSON object from `text` that contains a `verdict` key.
+ * Returns null if no valid envelope is found.
+ */
+function extractVerdictEnvelope(text) {
+    const candidates = [];
+    let i = 0;
+    while (i < text.length) {
+        const start = text.indexOf('{', i);
+        if (start === -1)
+            break;
+        let depth = 0;
+        let j = start;
+        let foundClose = false;
+        while (j < text.length) {
+            if (text[j] === '{') {
+                depth++;
+            }
+            else if (text[j] === '}') {
+                depth--;
+                if (depth === 0) {
+                    foundClose = true;
+                    break;
+                }
+            }
+            j++;
+        }
+        if (foundClose) {
+            const candidate = text.slice(start, j + 1);
+            try {
+                const parsed = JSON.parse(candidate);
+                if (parsed !== null &&
+                    typeof parsed === 'object' &&
+                    !Array.isArray(parsed) &&
+                    'verdict' in parsed) {
+                    candidates.push(parsed);
+                }
+            }
+            catch {
+                // Not valid JSON — skip
+            }
+        }
+        i = start + 1;
+    }
+    if (candidates.length === 0)
+        return null;
+    return candidates[candidates.length - 1] ?? null;
+}
+/**
+ * Robustly parse the trailing JSON verdict envelope from a reviewer's output.
+ *
+ * Fail-open contract: if the envelope is absent or malformed, returns
+ * `{ verdict: 'approve', notes: '', confidence: null }`. A broken reviewer
+ * must never block the user. This function NEVER throws.
+ *
+ * @param output - The full text output from the reviewing model.
+ */
+export function parseReviewVerdict(output) {
+    // Guard: never throw on any input
+    if (typeof output !== 'string')
+        return FAIL_OPEN;
+    let envelope;
+    try {
+        envelope = extractVerdictEnvelope(output);
+    }
+    catch {
+        return FAIL_OPEN;
+    }
+    if (envelope === null)
+        return FAIL_OPEN;
+    // Validate verdict — must be one of the three allowed values
+    if (typeof envelope.verdict !== 'string' || !VALID_VERDICTS.has(envelope.verdict)) {
+        return FAIL_OPEN;
+    }
+    const verdict = envelope.verdict;
+    const notes = typeof envelope.notes === 'string' ? envelope.notes.trim() : '';
+    // confidence is optional — null when absent or invalid
+    let confidence = null;
+    if (typeof envelope.confidence === 'number' && isFinite(envelope.confidence)) {
+        confidence = Math.min(1, Math.max(0, envelope.confidence));
+    }
+    return { verdict, notes, confidence };
+}
+//# sourceMappingURL=review.js.map

package/dist/core/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../src/core/review.ts"],"names":[],"mappings":"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"}

package/dist/core/route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/core/route.ts — pure cost-aware routing decision.
+ *
+ * Given a tier, the set of currently available provider IDs, and the active
+ * Policy, selects the concrete provider+model that should handle the work.
+ *
+ * No I/O, no time, no randomness. Pricing data is pure reference data imported
+ * from infra/pricing (permitted by the purity guard because pricing.ts itself
+ * imports no fs/path/child_process).
+ */
+import type { Tier, RouteDecision, Policy } from './types.js';
+import type { ProviderId } from '../providers/port.js';
+/**
+ * Resolve a {@link RouteDecision} for the given tier.
+ *
+ * Algorithm:
+ *  1. Walk `policy.providerOrderByTier[tier]` in order.
+ *  2. For the first provider that is present in `available`, resolve the
+ *     cheapest model for that provider+tier via `getCheapestForTier`.
+ *  3. If none of the policy-preferred providers are available but `available`
+ *     is non-empty, fall back to the globally cheapest model for that tier.
+ *  4. If `available` is empty, throw — there is nothing to route to.
+ *
+ * @param tier      - The orchestration tier to route.
+ * @param available - Provider IDs that are currently reachable.
+ * @param policy    - Active routing policy (from `DEFAULT_POLICY` or overrides).
+ */
+export declare function route(tier: Tier, available: ProviderId[], policy: Policy): RouteDecision;

package/dist/core/route.js

@@ -0,0 +1,52 @@
+/**
+ * src/core/route.ts — pure cost-aware routing decision.
+ *
+ * Given a tier, the set of currently available provider IDs, and the active
+ * Policy, selects the concrete provider+model that should handle the work.
+ *
+ * No I/O, no time, no randomness. Pricing data is pure reference data imported
+ * from infra/pricing (permitted by the purity guard because pricing.ts itself
+ * imports no fs/path/child_process).
+ */
+import { getCheapestForTier } from '../infra/pricing.js';
+/**
+ * Resolve a {@link RouteDecision} for the given tier.
+ *
+ * Algorithm:
+ *  1. Walk `policy.providerOrderByTier[tier]` in order.
+ *  2. For the first provider that is present in `available`, resolve the
+ *     cheapest model for that provider+tier via `getCheapestForTier`.
+ *  3. If none of the policy-preferred providers are available but `available`
+ *     is non-empty, fall back to the globally cheapest model for that tier.
+ *  4. If `available` is empty, throw — there is nothing to route to.
+ *
+ * @param tier      - The orchestration tier to route.
+ * @param available - Provider IDs that are currently reachable.
+ * @param policy    - Active routing policy (from `DEFAULT_POLICY` or overrides).
+ */
+export function route(tier, available, policy) {
+    if (available.length === 0) {
+        throw new Error(`route: no providers available for tier "${tier}" — start at least one provider`);
+    }
+    const preferredOrder = policy.providerOrderByTier[tier];
+    // Walk the preferred order and pick the first available provider.
+    for (const preferred of preferredOrder) {
+        if (available.includes(preferred)) {
+            const pricing = getCheapestForTier(tier, [preferred]);
+            return {
+                tier,
+                provider: preferred,
+                model: pricing.model,
+            };
+        }
+    }
+    // None of the policy-preferred providers are available; fall back to the
+    // globally cheapest model across all available providers.
+    const fallback = getCheapestForTier(tier, available);
+    return {
+        tier,
+        provider: fallback.provider,
+        model: fallback.model,
+    };
+}
+//# sourceMappingURL=route.js.map

package/dist/core/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/core/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CACnB,IAAU,EACV,SAAuB,EACvB,MAAc;IAEd,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,iCAAiC,CACjF,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAExD,kEAAkE;IAClE,KAAK,MAAM,SAAS,IAAI,cAAc,EAAE,CAAC;QACvC,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;YACtD,OAAO;gBACL,IAAI;gBACJ,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACrD,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,QAAQ,CAAC,QAAsB;QACzC,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * src/core/types.ts — shared types and ports for the orchestration core.
+ *
+ * This is the type hub. The pure core imports only types here (plus the
+ * Provider port). I/O is reached exclusively through the injected port
+ * interfaces below (Clock, SessionWriter, LedgerWriter), which infra
+ * implements — that is what keeps `src/core/` free of fs/child_process while
+ * remaining fully testable with fakes.
+ *
+ * Purity rule (enforced by test/arch/guards.test.ts): core code must obtain all
+ * time, ids, and randomness from the injected `Clock`, never from Date/Math.
+ */
+import type { Provider, ProviderId, SandboxLevel } from '../providers/port.js';
+export type Tier = 'worker' | 'ic' | 'manager';
+export type Risk = 'low' | 'medium' | 'high' | 'critical';
+export interface Classification {
+    readonly tier: Tier;
+    readonly risk: Risk;
+    /** Human-readable reason the classifier chose this tier/risk. */
+    readonly rationale: string;
+}
+/** A concrete routing decision: which provider+model runs a tier. */
+export interface RouteDecision {
+    readonly tier: Tier;
+    readonly provider: ProviderId;
+    readonly model: string;
+}
+/**
+ * Result of assessing a model's output for real, verifiable signals.
+ * `confidence` is null when the model emitted no parseable confidence envelope —
+ * we never fabricate a number (Honesty Contract).
+ */
+export interface Assessment {
+    readonly confidence: number | null;
+    readonly escalate: boolean;
+    readonly reason: string;
+    readonly needsReview: boolean;
+}
+export interface Clock {
+    /** Epoch milliseconds. */
+    now(): number;
+    /** ISO-8601 timestamp string. */
+    isoNow(): string;
+    /** A unique identifier (uuid-like). */
+    uuid(): string;
+    /** A float in [0, 1). */
+    random(): number;
+}
+export interface SessionEntry {
+    readonly timestamp: string;
+    readonly role: 'user' | 'assistant' | 'system';
+    readonly content: string;
+    readonly tier?: Tier;
+    readonly provider?: ProviderId;
+    readonly model?: string;
+    readonly confidence?: number | null;
+    readonly costUsd?: number;
+    readonly durationMs?: number;
+}
+export interface SessionWriter {
+    readonly id: string;
+    append(entry: SessionEntry): Promise<void>;
+}
+export interface LedgerEntry {
+    readonly timestamp: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly tier: Tier;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly usd: number;
+    readonly durationMs: number;
+    readonly success: boolean;
+}
+export interface LedgerWriter {
+    record(entry: LedgerEntry): Promise<void>;
+}
+export interface Policy {
+    /** Hard cap on tier attempts per task (loop/cost guard). */
+    readonly maxAttempts: number;
+    /** Escalate when self-reported confidence is strictly below this, indexed by risk. */
+    readonly escalateBelowConfidence: Record<Risk, number>;
+    /** Ordered provider preference per tier; route() honours availability. */
+    readonly providerOrderByTier: Record<Tier, readonly ProviderId[]>;
+}
+export interface OrchestrateDeps {
+    /** Available providers, keyed by id. Absent key = provider unavailable. */
+    readonly providers: Partial<Record<ProviderId, Provider>>;
+    readonly clock: Clock;
+    readonly session: SessionWriter;
+    readonly ledger: LedgerWriter;
+    readonly policy: Policy;
+    readonly cwd: string;
+    readonly sandbox: SandboxLevel;
+    readonly timeoutMs: number;
+}
+/**
+ * High-level events emitted by orchestrate(). The interface/render layer
+ * consumes these; every field is a real measurement (no fabricated values).
+ */
+export type CoreEvent = {
+    readonly type: 'classified';
+    readonly classification: Classification;
+} | {
+    readonly type: 'tier-start';
+    readonly tier: Tier;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly attempt: number;
+} | {
+    readonly type: 'provider-event';
+    readonly tier: Tier;
+    readonly event: import('../providers/port.js').ProviderEvent;
+} | {
+    readonly type: 'tier-done';
+    readonly tier: Tier;
+    readonly success: boolean;
+    readonly confidence: number | null;
+    readonly costUsd: number;
+    readonly durationMs: number;
+} | {
+    readonly type: 'escalate';
+    readonly from: Tier;
+    readonly to: Tier;
+    readonly reason: string;
+} | {
+    readonly type: 'notice';
+    readonly level: 'info' | 'warn' | 'error';
+    readonly message: string;
+} | {
+    readonly type: 'final';
+    readonly success: boolean;
+    readonly output: string;
+    readonly tier: Tier;
+    readonly totalCostUsd: number;
+    readonly sessionId: string;
+    readonly attempts: number;
+};

package/dist/core/types.js

@@ -0,0 +1,14 @@
+/**
+ * src/core/types.ts — shared types and ports for the orchestration core.
+ *
+ * This is the type hub. The pure core imports only types here (plus the
+ * Provider port). I/O is reached exclusively through the injected port
+ * interfaces below (Clock, SessionWriter, LedgerWriter), which infra
+ * implements — that is what keeps `src/core/` free of fs/child_process while
+ * remaining fully testable with fakes.
+ *
+ * Purity rule (enforced by test/arch/guards.test.ts): core code must obtain all
+ * time, ids, and randomness from the injected `Clock`, never from Date/Math.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/infra/atomic.d.ts

@@ -0,0 +1,53 @@
+/**
+ * atomic.ts — Atomic file operations for safe concurrent access
+ * Ported from myshell-tools/src/state/atomic.mjs with the following fixes:
+ *   - Full TypeScript strict typing
+ *   - Async (fs/promises) throughout
+ *   - Async backoff instead of CPU-spinning lock acquisition
+ *   - O(1) JSONL append via fs.appendFile (no read-then-rewrite)
+ */
+export interface LockOptions {
+    /** How long to keep trying before giving up (default: 5 000 ms) */
+    timeoutMs?: number;
+    /** Age at which an existing lock is considered stale and may be stolen (default: 10 000 ms) */
+    staleMs?: number;
+}
+export declare class LockTimeoutError extends Error {
+    constructor(lockPath: string, timeoutMs: number);
+}
+export declare class AtomicWriteError extends Error {
+    constructor(filePath: string, cause: unknown);
+}
+/**
+ * Acquire a `.lock` file using `O_EXCL` for atomic creation.
+ * Retries with exponential backoff until `timeoutMs` is reached.
+ * Steals locks whose mtime is older than `staleMs`.
+ *
+ * Throws `LockTimeoutError` if the lock cannot be acquired in time.
+ */
+export declare function acquireLock(lockPath: string, opts?: LockOptions): Promise<void>;
+/**
+ * Release a lock file previously acquired with `acquireLock`.
+ * Silently ignores a missing lock file (idempotent).
+ */
+export declare function releaseLock(lockPath: string): Promise<void>;
+/**
+ * Convenience wrapper: acquire the lock, run `fn`, then always release.
+ * Re-throws any error from `fn` after releasing the lock.
+ */
+export declare function withLock<T>(lockPath: string, fn: () => Promise<T>, opts?: LockOptions): Promise<T>;
+/**
+ * Atomically write `data` to `filePath` using a tmp-file + rename strategy.
+ * The tmp file lives in the same directory to avoid cross-device rename issues.
+ */
+export declare function atomicWrite(filePath: string, data: string): Promise<void>;
+/**
+ * Atomically append a single JSONL entry to `filePath`.
+ *
+ * This is O(1) — it uses `fs.appendFile` rather than reading the entire file
+ * and rewriting it on every call. The caller is responsible for holding a lock
+ * when concurrent appends must be strictly ordered.
+ *
+ * Creates `filePath` if it does not exist.
+ */
+export declare function atomicAppendJSONL(filePath: string, entry: unknown): Promise<void>;

package/dist/infra/atomic.js

@@ -0,0 +1,171 @@
+/**
+ * atomic.ts — Atomic file operations for safe concurrent access
+ * Ported from myshell-tools/src/state/atomic.mjs with the following fixes:
+ *   - Full TypeScript strict typing
+ *   - Async (fs/promises) throughout
+ *   - Async backoff instead of CPU-spinning lock acquisition
+ *   - O(1) JSONL append via fs.appendFile (no read-then-rewrite)
+ */
+import { open, rename, unlink, stat, appendFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+export class LockTimeoutError extends Error {
+    constructor(lockPath, timeoutMs) {
+        super(`Lock acquisition timed out after ${timeoutMs}ms for: ${lockPath}`);
+        this.name = 'LockTimeoutError';
+    }
+}
+export class AtomicWriteError extends Error {
+    constructor(filePath, cause) {
+        super(`Atomic write failed for: ${filePath} — ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = 'AtomicWriteError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_STALE_MS = 10_000;
+/** Async sleep. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Unique suffix so concurrent processes never collide on the tmp file. */
+function tmpSuffix() {
+    return `${process.pid}.${randomBytes(4).toString('hex')}`;
+}
+// ---------------------------------------------------------------------------
+// Lock primitives
+// ---------------------------------------------------------------------------
+/**
+ * Acquire a `.lock` file using `O_EXCL` for atomic creation.
+ * Retries with exponential backoff until `timeoutMs` is reached.
+ * Steals locks whose mtime is older than `staleMs`.
+ *
+ * Throws `LockTimeoutError` if the lock cannot be acquired in time.
+ */
+export async function acquireLock(lockPath, opts) {
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const staleMs = opts?.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    while (Date.now() < deadline) {
+        try {
+            // O_EXCL guarantees atomic creation — only one caller wins
+            const fh = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+            try {
+                await fh.writeFile(JSON.stringify({ pid: process.pid, ts: Date.now() }));
+            }
+            finally {
+                await fh.close();
+            }
+            return; // lock acquired
+        }
+        catch (err) {
+            const nodeErr = err;
+            if (nodeErr.code !== 'EEXIST')
+                throw err;
+            // Check whether the existing lock is stale
+            try {
+                const st = await stat(lockPath);
+                if (Date.now() - st.mtimeMs > staleMs) {
+                    // Stale — the holding process likely crashed; steal it
+                    try {
+                        await unlink(lockPath);
+                    }
+                    catch {
+                        // Another process may have already removed it; harmless
+                    }
+                    continue; // retry immediately
+                }
+            }
+            catch {
+                // Lock file disappeared between the EEXIST and stat — retry
+                continue;
+            }
+            // Back off before the next attempt (50 ms, 100 ms, 200 ms … up to 1 s)
+            const waitMs = Math.min(50 * 2 ** attempt, 1_000);
+            attempt++;
+            // Don't sleep past the deadline
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            await sleep(Math.min(waitMs, remaining));
+        }
+    }
+    throw new LockTimeoutError(lockPath, timeoutMs);
+}
+/**
+ * Release a lock file previously acquired with `acquireLock`.
+ * Silently ignores a missing lock file (idempotent).
+ */
+export async function releaseLock(lockPath) {
+    try {
+        await unlink(lockPath);
+    }
+    catch {
+        // Already gone — that's fine
+    }
+}
+/**
+ * Convenience wrapper: acquire the lock, run `fn`, then always release.
+ * Re-throws any error from `fn` after releasing the lock.
+ */
+export async function withLock(lockPath, fn, opts) {
+    await acquireLock(lockPath, opts);
+    try {
+        return await fn();
+    }
+    finally {
+        await releaseLock(lockPath);
+    }
+}
+// ---------------------------------------------------------------------------
+// Atomic file operations
+// ---------------------------------------------------------------------------
+/**
+ * Atomically write `data` to `filePath` using a tmp-file + rename strategy.
+ * The tmp file lives in the same directory to avoid cross-device rename issues.
+ */
+export async function atomicWrite(filePath, data) {
+    const tmp = `${filePath}.tmp.${tmpSuffix()}`;
+    try {
+        const fh = await open(tmp, 'w');
+        try {
+            await fh.writeFile(data);
+        }
+        finally {
+            await fh.close();
+        }
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of orphaned tmp file
+        try {
+            await unlink(tmp);
+        }
+        catch {
+            /* ignore */
+        }
+        throw new AtomicWriteError(filePath, err);
+    }
+}
+/**
+ * Atomically append a single JSONL entry to `filePath`.
+ *
+ * This is O(1) — it uses `fs.appendFile` rather than reading the entire file
+ * and rewriting it on every call. The caller is responsible for holding a lock
+ * when concurrent appends must be strictly ordered.
+ *
+ * Creates `filePath` if it does not exist.
+ */
+export async function atomicAppendJSONL(filePath, entry) {
+    const line = JSON.stringify(entry) + '\n';
+    try {
+        await appendFile(filePath, line, 'utf8');
+    }
+    catch (err) {
+        throw new AtomicWriteError(filePath, err);
+    }
+}
+//# sourceMappingURL=atomic.js.map