kankaku-pi 1.0.0

package/src/adapters/kankaku-dir.ts

@@ -0,0 +1,102 @@
+import { mkdirSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/**
+ * Resolve the kankaku data directory: an absolute `dirOrRelative` is used
+ * as-is, a relative one is joined against `cwd`. Shared by every lazy
+ * adapter so the rule lives in exactly one place.
+ */
+export function resolveKankakuDir(dirOrRelative: string, cwd: string): string {
+  return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}
+
+export interface WritableTargetResult {
+  dir: string;
+  /** `true` when `candidateDir` failed its writability probe and `dir` is `fallbackDir` instead. */
+  usedFallback: boolean;
+}
+
+export interface ResolveWritableTargetDeps {
+  /**
+   * Proves this process can actually write to `dir` — not merely that it
+   * exists — and throws on any failure. Injectable for tests (never touch
+   * real disk to simulate an unwritable directory); defaults to
+   * {@link defaultWritabilityProbe}.
+   */
+  probe?: (dir: string) => void;
+}
+
+/** Matches this probe's own marker filename: `.kankaku-write-probe.<pid>.<timestamp>.tmp`. */
+const PROBE_NAME_PATTERN = /^\.kankaku-write-probe\.\d+\.(\d+)\.tmp$/;
+/** A marker older than this is assumed abandoned (its writer was SIGKILLed between the write and its own unlink) — R4. */
+const PROBE_STALE_MS = 60_000;
+
+/**
+ * Best-effort removal of a stale writability-probe marker (R4): a probe
+ * that gets SIGKILLed between its `writeFileSync` and its own `unlinkSync`
+ * leaves `.kankaku-write-probe.<pid>.<timestamp>.tmp` behind forever —
+ * nothing else in `dir` ever looks at it again otherwise. Runs
+ * opportunistically every time the probe itself runs (mirrors
+ * `machine-process-registry.ts`'s own-write-time sweep pattern), so no
+ * separate cleanup process is needed. Only removes a marker whose
+ * filename-embedded timestamp (not the file's mtime, so this stays
+ * deterministic and easy to test) is older than a minute — never a fresh
+ * one, including this call's own marker (written after this sweep runs) or
+ * a concurrent process's own in-flight probe.
+ */
+function sweepStaleWriteProbes(dir: string, now: number): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return; // dir just created and already empty, or unreadable — nothing to sweep.
+  }
+
+  for (const name of names) {
+    const match = PROBE_NAME_PATTERN.exec(name);
+    if (!match) continue;
+    const timestamp = Number(match[1]);
+    if (!Number.isFinite(timestamp) || now - timestamp <= PROBE_STALE_MS) continue;
+    try {
+      unlinkSync(join(dir, name));
+    } catch {
+      // Best effort: already gone, or a concurrent sweep got there first.
+    }
+  }
+}
+
+/** `mkdirSync` + a temp marker file write/unlink: proves both creatability and write permission, not just existence (a read-only *existing* directory would otherwise pass a bare `mkdirSync` check silently, since recursive mkdir on an existing dir never fails). Also sweeps any stale marker left behind by an earlier, SIGKILLed probe (R4) before writing its own. */
+function defaultWritabilityProbe(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+  sweepStaleWriteProbes(dir, Date.now());
+  const marker = join(dir, `.kankaku-write-probe.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(marker, "");
+  unlinkSync(marker);
+}
+
+/**
+ * Resolve the target directory for a write that would normally go to
+ * `candidateDir` (F1: routing a verified subagent's work log/inflight
+ * checkpoints to its orchestrator's kankaku directory instead of its own
+ * cwd-relative one — ADR 0023's rewrite): `candidateDir` when it can be
+ * proven writable — created if it does not exist yet — `fallbackDir` (the
+ * process's own local directory) otherwise, so a parent directory that no
+ * longer exists, or that this process lacks permission to write to,
+ * degrades to a safe, local fallback instead of throwing and losing the
+ * record entirely. `usedFallback` lets the caller surface this (`/kankaku
+ * doctor`) so a human can notice and reunite the record manually — the
+ * append-only log can never be rewritten to fix it after the fact. Never
+ * throws: `fallbackDir` itself is never probed here — its own writability
+ * is handled the ordinary way, by whichever adapter eventually writes to
+ * it, exactly as it always has been for a process that never needed to
+ * route anywhere.
+ */
+export function resolveWritableTarget(candidateDir: string, fallbackDir: string, deps: ResolveWritableTargetDeps = {}): WritableTargetResult {
+  const probe = deps.probe ?? defaultWritabilityProbe;
+  try {
+    probe(candidateDir);
+    return { dir: candidateDir, usedFallback: false };
+  } catch {
+    return { dir: fallbackDir, usedFallback: true };
+  }
+}

package/src/adapters/lazy-file-inflight-store.ts

@@ -0,0 +1,43 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+import { FileInflightStore } from "./file-inflight-store.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+/**
+ * {@link InflightStore} that resolves a relative checkpoint directory
+ * lazily, mirroring {@link LazyJsonlWorkLog}: against the project of the
+ * first saved record, or against `fallbackCwd()` when `clear` or
+ * `recoverStale` happens before any record was saved in this process
+ * (e.g. `session_start`, which runs before `before_agent_start`).
+ */
+export class LazyFileInflightStore implements InflightStore {
+  private readonly dirOrRelative: string;
+  private readonly pid: number;
+  private readonly fallbackCwd: () => string;
+  private resolved: FileInflightStore | undefined;
+
+  constructor(dirOrRelative: string, pid: number, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.pid = pid;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  private resolveFor(cwd: string): FileInflightStore {
+    if (!this.resolved) {
+      this.resolved = new FileInflightStore(resolveKankakuDir(this.dirOrRelative, cwd), this.pid);
+    }
+    return this.resolved;
+  }
+
+  save(record: WorkRecord): void {
+    this.resolveFor(record.project).save(record);
+  }
+
+  clear(): void {
+    this.resolveFor(this.fallbackCwd()).clear();
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    return this.resolveFor(this.fallbackCwd()).recoverStale(isAlive);
+  }
+}

package/src/adapters/lazy-jsonl-work-log.ts

@@ -0,0 +1,39 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import { JsonlWorkLog } from "./jsonl-work-log.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+/**
+ * {@link WorkLog} that resolves a relative log directory lazily: against the
+ * project of the first appended record, or against `fallbackCwd()` when a
+ * read happens before any record was written in this process.
+ */
+export class LazyJsonlWorkLog implements WorkLog {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+  private resolved: JsonlWorkLog | undefined;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  private resolveFor(cwd: string): JsonlWorkLog {
+    if (!this.resolved) {
+      this.resolved = new JsonlWorkLog(resolveKankakuDir(this.dirOrRelative, cwd));
+    }
+    return this.resolved;
+  }
+
+  append(record: WorkRecord): void {
+    this.resolveFor(record.project).append(record);
+  }
+
+  readAll(): WorkRecord[] {
+    return this.resolveFor(this.fallbackCwd()).readAll();
+  }
+
+  version(): string {
+    return this.resolveFor(this.fallbackCwd()).version();
+  }
+}

package/src/adapters/machine-process-registry.ts

@@ -0,0 +1,256 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { classifyRegistryEntries, DEFAULT_MAX_ENTRY_AGE_MS } from "../domain/registry-health.ts";
+import type { RegistryClassification } from "../domain/registry-health.ts";
+import type { ProcessRegistry, RegistryEntry, RegistrySweepDeps } from "../ports/process-registry.ts";
+import { ensureDirMode, OWNER_FILE_MODE, tightenMode } from "./file-modes.ts";
+
+const RUN_DIR_NAME = "run";
+const JSON_EXT = ".json";
+
+function isOrchestratorRef(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object") return false;
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref["pid"] === "number" &&
+    typeof ref["project"] === "string" &&
+    typeof ref["startedAt"] === "string" &&
+    (ref["dir"] === undefined || typeof ref["dir"] === "string")
+  );
+}
+
+function isRegistryEntry(value: unknown): value is RegistryEntry {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["pid"] === "number" &&
+    typeof record["parentPid"] === "number" &&
+    (record["role"] === "orchestrator" || record["role"] === "subagent") &&
+    typeof record["project"] === "string" &&
+    typeof record["dir"] === "string" &&
+    typeof record["startedAt"] === "string" &&
+    isOrchestratorRef(record["orchestratorRef"]) &&
+    (record["processStartId"] === undefined || typeof record["processStartId"] === "number")
+  );
+}
+
+function safeUnlink(filePath: string): void {
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Best effort: another process (or a concurrent sweep) may have already removed it.
+  }
+}
+
+/**
+ * Delete `filePath` only when its on-disk bytes, re-read right now, are
+ * still byte-for-byte `expectedText` (F4, TOCTOU fix). Between this sweep's
+ * directory scan (where `expectedText` was captured) and this call, the pid
+ * this file is named after may have been reused by a brand new process that
+ * already wrote its own fresh entry to the very same path — deleting it then
+ * would destroy a live registration this sweep never actually judged.
+ * Skipping (rather than deleting) on any mismatch, a read failure, or the
+ * file already being gone is always the safe choice: a file that is
+ * genuinely stale gets a further chance on the next sweep.
+ */
+function safeUnlinkIfUnchanged(filePath: string, expectedText: string): void {
+  let current: string;
+  try {
+    current = readFileSync(filePath, "utf8");
+  } catch {
+    return; // already gone, or unreadable — nothing this call should touch.
+  }
+  if (current !== expectedText) return; // raced: a fresh entry now lives at this path.
+  safeUnlink(filePath);
+}
+
+/** Default `isAlive`: probe with signal 0 — mirrors `pi-tracker.ts`/`sync-state-store.ts`'s own default. */
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * {@link ProcessRegistry} backed by `<homeDir>/.kankaku/run/<pid>.json`,
+ * machine-wide and independent of any project's `KANKAKU_DIR` (ADR 0023).
+ * `record()` writes atomically (tmp file + rename), mirroring
+ * `file-inflight-store.ts`. Every operation degrades to "registry
+ * unavailable" (a no-op write, an empty read) on any failure — including a
+ * `homeDir()` that throws (no `HOME`, a sandboxed environment) — rather
+ * than propagating, since this is an enhancement to subagent detection and
+ * must never block or crash the extension it improves.
+ */
+export class MachineProcessRegistry implements ProcessRegistry {
+  private readonly homeDir: () => string;
+
+  constructor(homeDir: () => string) {
+    this.homeDir = homeDir;
+  }
+
+  private runDir(): string | undefined {
+    try {
+      return join(this.homeDir(), ".kankaku", RUN_DIR_NAME);
+    } catch {
+      return undefined;
+    }
+  }
+
+  record(entry: RegistryEntry, isAlive: (pid: number) => boolean = defaultIsAlive, sweepDeps: RegistrySweepDeps = {}): void {
+    const dir = this.runDir();
+    if (dir === undefined) return;
+
+    try {
+      ensureDirMode(dir);
+      const target = join(dir, `${entry.pid}${JSON_EXT}`);
+      const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+      writeFileSync(tmp, JSON.stringify(entry), { mode: OWNER_FILE_MODE });
+      renameSync(tmp, target);
+    } catch {
+      // Best effort: a write failure (no permission, disk full) must not
+      // block or fail the run it would otherwise track.
+      return;
+    }
+
+    this.sweep(dir, entry.pid, isAlive, sweepDeps);
+  }
+
+  removeOwn(pid: number, processStartId: number | undefined): void {
+    const dir = this.runDir();
+    if (dir === undefined) return;
+
+    const target = join(dir, `${pid}${JSON_EXT}`);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(target, "utf8"));
+    } catch {
+      return; // nothing to remove, or unreadable — best effort.
+    }
+
+    if (!isRegistryEntry(parsed) || parsed.pid !== pid || parsed.processStartId !== processStartId) {
+      // Not verifiably this process's own entry (already overwritten by a
+      // pid-reuse successor, or a mismatched identity) — never touch it.
+      return;
+    }
+
+    safeUnlink(target);
+  }
+
+  readAll(): RegistryEntry[] {
+    const dir = this.runDir();
+    if (dir === undefined || !existsSync(dir)) return [];
+
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return [];
+    }
+
+    const entries: RegistryEntry[] = [];
+    for (const name of names) {
+      if (!name.endsWith(JSON_EXT)) continue; // skips .tmp files too (they never end in plain .json)
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(join(dir, name), "utf8"));
+        if (isRegistryEntry(parsed)) entries.push(parsed);
+        // Tolerate a structurally invalid entry (e.g. a torn write); skip it.
+      } catch {
+        // Tolerate malformed/corrupt files; skip them.
+      }
+    }
+    return entries;
+  }
+
+  /**
+   * Read-only registry health snapshot for `/kankaku doctor`
+   * (SUBAGENT-REQ-017): every currently-persisted entry, classified as kept
+   * or discarded-and-why via the same pure classifier a real sweep uses —
+   * but without deleting anything, and (by default) without re-verifying
+   * any pid's live start identity, so this stays a cheap, no-extra-spawn
+   * diagnostic: a `stale-reuse` verdict therefore only ever shows up here
+   * when the caller explicitly injects a fresh `liveStartId` (e.g. from an
+   * ancestry snapshot it already has); otherwise such entries simply read
+   * as "kept" here even though a real `record()` sweep, run by a process
+   * that *does* have that live data, would already have discarded them.
+   */
+  health(deps: { isAlive?: (pid: number) => boolean; liveStartId?: (pid: number) => number | undefined; now?: number } = {}): RegistryClassification {
+    const entries = this.readAll();
+    return classifyRegistryEntries(entries, -1, {
+      isAlive: deps.isAlive ?? defaultIsAlive,
+      liveStartId: deps.liveStartId ?? (() => undefined),
+      now: deps.now ?? Date.now(),
+      maxAgeMs: DEFAULT_MAX_ENTRY_AGE_MS,
+    });
+  }
+
+  /**
+   * Opportunistic sweep, run whenever this process writes its own entry
+   * (mirrors `file-inflight-store.ts`'s stray-tmp-file sweep pattern), so
+   * `run/` does not grow unbounded and never keeps serving a stale
+   * identity (SUBAGENT-REQ-010, and the PID-reuse fix). Delegates the
+   * actual keep/discard decision to the pure
+   * `domain/registry-health.ts#classifyRegistryEntries`, fed with every
+   * *structurally valid* on-disk entry (a corrupt/torn file is simply
+   * skipped here, same as `readAll`) plus whatever this call's own
+   * `isAlive`/`liveStartId` can tell it. Never removes the entry this call
+   * itself just wrote, regardless of what those report for it.
+   */
+  private sweep(dir: string, ownPid: number, isAlive: (pid: number) => boolean, sweepDeps: RegistrySweepDeps): void {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    const entries: RegistryEntry[] = [];
+    const pathByPid = new Map<number, string>();
+    // Raw file text as read during this scan, keyed by pid — kept so a
+    // later deletion can re-verify byte-for-byte against what was actually
+    // judged stale (see the TOCTOU re-check below), never against a
+    // re-parsed/re-serialized copy that could mask a real change.
+    const textByPid = new Map<number, string>();
+    for (const name of names) {
+      if (!name.endsWith(JSON_EXT)) continue;
+      const pid = Number(name.slice(0, -JSON_EXT.length));
+      if (!Number.isFinite(pid)) continue;
+      const path = join(dir, name);
+      // Best-effort mode tightening for every entry file this sweep
+      // encounters (F4), not just this process's own — an older kankaku
+      // build, or a filesystem with a permissive default, may have left one
+      // world/group-readable.
+      tightenMode(path, OWNER_FILE_MODE);
+      try {
+        const text = readFileSync(path, "utf8");
+        const parsed: unknown = JSON.parse(text);
+        if (isRegistryEntry(parsed)) {
+          entries.push(parsed);
+          pathByPid.set(pid, path);
+          textByPid.set(pid, text);
+        }
+        // A structurally invalid/corrupt file is left alone here — readAll
+        // already tolerates it by skipping, and this sweep only acts on
+        // entries it can positively classify.
+      } catch {
+        // Tolerate malformed/corrupt files; skip them.
+      }
+    }
+
+    const { discard } = classifyRegistryEntries(entries, ownPid, {
+      isAlive,
+      liveStartId: sweepDeps.liveStartId ?? (() => undefined),
+      now: sweepDeps.now ?? Date.now(),
+      maxAgeMs: DEFAULT_MAX_ENTRY_AGE_MS,
+    });
+
+    for (const { entry } of discard) {
+      const path = pathByPid.get(entry.pid);
+      const expectedText = textByPid.get(entry.pid);
+      if (path && expectedText !== undefined) safeUnlinkIfUnchanged(path, expectedText);
+    }
+  }
+}