kankaku 0.4.6 → 0.5.0

package/src/adapters/subagent-startup.ts

@@ -0,0 +1,66 @@
+import { findAncestorEntry } from "../domain/ancestry-match.ts";
+import type { ProcessRegistry, RegistryEntry } from "../ports/process-registry.ts";
+import { ownStartIdFromUptime, snapshotAncestry, walkAncestry } from "./ancestry.ts";
+import type { AncestrySnapshot } from "./ancestry.ts";
+
+export interface SubagentStartupDeps {
+  registry: ProcessRegistry;
+  /** This process's own OS parent pid (`process.ppid`). */
+  ppid: number;
+  /** `Date.now`, injected. */
+  now: () => number;
+  /** `process.uptime`, injected. */
+  uptimeSeconds: () => number;
+  /** Injectable for tests; defaults to the real {@link snapshotAncestry}. */
+  snapshotAncestry?: () => AncestrySnapshot;
+}
+
+export interface SubagentStartupResult {
+  /** Every other kankaku process's registry entry visible at startup (this process has not written its own yet). */
+  registryEntries: RegistryEntry[];
+  /** The nearest verified tracked ancestor, if any — see `domain/ancestry-match.ts#findAncestorEntry`. */
+  ancestorEntry: RegistryEntry | undefined;
+  /** This process's own approximate OS start-time identity, derived with no subprocess spawn (F5). */
+  ownProcessStartId: number;
+  /**
+   * Live start-identity lookup from the same ancestry snapshot taken above
+   * (or, when no snapshot was needed — F5 — a function that always reports
+   * "unknown", the same fail-safe default `RegistrySweepDeps.liveStartId`
+   * itself documents). Reused by the caller's own `registry.record()` sweep
+   * so registering this process's entry never pays for a *second* snapshot.
+   */
+  liveStartId: (pid: number) => number | undefined;
+}
+
+/**
+ * Compose this process's ancestor-registry lookup at startup (F5: cheap in
+ * the common case, never on a hot path after this). Reads the machine-wide
+ * registry first — `registry.readAll()` never throws by its own port
+ * contract, so nothing here defensively re-wraps it — and takes the one OS
+ * ancestor-chain snapshot (a `ps` spawn or `/proc` scan) **only** when at
+ * least one other entry exists that could possibly be an ancestor; when the
+ * registry is empty, there is nothing an ancestor-chain walk could ever
+ * find, so the snapshot is skipped entirely rather than paying its cost for
+ * a result that would be `undefined` either way. This is the only place
+ * `extension.ts` needs to call to learn "who (if anyone) is my tracked
+ * ancestor, and what is my own start identity" — see also F1's write
+ * routing (`domain/ancestry-match.ts#resolveOrchestratorRef`, which
+ * consumes `ancestorEntry`) and F2/F3's role/interactivity decisions
+ * (`config.ts#detectRole`, which consume `ancestorEntry !== undefined`).
+ */
+export function resolveSubagentStartup(deps: SubagentStartupDeps): SubagentStartupResult {
+  const registryEntries = deps.registry.readAll();
+  const ownProcessStartId = ownStartIdFromUptime(deps.now(), deps.uptimeSeconds());
+
+  if (registryEntries.length === 0) {
+    return { registryEntries, ancestorEntry: undefined, ownProcessStartId, liveStartId: () => undefined };
+  }
+
+  const takeSnapshot = deps.snapshotAncestry ?? snapshotAncestry;
+  const snapshot = takeSnapshot();
+  const ancestorPids = walkAncestry(deps.ppid, snapshot.ppidByPid);
+  const liveStartId = (pid: number): number | undefined => snapshot.startIdByPid.get(pid);
+  const ancestorEntry = findAncestorEntry(ancestorPids, registryEntries, liveStartId);
+
+  return { registryEntries, ancestorEntry, ownProcessStartId, liveStartId };
+}

package/src/adapters/sync-runner.ts

