kankaku 0.5.1 → 0.6.5

package/README.md

@@ -114,7 +114,9 @@ remains valid.
 `clientId`, `clientName`, `projectId`, `projectName` and `machine` are only
 present once a hub is configured (see "Hub (PocketBase)"); every report and
 export written before this feature, or by a user without a hub, is
-unaffected.
+unaffected. `hubTaskId`/`hubTaskTitle` are set alongside them only when a
+hub task is linked to the session (`/kankaku task pick`) — see "Linking to
+a hub task" below.
 
 `sessionDir` is present only when pi's session manager reports a
 *non-default* session directory (`--session-dir`, or a resumed session
@@ -686,7 +688,11 @@ the future, this is the signal that would surface it.
 ## The `/kankaku` command
 
 Run `/kankaku` inside pi to see today's totals (work, waiting, record count)
-per role, plus a union-based tasks segment. In the interactive TUI the report
+per role, plus a union-based tasks segment. Each totals line also shows
+`cache hit NN%` when tokens were recorded: the share of prompt input tokens
+served from the provider's prompt cache, cache reads over input plus cache
+reads plus cache writes; the segment is omitted, not shown as `0%`, when no
+tokens were recorded. In the interactive TUI the report
 is appended to the chat transcript as a durable card that is never sent to
 the LLM; without a UI (print or RPC mode) it falls back to a notification.
 Arguments are whitespace-separated and order-insensitive:
@@ -719,6 +725,9 @@ The following are available only when a hub is configured (see "Hub
   produced it. `/kankaku target pick` runs the picker again (works
   mid-session; the new target applies to records settled afterwards).
   `/kankaku target clear` clears the session-level target.
+- `/kankaku task` (or `/kankaku task pick`) — link this session to an
+  open/doing hub task of the effective project. `/kankaku task clear`
+  drops the link. See "Linking to a hub task" below.
 - `/kankaku catalog refresh` — force a catalog refresh and report the
   client/project counts.
 - `/kankaku projects` — one line per project (work/waiting/wall time, cost,
@@ -825,6 +834,33 @@ task view exposes it from the orchestrator record only.
 The status bar shows `💼 <client> · <project>` (or just `💼 <client>` without
 a project) in place of the legacy client label, both idle and during a run.
 
+### Linking to a hub task
+
+`/kankaku task` (or `/kankaku task pick`) links the current session to one
+of the effective project's existing hub `tasks` rows: a `ctx.ui.select`
+picker lists the project's `open`/`doing` tasks, sorted by title (colliding
+titles are disambiguated with the task's external reference, or its id).
+`/kankaku task clear` drops the link, keeping the rest of the session
+target. kankaku never creates a task from pi — this only links to one
+that already exists in the hub.
+
+The link is **session-only**: unlike `clientId`/`projectId`, it is never
+persisted to `<KANKAKU_DIR>/config.json`, and it is never asked for at
+`session_start` — you always link a task explicitly, with `/kankaku task`.
+Any target change (`/kankaku target pick`, `/kankaku target clear`, or the
+legacy `/kankaku client <name>`) drops the linked task, since a new client
+or project makes the old task's link meaningless. A task whose project no
+longer matches the effective project (e.g. after a target change or a
+reassignment in the hub) is also dropped by the domain resolver, never
+silently linked across projects. A task already marked `done` when linked
+keeps linking for the rest of the session — only the picker itself hides
+`done` tasks, so you cannot accidentally pick a closed one, but finishing
+the picked task in the hub mid-session does not break the link. Subagent
+records never carry a linked task, exactly like `clientId`/`projectId` —
+the task view exposes it from the orchestrator record only, and
+`formatWorkTargetLabel` appends it to the status-bar/report label as
+`<client> · <project> › <task title>`.
+
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at
@@ -905,10 +941,13 @@ web app) can move a task from one client/project to another directly in
 PocketBase — for example, moving a "Sin determinar" row to its real
 client once you have identified it. A later re-sync of that same task
 **must never undo that**: on create kankaku sends the full row, including
-`client`/`project`/`legacy_client_label`; on every subsequent update it
-sends measurement fields only (`wall_ms`, `cost`, `status`, ...) and never
-touches assignment fields again. If you need kankaku itself to change a
-task's assignment, do it in the web app, not by re-syncing.
+`client`/`project`/`task`/`legacy_client_label`; on every subsequent update
+it sends measurement fields only (`wall_ms`, `cost`, `status`, ...) and
+never touches assignment fields again. `task` (the linked `tasks` relation)
+is create-only for the exact same reason: reassigning which task a row
+belongs to in the web app is never undone by a later sync. If you need
+kankaku itself to change a task's assignment, do it in the web app, not by
+re-syncing.
 
 **Historical ("Sin determinar") records.** A record with no `clientId`, or
 whose `clientId` no longer resolves in the catalog, is routed to the hub's
@@ -1198,6 +1237,34 @@ Columns (in this order for CSV; the same fields for JSON):
   are never throttled, and none of this applies to a manual `/kankaku
   sync`, `sync all`, or `backfill`.
 
+## Using kankaku as a library
+
+Besides the pi extension, `kankaku` publishes three compiled, pi-free entry
+points for a plain Node consumer — no pi, no TypeScript loader — such as a
+separate CLI or another agent's plugin (e.g. the `kankaku-claude` package):
+
+- `kankaku/domain` — the pure domain layer: `WorkTracker`, `buildTasks`,
+  `unionMs`, and the rest of `src/domain/`.
+- `kankaku/ports` — the port interfaces only (`Clock`, `WorkLog`, `Catalog`,
+  `WorkSink`, `ProcessRegistry`, `InflightStore`), for writing your own
+  adapters against.
+- `kankaku/hub` — the pi-free adapters: the PocketBase HTTP client and
+  catalog/sink, `runSync`, the JSONL work log, the cached catalog, hub
+  credentials, and related filesystem helpers. Nothing reachable from this
+  entry point ever imports a pi package type.
+
+```js
+import { runSync } from "kankaku/hub";
+import { buildTasks } from "kankaku/domain";
+```
+
+Each entry point is compiled ahead of time (`npm run build`, part of `npm
+run check`) to `dist/<domain|ports|hub>/index.{js,d.ts}` and resolved
+through `package.json`'s `exports` map, so importing it never needs type
+stripping or a `.ts` loader. `kankaku/src/*` is how pi itself loads
+`./src/extension.ts` and is not a public API — its shape can change without
+notice; import only `kankaku/domain`, `kankaku/ports`, or `kankaku/hub`.
+
 ## Limitations
 
 - A prompt shown by a tool that does not go through `ctx.ui` and is not
@@ -1217,14 +1284,17 @@ Columns (in this order for CSV; the same fields for JSON):
   (PocketBase)" above is phase 1; sync itself ("Hub (PocketBase)" > "Sync")
   is phase 2 — both already shipped.
 - A standalone CLI entry point (`npx kankaku sync`, for a cron/launchd job
-  outside of any pi session) is deliberately not included yet: Node refuses
-  type stripping for a `.ts` file under `node_modules`, so a bin script
-  needs a build step this package does not have yet. `sync-runner.ts` and
-  its adapters are already decoupled from pi so that build step is the only
-  missing piece.
+  outside of any pi session) is deliberately not included yet. The build
+  step it needs now exists — `sync-runner.ts` and its adapters are
+  published pi-free and pre-compiled as `kankaku/hub` (see "Using kankaku
+  as a library") — but a `bin` script that wires that up as a runnable CLI
+  is not; the compiled entry points are today consumed as a library, not a
+  binary.
 - Linking a `task_entries` row to an existing `tasks` record (phase 3 in the
-  hub's own data model) — kankaku never invents tasks; it would only ever
-  link to one created in the manager.
+  hub's own data model) has shipped: `/kankaku task pick`/`clear` (see
+  "Linking to a hub task" above). Creating a task from pi
+  (`/kankaku task new`) is deliberately not included — kankaku never
+  invents tasks; it only ever links to one already created in the manager.
 - Generic subagent detection (phase 6): 6a fixed the two correctness bugs
   described in "Subagents" above (a phantom-orchestrator double count; a
   gentle-pi cross-worktree child's work going missing). 6b added the

package/dist/adapters/cached-catalog.d.ts

@@ -0,0 +1,42 @@
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { Clock } from "../ports/clock.ts";
+import type { Catalog, CatalogSnapshot } from "../ports/catalog.ts";
+export interface CachedCatalogDeps {
+    /** Absolute path to the cache file, e.g. `~/.kankaku/catalog.json`. */
+    filePath: string;
+    /** The configured hub URL; a cache written for a different URL is ignored. */
+    url: string;
+    clock: Clock;
+    /** Cache TTL in ms. Defaults to 6 hours. */
+    ttlMs?: number;
+    /**
+     * Fetch a fresh `{ clients, projects, tasks }` triple, e.g.
+     * `createPocketBaseCatalogFetcher(...)`. `tasks` is optional here (unlike
+     * on the real PocketBase fetcher) so a test double that only cares about
+     * clients/projects keeps compiling unchanged.
+     */
+    fetchCatalog: (signal?: AbortSignal) => Promise<{
+        clients: Client[];
+        projects: Project[];
+        tasks?: HubTask[];
+    }>;
+}
+/**
+ * Disk-backed {@link Catalog}: `read()` is a synchronous, cheap read of the
+ * last known snapshot (memoised after the first disk read so repeated
+ * calls in one process never re-stat/re-parse); `refresh()` fetches, caches
+ * to disk atomically (tmp + rename, mirroring `file-inflight-store.ts`),
+ * and never throws — a failed refresh resolves `undefined` and leaves the
+ * previous snapshot (if any) untouched.
+ */
+export declare class CachedCatalog implements Catalog {
+    private readonly deps;
+    private memo;
+    private memoized;
+    constructor(deps: CachedCatalogDeps);
+    read(): CatalogSnapshot | undefined;
+    isStale(): boolean;
+    refresh(signal?: AbortSignal): Promise<CatalogSnapshot | undefined>;
+    private readDisk;
+    private writeDisk;
+}

package/dist/adapters/cached-catalog.js

@@ -0,0 +1,121 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { OWNER_DIR_MODE, OWNER_FILE_MODE } from "./file-modes.js";
+/** Six hours in milliseconds — clients and projects change rarely. */
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+function isClientArray(value) {
+    return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof item.id === "string");
+}
+function isProjectArray(value) {
+    return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof item.id === "string");
+}
+function isHubTaskArray(value) {
+    return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof item.id === "string");
+}
+function isCatalogSnapshot(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record["fetchedAt"] === "number" &&
+        typeof record["url"] === "string" &&
+        isClientArray(record["clients"]) &&
+        isProjectArray(record["projects"]) &&
+        (record["tasks"] === undefined || isHubTaskArray(record["tasks"])));
+}
+/**
+ * Disk-backed {@link Catalog}: `read()` is a synchronous, cheap read of the
+ * last known snapshot (memoised after the first disk read so repeated
+ * calls in one process never re-stat/re-parse); `refresh()` fetches, caches
+ * to disk atomically (tmp + rename, mirroring `file-inflight-store.ts`),
+ * and never throws — a failed refresh resolves `undefined` and leaves the
+ * previous snapshot (if any) untouched.
+ */
+export class CachedCatalog {
+    deps;
+    memo;
+    memoized = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    read() {
+        if (!this.memoized) {
+            this.memo = this.readDisk();
+            this.memoized = true;
+        }
+        return this.memo;
+    }
+    isStale() {
+        const snapshot = this.read();
+        if (!snapshot)
+            return true;
+        const ttl = this.deps.ttlMs ?? DEFAULT_TTL_MS;
+        return this.deps.clock.now() - snapshot.fetchedAt > ttl;
+    }
+    async refresh(signal) {
+        try {
+            const { clients, projects, tasks } = await this.deps.fetchCatalog(signal);
+            const snapshot = {
+                fetchedAt: this.deps.clock.now(),
+                url: this.deps.url,
+                clients,
+                projects,
+                ...(tasks !== undefined ? { tasks } : {}),
+            };
+            this.writeDisk(snapshot);
+            this.memo = snapshot;
+            this.memoized = true;
+            return snapshot;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    readDisk() {
+        try {
+            if (!existsSync(this.deps.filePath))
+                return undefined;
+            const parsed = JSON.parse(readFileSync(this.deps.filePath, "utf8"));
+            if (!isCatalogSnapshot(parsed))
+                return undefined;
+            if (parsed.url !== this.deps.url)
+                return undefined;
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    writeDisk(snapshot) {
+        try {
+            // This cache lives under `~/.kankaku` (machine-wide, not a project's
+            // own KANKAKU_DIR) — but `~/.kankaku` itself is never mode-tightened
+            // here (R2): when pi runs with cwd === $HOME, a project's own default
+            // KANKAKU_DIR (`.kankaku`, relative) resolves to this exact same
+            // path, and a project's kankaku dir must never be tightened
+            // (AGENTS.md). Only what this package exclusively owns is touched:
+            // an EXISTING directory is never chmod'd — `mkdirSync`'s own `mode`
+            // option only ever applies to a directory this call actually
+            // creates, never one that already existed (Node skips the mkdir
+            // syscall for an existing path segment entirely, mode and all), so
+            // passing `mode` here is safe even though this path may be a
+            // project's own dir (G3). When this call IS the first writer (no
+            // `~/.kankaku` yet at all, e.g. a machine with the hub configured but
+            // no project ever run from $HOME), it is created owner-only
+            // (`OWNER_DIR_MODE`, 0700) rather than left at the umask default. The
+            // cache file itself is always written fresh via tmp+rename with
+            // OWNER_FILE_MODE below, which already guarantees 0600 on every
+            // write regardless of whatever mode an older file at this path (or
+            // an older kankaku build) left behind — a rename replaces the whole
+            // inode, so a stale looser mode can never survive a write.
+            mkdirSync(dirname(this.deps.filePath), { recursive: true, mode: OWNER_DIR_MODE });
+            const tmp = `${this.deps.filePath}.${process.pid}.${Date.now()}.tmp`;
+            // Owner-only: this file names every client/project the machine's user has touched.
+            writeFileSync(tmp, JSON.stringify(snapshot), { mode: OWNER_FILE_MODE });
+            renameSync(tmp, this.deps.filePath);
+        }
+        catch {
+            // Best-effort cache write: a failure here must not fail the refresh
+            // itself, since the in-memory snapshot is still usable this process.
+        }
+    }
+}

package/dist/adapters/file-modes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Every file kankaku writes under `~/.kankaku` (the machine-wide registry
+ * `run/`, the catalog cache) carries absolute project paths, session ids, or
+ * hub identifiers — restricted to the owner (F4). Not applied to a
+ * project's own `<KANKAKU_DIR>` (`worklog.jsonl`, `inflight/`, …), which is
+ * project-local, frequently committed alongside, and out of scope here.
+ */
+export declare const OWNER_DIR_MODE = 448;
+export declare const OWNER_FILE_MODE = 384;
+/**
+ * Create `dir` (recursive) with `mode`, then best-effort tighten it when it
+ * already existed with a looser mode — `mkdirSync`'s own `mode` option only
+ * applies to a directory it actually creates in this call, never to one
+ * that already existed (e.g. left by an older kankaku build, or a
+ * permissive umask). Never throws: a permission-tightening failure must
+ * never block the write this call exists to make.
+ */
+export declare function ensureDirMode(dir: string, mode?: number): void;
+/** Best-effort `chmod` down to `mode` when the current mode is looser than it; never throws. */
+export declare function tightenMode(path: string, mode?: number): void;

package/dist/adapters/file-modes.js

@@ -0,0 +1,34 @@
+import { chmodSync, mkdirSync, statSync } from "node:fs";
+/**
+ * Every file kankaku writes under `~/.kankaku` (the machine-wide registry
+ * `run/`, the catalog cache) carries absolute project paths, session ids, or
+ * hub identifiers — restricted to the owner (F4). Not applied to a
+ * project's own `<KANKAKU_DIR>` (`worklog.jsonl`, `inflight/`, …), which is
+ * project-local, frequently committed alongside, and out of scope here.
+ */
+export const OWNER_DIR_MODE = 0o700;
+export const OWNER_FILE_MODE = 0o600;
+/**
+ * Create `dir` (recursive) with `mode`, then best-effort tighten it when it
+ * already existed with a looser mode — `mkdirSync`'s own `mode` option only
+ * applies to a directory it actually creates in this call, never to one
+ * that already existed (e.g. left by an older kankaku build, or a
+ * permissive umask). Never throws: a permission-tightening failure must
+ * never block the write this call exists to make.
+ */
+export function ensureDirMode(dir, mode = OWNER_DIR_MODE) {
+    mkdirSync(dir, { recursive: true, mode });
+    tightenMode(dir, mode);
+}
+/** Best-effort `chmod` down to `mode` when the current mode is looser than it; never throws. */
+export function tightenMode(path, mode = OWNER_FILE_MODE) {
+    try {
+        const current = statSync(path).mode & 0o777;
+        if ((current & ~mode) !== 0)
+            chmodSync(path, mode);
+    }
+    catch {
+        // Best effort: another process may have already removed the path, or
+        // this filesystem does not support POSIX modes at all.
+    }
+}

package/dist/adapters/hub-credentials.d.ts

@@ -0,0 +1,35 @@
+export interface HubCredentials {
+    url: string;
+    email: string;
+    password: string;
+}
+export interface ResolveHubCredentialsDeps {
+    env: NodeJS.ProcessEnv;
+    /**
+     * Resolves the home directory; called lazily, inside this function, and
+     * defensively. A throwing provider (no `HOME`, a sandboxed environment
+     * without a resolvable home directory) is treated the same as "no home
+     * directory" rather than propagating — env-only credentials must still
+     * resolve, and the hub-unconfigured case must stay a no-op regardless of
+     * the host environment. Injectable for tests; defaults to `os.homedir` at
+     * the call site (extension.ts) — passed as a reference, never invoked
+     * there, so a throw never escapes before this function's own try/catch.
+     */
+    homeDir: () => string;
+}
+export interface ResolveHubCredentialsResult {
+    /** `undefined` when unconfigured (no url/email/password from any source) or the URL is refused. */
+    credentials: HubCredentials | undefined;
+    /** Set only when a hub URL was given but rejected by {@link validateHubUrl}; surface it once via `ctx.ui.notify`. */
+    invalidReason?: string;
+}
+/**
+ * Resolve hub credentials: `KANKAKU_PB_URL`/`_EMAIL`/`_PASSWORD` take
+ * precedence per field over `~/.kankaku/credentials.json` (so a partially
+ * set environment still combines with the file rather than failing
+ * closed). Never reads the project's own `.kankaku/config.json` — that
+ * file is project-local and frequently committed.
+ */
+/** Resolve `homeDir()` defensively: any failure (no `HOME`, a sandboxed environment) yields `undefined` instead of throwing. Exported so callers with their own homedir-dependent path (e.g. `extension.ts`'s catalog cache) can share the same guard. */
+export declare function safeHomeDir(homeDir: () => string): string | undefined;
+export declare function resolveHubCredentials(deps: ResolveHubCredentialsDeps): ResolveHubCredentialsResult;

package/dist/adapters/hub-credentials.js

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadHubEnvCredentials, validateHubUrl } from "../config.js";
+const CREDENTIALS_FILE = join(".kankaku", "credentials.json");
+/**
+ * Read `<homeDir>/.kankaku/credentials.json`. Tolerates a missing file,
+ * malformed JSON, a non-object document, or non-string fields — all
+ * return `{}` rather than throwing, since this file is optional and
+ * hand-edited (mirrors `project-config.ts#readProjectClient`).
+ */
+function readCredentialsFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const record = parsed;
+        return {
+            url: typeof record["url"] === "string" ? record["url"] : undefined,
+            email: typeof record["email"] === "string" ? record["email"] : undefined,
+            password: typeof record["password"] === "string" ? record["password"] : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve hub credentials: `KANKAKU_PB_URL`/`_EMAIL`/`_PASSWORD` take
+ * precedence per field over `~/.kankaku/credentials.json` (so a partially
+ * set environment still combines with the file rather than failing
+ * closed). Never reads the project's own `.kankaku/config.json` — that
+ * file is project-local and frequently committed.
+ */
+/** Resolve `homeDir()` defensively: any failure (no `HOME`, a sandboxed environment) yields `undefined` instead of throwing. Exported so callers with their own homedir-dependent path (e.g. `extension.ts`'s catalog cache) can share the same guard. */
+export function safeHomeDir(homeDir) {
+    try {
+        return homeDir();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveHubCredentials(deps) {
+    const fromEnv = loadHubEnvCredentials(deps.env);
+    const homeDir = safeHomeDir(deps.homeDir);
+    const fromFile = homeDir !== undefined ? readCredentialsFile(join(homeDir, CREDENTIALS_FILE)) : {};
+    const url = fromEnv.url ?? fromFile.url;
+    const email = fromEnv.email ?? fromFile.email;
+    const password = fromEnv.password ?? fromFile.password;
+    if (!url || !email || !password)
+        return { credentials: undefined };
+    const validation = validateHubUrl(url);
+    if (!validation.ok)
+        return { credentials: undefined, invalidReason: validation.reason };
+    return { credentials: { url, email, password } };
+}

package/dist/adapters/jsonl-work-log.d.ts

@@ -0,0 +1,20 @@
+import type { WorkLog } from "../ports/work-log.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+/**
+ * Append-only JSONL {@link WorkLog} backed by `<dir>/worklog.jsonl`.
+ * A record is written with a single `appendFileSync` call so a parent and
+ * its subagent children can write concurrently without interleaving lines.
+ */
+export declare class JsonlWorkLog implements WorkLog {
+    private readonly dir;
+    constructor(dir: string);
+    private get filePath();
+    append(record: WorkRecord): void;
+    /**
+     * Cheap change signal: `mtimeMs:size` of the log file, computed with a
+     * single `statSync` rather than reading the file. `"0:0"` when the file
+     * does not exist yet (before the first `append`).
+     */
+    version(): string;
+    readAll(): WorkRecord[];
+}

package/dist/adapters/jsonl-work-log.js

@@ -0,0 +1,62 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { dedupeById } from "../domain/task-view.js";
+import { isWorkRecord } from "../domain/work-record.js";
+const LOG_FILE_NAME = "worklog.jsonl";
+/**
+ * Append-only JSONL {@link WorkLog} backed by `<dir>/worklog.jsonl`.
+ * A record is written with a single `appendFileSync` call so a parent and
+ * its subagent children can write concurrently without interleaving lines.
+ */
+export class JsonlWorkLog {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    get filePath() {
+        return join(this.dir, LOG_FILE_NAME);
+    }
+    append(record) {
+        mkdirSync(this.dir, { recursive: true });
+        appendFileSync(this.filePath, `${JSON.stringify(record)}\n`);
+    }
+    /**
+     * Cheap change signal: `mtimeMs:size` of the log file, computed with a
+     * single `statSync` rather than reading the file. `"0:0"` when the file
+     * does not exist yet (before the first `append`).
+     */
+    version() {
+        try {
+            const stats = statSync(this.filePath);
+            return `${stats.mtimeMs}:${stats.size}`;
+        }
+        catch {
+            return "0:0";
+        }
+    }
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        const content = readFileSync(this.filePath, "utf8");
+        const records = [];
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (isWorkRecord(parsed)) {
+                    records.push(parsed);
+                }
+                // Tolerate a structurally invalid record (e.g. an incompatible
+                // schema or a torn write that still parses as JSON); skip it.
+            }
+            catch {
+                // Tolerate malformed lines (e.g. a torn write); skip them.
+            }
+        }
+        // One id can be in the file twice (written at settle, then re-appended by
+        // crash recovery): every reader gets it once — see dedupeById.
+        return dedupeById(records);
+    }
+}

package/dist/adapters/kankaku-dir.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function resolveKankakuDir(dirOrRelative: string, cwd: string): string;
+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;
+}
+/**
+ * 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 declare function resolveWritableTarget(candidateDir: string, fallbackDir: string, deps?: ResolveWritableTargetDeps): WritableTargetResult;