kankaku-pi 1.0.0

package/dist/adapters/sync-runner.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Orchestrates one sync run: read every record, build tasks (never
+ * re-implementing the aggregation — `buildTasks` is the only place it
+ * lives), plan what needs pushing, push it, and persist the new state.
+ * Never throws to its caller: every failure mode is folded into the
+ * returned {@link SyncSummary}.
+ */
+import type { SyncState } from "../domain/sync-plan.ts";
+import type { TaskView } from "../domain/task-view.ts";
+import type { Clock } from "../ports/clock.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import type { WorkSink } from "../ports/work-sink.ts";
+import type { SyncStateStore } from "./sync-state-store.ts";
+export interface SyncSummary {
+    uploaded: number;
+    updated: number;
+    skipped: number;
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Count of tasks routed to the unassigned client this run, grouped by their historical free-text label. */
+    unassigned: Record<string, number>;
+    syncedThrough: string | undefined;
+    durationMs: number;
+    /** Set when a network/timeout/5xx/auth failure stopped the run before every candidate task was attempted. */
+    error?: string;
+    /** `true` when another sync already holds the lock; nothing was attempted this run. */
+    locked?: boolean;
+}
+/**
+ * Which automatic trigger asked for this run, or `undefined` for a manual
+ * one (`/kankaku sync`, `sync all`, `backfill`) — see `runSync`'s
+ * short-circuit and throttle, which apply only to the automatic path.
+ * `session_shutdown` (pi awaits this handler — see `adapters/pi-tracker.ts`)
+ * is, like `session_start`, never throttled: only `agent_settled` is.
+ */
+export type SyncTrigger = "session_start" | "agent_settled" | "session_shutdown";
+export interface SyncRunnerDeps {
+    log: WorkLog;
+    sink: WorkSink;
+    stateStore: SyncStateStore;
+    clock: Clock;
+    /** The configured hub URL — a state file synced against a different one triggers a full sync. */
+    target: string;
+    windowHours?: number;
+    /**
+     * `KANKAKU_SYNC_MIN_INTERVAL_MINUTES`, already converted to ms. Only
+     * applies to the automatic path (`options.trigger` set). Defaults to 5
+     * minutes; `0` disables throttling.
+     */
+    minAutoIntervalMs?: number;
+}
+/**
+ * Run one sync pass. Acquires the cross-process lock for the whole run
+ * (never held across `await` boundaries outside this function) so two pi
+ * processes never race on the same `sync-state.json`.
+ *
+ * When `options.trigger` is set (the automatic `session_start`/
+ * `agent_settled`/`session_shutdown` path, as opposed to a manual
+ * `/kankaku sync`), two cheap gates run before any `WorkLog.readAll()` or
+ * network call: (a) if the log's `version()` is unchanged since the last
+ * successful sync and that sync did not error, skip entirely, for every
+ * trigger; otherwise (b) throttle to at most one real attempt per
+ * `minAutoIntervalMs`, but only for `agent_settled` — fired once per
+ * prompt, so `version()` almost always differs right after it appended a
+ * record. `session_start` and `session_shutdown` never throttle (see
+ * `isThrottled`). Neither gate ever applies to a manual sync.
+ */
+export declare function runSync(deps: SyncRunnerDeps, options?: {
+    full?: boolean;
+    trigger?: SyncTrigger;
+}): Promise<SyncSummary>;
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku-pi/hub` surface. It will be removed in the next minor.
+ */
+export declare function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number;
+/**
+ * {@link computeSyncStatus}'s return shape, exported so a caller (e.g.
+ * `hub-actions.ts#buildSyncStatusLines`, or a future standalone TUI reusing
+ * `kankaku-pi/hub`) can depend on this type without importing anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+export interface SyncStatusSnapshot {
+    state: SyncState | undefined;
+    pending: number;
+    staleOutsideWindow: number;
+}
+/**
+ * `/kankaku sync status`: the persisted state, a locally-computed pending
+ * count, and (R3) how many tasks changed since their last sync but fall
+ * outside this run's revisit window — a `sync all` needed to pick them up
+ * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
+ * (PocketBase)" > "Sync" > "Limitations"). No network.
+ */
+export declare function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): SyncStatusSnapshot;
+/**
+ * Wrap an async function so concurrent callers share one in-flight call
+ * instead of starting a new one each — kankaku's single-flight guard for
+ * sync: `/kankaku sync`, the `session_start` auto-sync and the
+ * `agent_settled` auto-sync all go through the same wrapped function, so
+ * only one sync is ever running at a time within this process. (The
+ * cross-process case is covered separately by `SyncStateStore`'s lock
+ * file.) A caller that arrives while one is in flight joins its result
+ * rather than queuing a fresh run — the next trigger (the next
+ * `session_start` or `agent_settled`) will pick up anything missed, since
+ * every sync also revisits the trailing window.
+ */
+export declare function singleFlight<Args extends unknown[], T>(fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T>;

package/dist/adapters/sync-runner.js

@@ -0,0 +1,273 @@
+/**
+ * Orchestrates one sync run: read every record, build tasks (never
+ * re-implementing the aggregation — `buildTasks` is the only place it
+ * lives), plan what needs pushing, push it, and persist the new state.
+ * Never throws to its caller: every failure mode is folded into the
+ * returned {@link SyncSummary}.
+ */
+import { buildTasks } from "../domain/task-view.js";
+import { computeTaskContentHash, planSync, pruneHashes } from "../domain/sync-plan.js";
+const NO_LABEL = "(no label)";
+const DEFAULT_MIN_AUTO_INTERVAL_MS = 5 * 60 * 1000;
+/** The later of two ISO timestamps, treating `undefined` as earlier than anything. */
+function laterIso(a, b) {
+    if (a === undefined)
+        return b;
+    return Date.parse(b) > Date.parse(a) ? b : a;
+}
+function emptySummary(durationMs, syncedThrough) {
+    return { uploaded: 0, updated: 0, skipped: 0, failed: [], unassigned: {}, syncedThrough, durationMs };
+}
+/**
+ * Whether the automatic path's throttle should block this run right now.
+ * Only `agent_settled` — fired once per prompt, far more often than a
+ * session starts or ends — is ever throttled; `session_start` and
+ * `session_shutdown` always bypass it (a session boundary is a good time
+ * to catch up regardless of how recently the last automatic run happened,
+ * and the shutdown one is awaited and time-bounded on its own — see
+ * `adapters/pi-tracker.ts`). `undefined`/non-finite `lastRunAt` (never
+ * run, or a malformed on-disk value) never throttles either — there is
+ * nothing to measure the interval against.
+ */
+function isThrottled(state, trigger, now, minIntervalMs) {
+    if (trigger !== "agent_settled")
+        return false;
+    if (minIntervalMs <= 0)
+        return false;
+    const lastRunAt = state?.lastRunAt;
+    if (!Number.isFinite(lastRunAt))
+        return false;
+    if (now - lastRunAt >= minIntervalMs)
+        return false;
+    return true;
+}
+/**
+ * Run one sync pass. Acquires the cross-process lock for the whole run
+ * (never held across `await` boundaries outside this function) so two pi
+ * processes never race on the same `sync-state.json`.
+ *
+ * When `options.trigger` is set (the automatic `session_start`/
+ * `agent_settled`/`session_shutdown` path, as opposed to a manual
+ * `/kankaku sync`), two cheap gates run before any `WorkLog.readAll()` or
+ * network call: (a) if the log's `version()` is unchanged since the last
+ * successful sync and that sync did not error, skip entirely, for every
+ * trigger; otherwise (b) throttle to at most one real attempt per
+ * `minAutoIntervalMs`, but only for `agent_settled` — fired once per
+ * prompt, so `version()` almost always differs right after it appended a
+ * record. `session_start` and `session_shutdown` never throttle (see
+ * `isThrottled`). Neither gate ever applies to a manual sync.
+ */
+export async function runSync(deps, options = {}) {
+    const startedAt = deps.clock.now();
+    if (options.trigger !== undefined) {
+        // Gated like every other read below: a state written for another hub
+        // says nothing about THIS hub, so neither its `logVersion` (which
+        // would otherwise skip the new hub's very first run until the next
+        // record is appended) nor its `lastRunAt` throttle may apply.
+        const peek = stateForTarget(deps, deps.stateStore.read());
+        const currentVersion = deps.log.version?.();
+        const versionUnchanged = currentVersion !== undefined && peek?.logVersion === currentVersion;
+        if (versionUnchanged && peek?.lastError === undefined) {
+            return emptySummary(deps.clock.now() - startedAt, peek?.syncedThrough);
+        }
+        const minIntervalMs = deps.minAutoIntervalMs ?? DEFAULT_MIN_AUTO_INTERVAL_MS;
+        if (isThrottled(peek, options.trigger, deps.clock.now(), minIntervalMs)) {
+            return emptySummary(deps.clock.now() - startedAt, peek?.syncedThrough);
+        }
+    }
+    let lockAcquired = false;
+    try {
+        lockAcquired = deps.stateStore.tryLock();
+        if (!lockAcquired) {
+            const state = stateForTarget(deps, deps.stateStore.read());
+            return { ...emptySummary(deps.clock.now() - startedAt, state?.syncedThrough), locked: true };
+        }
+        const state = deps.stateStore.read();
+        // A state from another hub is ignored wholesale, on EVERY path below
+        // (the summary, the error path, and the successful merge): its
+        // watermark and its hashes describe rows the configured hub does not
+        // have (mirrors `domain/sync-plan.ts#planSync`'s gate). `planSync`
+        // still receives the raw `state`, since it applies that same gate
+        // itself and its `target` comparison is what makes the run a full one.
+        const priorState = stateForTarget(deps, state);
+        // Captured once, here, and persisted as-is below: this is the version
+        // the tasks below were actually built from, not whatever the log might
+        // become by the time an awaited push finishes.
+        const logVersionAtRead = deps.log.version?.();
+        const tasks = buildTasks(deps.log.readAll());
+        const plan = planSync(tasks, state, { target: deps.target, ...(deps.windowHours !== undefined ? { windowHours: deps.windowHours } : {}), ...(options.full !== undefined ? { full: options.full } : {}) });
+        let results;
+        try {
+            results = await deps.sink.push(plan.toSync);
+        }
+        catch (error) {
+            // WorkSink implementations are expected never to throw, but this
+            // runner must hold that guarantee even if one does.
+            const message = error instanceof Error ? error.message : String(error);
+            const summary = emptySummary(deps.clock.now() - startedAt, priorState?.syncedThrough);
+            summary.skipped = plan.unchangedCount;
+            summary.error = message;
+            // `priorState`, never `state`: a throwing sink on the first run
+            // against a NEW hub must not carry the old hub's hashes and
+            // watermark over under the new target, or the next run would
+            // skip every task as "unchanged" (the exact bug 0.8.1 fixed on the
+            // successful path).
+            persistError(deps, priorState, message, logVersionAtRead);
+            return summary;
+        }
+        const byId = new Map(plan.toSync.map((task) => [task.id, task]));
+        // Both are keyed by content that ultimately traces back to free-text
+        // worklog/legacy-client data (task ids, legacy client labels): built in
+        // a `Map` and emitted via `Object.fromEntries` below (never
+        // `newHashes[task.id] = ...` on a plain object), so a value like
+        // `__proto__` or `constructor` becomes a normal own entry instead of
+        // silently colliding with an inherited `Object.prototype` property.
+        const newHashes = new Map();
+        const failed = [];
+        const unassigned = new Map();
+        let uploaded = 0;
+        let updated = 0;
+        let syncedThrough = priorState?.syncedThrough;
+        let stopError;
+        // Whether at least one task was actually resolved (pushed or recorded
+        // as failed) this run — as opposed to the run stopping on its very
+        // first attempt. Guards `target` below: a run against a new/unreachable
+        // target that resolves nothing must not overwrite the state's `target`,
+        // or a later sync against the *real* target would wrongly see it as
+        // unchanged and skip the full re-evaluation it needs.
+        let progressed = false;
+        for (const result of results) {
+            const task = byId.get(result.taskId);
+            if (!task)
+                continue; // defensive: a WorkSink implementation misbehaving should not crash the runner.
+            if (result.outcome.kind === "created" || result.outcome.kind === "updated") {
+                if (result.outcome.kind === "created")
+                    uploaded += 1;
+                else
+                    updated += 1;
+                newHashes.set(task.id, computeTaskContentHash(task));
+                syncedThrough = laterIso(syncedThrough, task.endedAt);
+                progressed = true;
+                if (result.outcome.unassigned) {
+                    const label = result.outcome.legacyLabel || NO_LABEL;
+                    unassigned.set(label, (unassigned.get(label) ?? 0) + 1);
+                }
+            }
+            else if (result.outcome.kind === "failed") {
+                // Recorded and skipped, not retried forever: stamp its hash too so
+                // an unchanged, permanently-invalid task is not resent every run.
+                failed.push({ id: task.id, reason: result.outcome.reason });
+                newHashes.set(task.id, computeTaskContentHash(task));
+                syncedThrough = laterIso(syncedThrough, task.endedAt);
+                progressed = true;
+            }
+            else {
+                // "error": a network/timeout/5xx/auth failure. Stop here — nothing
+                // after this point in the results is considered resolved. The
+                // results follow `plan.toSync`'s order (new work oldest-first,
+                // then corrections newest-first), and `syncedThrough` is a max
+                // over what WAS resolved, so stopping early can only leave it
+                // lower, never advance it past an unresolved task.
+                stopError = result.outcome.reason;
+                break;
+            }
+        }
+        const mergedHashes = { ...(priorState?.hashes ?? {}), ...Object.fromEntries(newHashes) };
+        // G2: no longer window-bound — see `domain/sync-plan.ts#pruneHashes`'s
+        // doc comment. `tasks` here is every task `buildTasks` currently knows
+        // about (the full `readAll()`, not just this run's eligible/window
+        // subset), so a hash is only ever dropped for a task id that has
+        // genuinely vanished, never merely because it is old.
+        const prunedHashes = pruneHashes(mergedHashes, tasks);
+        // Only adopt deps.target as the persisted target once this run has
+        // actually resolved something against it; otherwise keep whatever
+        // target (if any) the previous state was synced against.
+        const persistedTarget = progressed || state === undefined ? deps.target : state.target;
+        deps.stateStore.write({
+            target: persistedTarget,
+            ...(syncedThrough !== undefined ? { syncedThrough } : {}),
+            hashes: prunedHashes,
+            ...(stopError !== undefined ? { lastError: { message: stopError, at: new Date(deps.clock.now()).toISOString() } } : {}),
+            ...(logVersionAtRead !== undefined ? { logVersion: logVersionAtRead } : {}),
+            lastRunAt: deps.clock.now(),
+        });
+        return {
+            uploaded,
+            updated,
+            skipped: plan.unchangedCount,
+            failed,
+            unassigned: Object.fromEntries(unassigned),
+            syncedThrough,
+            durationMs: deps.clock.now() - startedAt,
+            ...(stopError !== undefined ? { error: stopError } : {}),
+        };
+    }
+    finally {
+        if (lockAcquired)
+            deps.stateStore.unlock();
+    }
+}
+/** `state` when it was written against `deps.target`; `undefined` (as if there were no state at all) when it belongs to another hub. */
+function stateForTarget(deps, state) {
+    return state !== undefined && state.target === deps.target ? state : undefined;
+}
+/** Persist a failed run. `state` must already be gated by {@link stateForTarget}: what it carries is re-written under `deps.target`. */
+function persistError(deps, state, message, logVersionAtRead) {
+    deps.stateStore.write({
+        target: deps.target,
+        ...(state?.syncedThrough !== undefined ? { syncedThrough: state.syncedThrough } : {}),
+        hashes: state?.hashes ?? {},
+        lastError: { message, at: new Date(deps.clock.now()).toISOString() },
+        ...(logVersionAtRead !== undefined ? { logVersion: logVersionAtRead } : {}),
+        lastRunAt: deps.clock.now(),
+    });
+}
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku-pi/hub` surface. It will be removed in the next minor.
+ */
+export function pendingCount(tasks, state, target, windowHours) {
+    const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
+    return plan.toSync.length + plan.correctionsDeferred;
+}
+/**
+ * `/kankaku sync status`: the persisted state, a locally-computed pending
+ * count, and (R3) how many tasks changed since their last sync but fall
+ * outside this run's revisit window — a `sync all` needed to pick them up
+ * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
+ * (PocketBase)" > "Sync" > "Limitations"). No network.
+ */
+export function computeSyncStatus(log, stateStore, target, windowHours) {
+    const state = stateStore.read();
+    const tasks = buildTasks(log.readAll());
+    const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
+    // Deferred corrections are pending too: the cap only spreads them over runs.
+    return { state, pending: plan.toSync.length + plan.correctionsDeferred, staleOutsideWindow: plan.staleOutsideWindow.length };
+}
+/**
+ * Wrap an async function so concurrent callers share one in-flight call
+ * instead of starting a new one each — kankaku's single-flight guard for
+ * sync: `/kankaku sync`, the `session_start` auto-sync and the
+ * `agent_settled` auto-sync all go through the same wrapped function, so
+ * only one sync is ever running at a time within this process. (The
+ * cross-process case is covered separately by `SyncStateStore`'s lock
+ * file.) A caller that arrives while one is in flight joins its result
+ * rather than queuing a fresh run — the next trigger (the next
+ * `session_start` or `agent_settled`) will pick up anything missed, since
+ * every sync also revisits the trailing window.
+ */
+export function singleFlight(fn) {
+    let inFlight;
+    return (...args) => {
+        if (!inFlight) {
+            inFlight = fn(...args).finally(() => {
+                inFlight = undefined;
+            });
+        }
+        return inFlight;
+    };
+}

package/dist/adapters/sync-state-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Disk-backed store for `<KANKAKU_DIR>/sync-state.json`, plus a simple
+ * cross-process lock so two pi processes (e.g. an orchestrator's
+ * auto-sync and a manual `/kankaku sync` in another terminal) never sync
+ * the same directory concurrently. Mirrors `file-inflight-store.ts`'s
+ * atomic-write and liveness-probe conventions.
+ */
+import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import type { SyncState } from "../domain/sync-plan.ts";
+/** The subset of `node:fs` the lock's acquire/recover path needs, injectable so tests can simulate cross-process interleaving deterministically. */
+export interface SyncStateStoreFsOps {
+    existsSync: typeof existsSync;
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
+    openSync: typeof openSync;
+    closeSync: typeof closeSync;
+}
+export interface SyncStateStoreDeps {
+    dir: string;
+    pid: number;
+    /** Whether a pid is still alive. Defaults to the same signal-probe used elsewhere. */
+    isAlive?: (pid: number) => boolean;
+    /** Injectable for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable `node:fs` primitives for the lock's acquire/recover path. Defaults to the real ones. */
+    fs?: SyncStateStoreFsOps;
+}
+/**
+ * `read()`/`write()` tolerate a missing or malformed file (return
+ * `undefined` / overwrite, respectively) since this state is disposable —
+ * losing it only costs a full re-evaluation on the next sync, never data.
+ * `tryLock()`/`unlock()` implement a simple pid+timestamp lock file, stale
+ * after {@link STALE_LOCK_MS}.
+ */
+export declare class SyncStateStore {
+    private readonly deps;
+    constructor(deps: SyncStateStoreDeps);
+    private get statePath();
+    private get lockPath();
+    read(): SyncState | undefined;
+    write(state: SyncState): void;
+    /**
+     * Try to acquire the cross-process sync lock. Acquisition itself is
+     * atomic: it always goes through an exclusive create ({@link acquireFresh},
+     * `open` with the `wx` flag), never a read-then-write, so two processes
+     * racing to create the lock file can never both succeed. Returns `true`
+     * (and takes ownership) when there is no lock file, this process already
+     * owns it (re-entrant), or the existing one is stale (its pid is no
+     * longer alive, or it is older than {@link STALE_LOCK_MS}) and this
+     * process wins the race to recover it; `false` when a live, fresh lock is
+     * held by another process, or this process loses a stale-lock recovery
+     * race to another one.
+     */
+    tryLock(): boolean;
+    /** Create the lock file exclusively (`wx`): fails with EEXIST when another lock already exists, never silently overwrites one. Assumes `this.deps.dir` already exists (`tryLock` ensures it once up front). */
+    private acquireFresh;
+    /** Release the lock, but only if this process still owns it (never clobber someone else's fresher lock). */
+    unlock(): void;
+    private readLock;
+}

package/dist/adapters/sync-state-store.js

@@ -0,0 +1,188 @@
+/**
+ * Disk-backed store for `<KANKAKU_DIR>/sync-state.json`, plus a simple
+ * cross-process lock so two pi processes (e.g. an orchestrator's
+ * auto-sync and a manual `/kankaku sync` in another terminal) never sync
+ * the same directory concurrently. Mirrors `file-inflight-store.ts`'s
+ * atomic-write and liveness-probe conventions.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const STATE_FILE_NAME = "sync-state.json";
+const LOCK_FILE_NAME = "sync.lock";
+/** A lock older than this is considered abandoned even if its owning pid still (coincidentally) exists. */
+const STALE_LOCK_MS = 5 * 60 * 1000;
+const defaultFsOps = { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, openSync, closeSync };
+function isEnoent(error) {
+    return error?.code === "ENOENT";
+}
+function isEexist(error) {
+    return error?.code === "EEXIST";
+}
+function isSyncState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record["target"] === "string" &&
+        typeof record["hashes"] === "object" &&
+        record["hashes"] !== null &&
+        (record["syncedThrough"] === undefined || typeof record["syncedThrough"] === "string"));
+}
+function isLockFile(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record["pid"] === "number" && typeof record["at"] === "number";
+}
+function atomicWrite(filePath, content) {
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, filePath);
+}
+function safeUnlink(fs, filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // Best effort: already removed, or never existed.
+    }
+}
+/**
+ * `read()`/`write()` tolerate a missing or malformed file (return
+ * `undefined` / overwrite, respectively) since this state is disposable —
+ * losing it only costs a full re-evaluation on the next sync, never data.
+ * `tryLock()`/`unlock()` implement a simple pid+timestamp lock file, stale
+ * after {@link STALE_LOCK_MS}.
+ */
+export class SyncStateStore {
+    deps;
+    constructor(deps) {
+        this.deps = {
+            dir: deps.dir,
+            pid: deps.pid,
+            isAlive: deps.isAlive ?? defaultIsAlive,
+            now: deps.now ?? (() => Date.now()),
+            fs: deps.fs ?? defaultFsOps,
+        };
+    }
+    get statePath() {
+        return join(this.deps.dir, STATE_FILE_NAME);
+    }
+    get lockPath() {
+        return join(this.deps.dir, LOCK_FILE_NAME);
+    }
+    read() {
+        try {
+            if (!existsSync(this.statePath))
+                return undefined;
+            const parsed = JSON.parse(readFileSync(this.statePath, "utf8"));
+            return isSyncState(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(state) {
+        mkdirSync(this.deps.dir, { recursive: true });
+        atomicWrite(this.statePath, JSON.stringify(state));
+    }
+    /**
+     * Try to acquire the cross-process sync lock. Acquisition itself is
+     * atomic: it always goes through an exclusive create ({@link acquireFresh},
+     * `open` with the `wx` flag), never a read-then-write, so two processes
+     * racing to create the lock file can never both succeed. Returns `true`
+     * (and takes ownership) when there is no lock file, this process already
+     * owns it (re-entrant), or the existing one is stale (its pid is no
+     * longer alive, or it is older than {@link STALE_LOCK_MS}) and this
+     * process wins the race to recover it; `false` when a live, fresh lock is
+     * held by another process, or this process loses a stale-lock recovery
+     * race to another one.
+     */
+    tryLock() {
+        mkdirSync(this.deps.dir, { recursive: true });
+        if (this.acquireFresh())
+            return true;
+        const existing = this.readLock();
+        if (!existing) {
+            // Raced with a release between our failed create and this read; the
+            // slot may be free again now. One more attempt, then give up rather
+            // than looping forever.
+            return this.acquireFresh();
+        }
+        if (existing.pid === this.deps.pid)
+            return true; // re-entrant: we already own it.
+        const age = this.deps.now() - existing.at;
+        const stale = age > STALE_LOCK_MS || !this.deps.isAlive(existing.pid);
+        if (!stale)
+            return false; // live, fresh lock held by someone else.
+        // Stale-lock recovery, made race-safe: rename the stale file to a
+        // unique tombstone name first. `rename` is atomic, so only one racer's
+        // call can succeed; every loser gets ENOENT and backs off instead of
+        // deleting (or overwriting) a lock it never proved was still stale.
+        const tombstone = `${this.lockPath}.stale.${this.deps.pid}.${this.deps.now()}.tmp`;
+        try {
+            this.deps.fs.renameSync(this.lockPath, tombstone);
+        }
+        catch (error) {
+            if (isEnoent(error))
+                return false; // lost the recovery race; back off.
+            throw error;
+        }
+        safeUnlink(this.deps.fs, tombstone);
+        return this.acquireFresh(); // false here means a third racer won it first.
+    }
+    /** Create the lock file exclusively (`wx`): fails with EEXIST when another lock already exists, never silently overwrites one. Assumes `this.deps.dir` already exists (`tryLock` ensures it once up front). */
+    acquireFresh() {
+        let fd;
+        try {
+            fd = this.deps.fs.openSync(this.lockPath, "wx");
+        }
+        catch (error) {
+            if (isEexist(error))
+                return false;
+            throw error;
+        }
+        try {
+            this.deps.fs.writeFileSync(fd, JSON.stringify({ pid: this.deps.pid, at: this.deps.now() }));
+        }
+        catch (error) {
+            try {
+                this.deps.fs.closeSync(fd);
+            }
+            catch {
+                // Best effort: still try to clean up the partially written file below.
+            }
+            safeUnlink(this.deps.fs, this.lockPath);
+            throw error;
+        }
+        this.deps.fs.closeSync(fd);
+        return true;
+    }
+    /** Release the lock, but only if this process still owns it (never clobber someone else's fresher lock). */
+    unlock() {
+        const existing = this.readLock();
+        if (existing && existing.pid === this.deps.pid) {
+            safeUnlink(this.deps.fs, this.lockPath);
+        }
+    }
+    readLock() {
+        try {
+            if (!this.deps.fs.existsSync(this.lockPath))
+                return undefined;
+            const parsed = JSON.parse(this.deps.fs.readFileSync(this.lockPath, "utf8"));
+            return isLockFile(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Default `isAlive`: probe with signal 0 — mirrors `pi-tracker.ts`'s default. */
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}