@@ -0,0 +1,301 @@
+/**
+ * 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) {
+    const peek = 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 = deps.stateStore.read();
+      return { ...emptySummary(deps.clock.now() - startedAt, state?.syncedThrough), locked: true };
+    }
+
+    const state = deps.stateStore.read();
+    // 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, state?.syncedThrough);
+      summary.skipped = plan.unchangedCount;
+      summary.error = message;
+      persistError(deps, state, 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 = state?.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 (chronologically sorted) results is
+        // considered resolved, so syncedThrough does not advance past it.
+        stopError = result.outcome.reason;
+        break;
+      }
+    }
+
+    const mergedHashes = { ...(state?.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();
+  }
+}
+
+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, for `/kankaku sync status` — computed locally, no network. */
+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;
+}
+
+/**
+ * `/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,
+): { state: ReturnType<SyncStateStore["read"]>; pending: number; staleOutsideWindow: number } {
+  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";
+  }
+}

package/src/adapters/target-picker.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Client, Project, WorkTarget } from "../domain/work-target.ts";
+
+const SKIP_OPTION = "— skip —";
+const NO_PROJECT_OPTION = "(no project)";
+
+export interface PickerCatalog {
+  clients: Client[];
+  projects: Project[];
+}
+
+export type PickResult = { kind: "picked"; target: WorkTarget } | { kind: "skipped" };
+
+interface LabeledOption<T> {
+  label: string;
+  item: T;
+}
+
+/**
+ * Build `label -> item` options, sorted by name. When two items share the
+ * same name, disambiguate every colliding label by appending ` (code)` so
+ * every option maps back to exactly one id.
+ */
+function labelOptions<T extends { name: string; code?: string }>(items: T[]): LabeledOption<T>[] {
+  const sorted = [...items].sort((a, b) => a.name.localeCompare(b.name));
+  const nameCounts = new Map<string, number>();
+  for (const item of sorted) {
+    nameCounts.set(item.name, (nameCounts.get(item.name) ?? 0) + 1);
+  }
+
+  return sorted.map((item) => {
+    const collides = (nameCounts.get(item.name) ?? 0) > 1;
+    const label = collides && item.code ? `${item.name} (${item.code})` : item.name;
+    return { label, item };
+  });
+}
+
+/**
+ * Run the client/project picker (`ctx.ui.select`) against an already-loaded
+ * catalog snapshot. Pure UI interaction: no network, no persistence — the
+ * caller (`session-target.ts`) decides what to do with the result.
+ *
+ * Declining at either step — choosing "— skip —" or dismissing the dialog
+ * (`undefined`) — cancels the whole pick, not just that step.
+ */
+export async function pickTarget(ctx: ExtensionContext, catalog: PickerCatalog): Promise<PickResult> {
+  const pickableClients = catalog.clients.filter((client) => client.active && !client.unassigned);
+  const clientOptions = labelOptions(pickableClients);
+
+  const clientChoice = await ctx.ui.select("kankaku — client", [...clientOptions.map((option) => option.label), SKIP_OPTION]);
+  if (clientChoice === undefined || clientChoice === SKIP_OPTION) return { kind: "skipped" };
+
+  const client = clientOptions.find((option) => option.label === clientChoice)?.item;
+  if (!client) return { kind: "skipped" };
+
+  const pickableProjects = catalog.projects.filter((project) => project.active && project.clientId === client.id);
+  const projectOptions = labelOptions(pickableProjects);
+
+  const projectChoice = await ctx.ui.select("kankaku — project", [
+    ...projectOptions.map((option) => option.label),
+    NO_PROJECT_OPTION,
+    SKIP_OPTION,
+  ]);
+  if (projectChoice === undefined || projectChoice === SKIP_OPTION) return { kind: "skipped" };
+
+  const project = projectChoice === NO_PROJECT_OPTION ? undefined : projectOptions.find((option) => option.label === projectChoice)?.item;
+
+  const target: WorkTarget = {
+    clientId: client.id,
+    clientCode: client.code,
+    clientName: client.name,
+    ...(project !== undefined
+      ? {
+          projectId: project.id,
+          ...(project.code !== undefined ? { projectCode: project.code } : {}),
+          projectName: project.name,
+        }
+      : {}),
+  };
+
+  return { kind: "picked", target };
+}