kankaku-pi 1.0.0

package/src/adapters/sync-runner.ts

@@ -0,0 +1,340 @@
+/**
+ * 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.ts";
+import { computeTaskContentHash, planSync, pruneHashes } from "../domain/sync-plan.ts";
+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;
+}
+
+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: string | undefined, b: string): string {
+  if (a === undefined) return b;
+  return Date.parse(b) > Date.parse(a) ? b : a;
+}
+
+function emptySummary(durationMs: number, syncedThrough: string | undefined): SyncSummary {
+  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: SyncState | undefined, trigger: SyncTrigger, now: number, minIntervalMs: number): boolean {
+  if (trigger !== "agent_settled") return false;
+  if (minIntervalMs <= 0) return false;
+  const lastRunAt = state?.lastRunAt;
+  if (!Number.isFinite(lastRunAt)) return false;
+  if (now - (lastRunAt as number) >= 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: SyncRunnerDeps, options: { full?: boolean; trigger?: SyncTrigger } = {}): Promise<SyncSummary> {
+  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: Awaited<ReturnType<WorkSink["push"]>>;
+    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<string, string>();
+    const failed: Array<{ id: string; reason: string }> = [];
+    const unassigned = new Map<string, number>();
+    let uploaded = 0;
+    let updated = 0;
+    let syncedThrough = priorState?.syncedThrough;
+    let stopError: string | undefined;
+    // 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: SyncRunnerDeps, state: ReturnType<SyncStateStore["read"]>): ReturnType<SyncStateStore["read"]> {
+  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: SyncRunnerDeps, state: ReturnType<SyncStateStore["read"]>, message: string, logVersionAtRead: string | number | undefined): void {
+  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: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number {
+  const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
+  return plan.toSync.length + plan.correctionsDeferred;
+}
+
+/**
+ * {@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 function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): SyncStatusSnapshot {
+  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<Args extends unknown[], T>(fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T> {
+  let inFlight: Promise<T> | undefined;
+  return (...args: Args): Promise<T> => {
+    if (!inFlight) {
+      inFlight = fn(...args).finally(() => {
+        inFlight = undefined;
+      });
+    }
+    return inFlight;
+  };
+}

package/src/adapters/sync-state-store.ts

@@ -0,0 +1,227 @@
+/**
+ * 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";
+import type { SyncState } from "../domain/sync-plan.ts";
+
+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;
+
+interface LockFile {
+  pid: number;
+  at: number;
+}
+
+/** 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;
+}
+
+const defaultFsOps: SyncStateStoreFsOps = { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, openSync, closeSync };
+
+function isEnoent(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "ENOENT";
+}
+
+function isEexist(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "EEXIST";
+}
+
+function isSyncState(value: unknown): value is SyncState {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["target"] === "string" &&
+    typeof record["hashes"] === "object" &&
+    record["hashes"] !== null &&
+    (record["syncedThrough"] === undefined || typeof record["syncedThrough"] === "string")
+  );
+}
+
+function isLockFile(value: unknown): value is LockFile {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return typeof record["pid"] === "number" && typeof record["at"] === "number";
+}
+
+function atomicWrite(filePath: string, content: string): void {
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, filePath);
+}
+
+function safeUnlink(fs: Pick<SyncStateStoreFsOps, "unlinkSync">, filePath: string): void {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // Best effort: already removed, or never existed.
+  }
+}
+
+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 class SyncStateStore {
+  private readonly deps: Required<SyncStateStoreDeps>;
+
+  constructor(deps: SyncStateStoreDeps) {
+    this.deps = {
+      dir: deps.dir,
+      pid: deps.pid,
+      isAlive: deps.isAlive ?? defaultIsAlive,
+      now: deps.now ?? (() => Date.now()),
+      fs: deps.fs ?? defaultFsOps,
+    };
+  }
+
+  private get statePath(): string {
+    return join(this.deps.dir, STATE_FILE_NAME);
+  }
+
+  private get lockPath(): string {
+    return join(this.deps.dir, LOCK_FILE_NAME);
+  }
+
+  read(): SyncState | undefined {
+    try {
+      if (!existsSync(this.statePath)) return undefined;
+      const parsed: unknown = JSON.parse(readFileSync(this.statePath, "utf8"));
+      return isSyncState(parsed) ? parsed : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  write(state: SyncState): void {
+    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(): boolean {
+    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). */
+  private acquireFresh(): boolean {
+    let fd: number;
+    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(): void {
+    const existing = this.readLock();
+    if (existing && existing.pid === this.deps.pid) {
+      safeUnlink(this.deps.fs, this.lockPath);
+    }
+  }
+
+  private readLock(): LockFile | undefined {
+    try {
+      if (!this.deps.fs.existsSync(this.lockPath)) return undefined;
+      const parsed: unknown = 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: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}