kankaku-pi 1.0.0

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/export-writer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Write `content` to `<dir>/export/<name>` (creating the `export`
+ * subdirectory as needed, overwriting any existing file with the same
+ * name) and return the absolute path it was written to.
+ */
+export declare function writeExport(dir: string, name: string, content: string): string;
+/** Writes exports under a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export declare class LazyExportWriter {
+    private readonly dirOrRelative;
+    private readonly fallbackCwd;
+    constructor(dirOrRelative: string, fallbackCwd?: () => string);
+    write(name: string, content: string): string;
+}

package/dist/adapters/export-writer.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.js";
+const EXPORT_SUBDIR = "export";
+/**
+ * Write `content` to `<dir>/export/<name>` (creating the `export`
+ * subdirectory as needed, overwriting any existing file with the same
+ * name) and return the absolute path it was written to.
+ */
+export function writeExport(dir, name, content) {
+    const exportDir = join(dir, EXPORT_SUBDIR);
+    mkdirSync(exportDir, { recursive: true });
+    const filePath = resolve(join(exportDir, name));
+    writeFileSync(filePath, content);
+    return filePath;
+}
+/** Writes exports under a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyExportWriter {
+    dirOrRelative;
+    fallbackCwd;
+    constructor(dirOrRelative, fallbackCwd = () => process.cwd()) {
+        this.dirOrRelative = dirOrRelative;
+        this.fallbackCwd = fallbackCwd;
+    }
+    write(name, content) {
+        return writeExport(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), name, content);
+    }
+}

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-actions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared line-building for the hub-facing `/kankaku` subcommands (`sync`,
+ * `sync all`, `sync status`, `backfill`, `catalog refresh`) and the panel's
+ * `sync`/`export` screens (`adapters/panel/screens/sync.ts`), extracted from
+ * `kankaku-command.ts` so the subcommands and the panel can never drift —
+ * see odd/tasks/kankaku-panel.md P4.
+ */
+import type { CatalogSnapshot } from "../ports/catalog.ts";
+import type { SyncStatusSnapshot, SyncSummary } from "./sync-runner.ts";
+/**
+ * `/kankaku sync status`'s report lines: the watermark, the pending count,
+ * how many tasks fell outside this run's revisit window (R3), and the last
+ * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
+ */
+export declare function buildSyncStatusLines(status: SyncStatusSnapshot): string[];
+/**
+ * Render a {@link SyncSummary} as report lines: counts, any stop reason, the
+ * new watermark, and the unassigned/failed breakdowns. Used by `/kankaku
+ * sync`/`sync all` and the panel's sync screen.
+ */
+export declare function formatSyncSummaryLines(summary: SyncSummary): string[];
+/**
+ * `/kankaku backfill`'s report lines: tasks routed to Sin determinar this
+ * run, grouped by their old free-text label, or "no unassigned tasks" when
+ * none were. Exact body of `handleBackfillCommand`.
+ */
+export declare function formatBackfillLines(summary: SyncSummary): string[];
+/**
+ * `/kankaku catalog refresh`'s report lines: client/project counts, or an
+ * unreachable notice when the refresh failed (`snapshot` is `undefined`).
+ * The subcommand still notifies that failure as an error rather than a
+ * report (see `handleCatalogCommand`); the panel's sync screen shows
+ * whatever this returns either way.
+ */
+export declare function formatCatalogRefreshLines(snapshot: CatalogSnapshot | undefined): string[];

package/dist/adapters/hub-actions.js

@@ -0,0 +1,70 @@
+/**
+ * `/kankaku sync status`'s report lines: the watermark, the pending count,
+ * how many tasks fell outside this run's revisit window (R3), and the last
+ * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
+ */
+export function buildSyncStatusLines(status) {
+    const { state, pending, staleOutsideWindow } = status;
+    const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
+    if (staleOutsideWindow > 0) {
+        lines.push(`${staleOutsideWindow} task(s) never synced fall outside the sync window — run '/kankaku sync all' to upload them`);
+    }
+    if (state?.lastError)
+        lines.push(`last error: ${state.lastError.message} (at ${state.lastError.at})`);
+    return lines;
+}
+/**
+ * Render a {@link SyncSummary} as report lines: counts, any stop reason, the
+ * new watermark, and the unassigned/failed breakdowns. Used by `/kankaku
+ * sync`/`sync all` and the panel's sync screen.
+ */
+export function formatSyncSummaryLines(summary) {
+    const lines = [`uploaded ${summary.uploaded}, updated ${summary.updated}, skipped ${summary.skipped}, failed ${summary.failed.length}`];
+    if (summary.locked)
+        lines.push("another sync is already in progress; nothing was attempted");
+    if (summary.error)
+        lines.push(`stopped early: ${summary.error}`);
+    if (summary.syncedThrough)
+        lines.push(`synced through ${summary.syncedThrough}`);
+    const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+    if (unassignedEntries.length > 0) {
+        lines.push("unassigned (Sin determinar):");
+        for (const [label, count] of unassignedEntries)
+            lines.push(`  ${label}: ${count}`);
+    }
+    if (summary.failed.length > 0) {
+        lines.push("failed:");
+        for (const entry of summary.failed)
+            lines.push(`  ${entry.id}: ${entry.reason}`);
+    }
+    return lines;
+}
+/**
+ * `/kankaku backfill`'s report lines: tasks routed to Sin determinar this
+ * run, grouped by their old free-text label, or "no unassigned tasks" when
+ * none were. Exact body of `handleBackfillCommand`.
+ */
+export function formatBackfillLines(summary) {
+    const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+    const lines = unassignedEntries.length > 0
+        ? [
+            ...unassignedEntries.map(([label, count]) => `${label}: ${count} task(s) -> Sin determinar`),
+            "reassign these in the hub web app's unassigned queue",
+        ]
+        : ["no unassigned tasks"];
+    if (summary.error)
+        lines.push(`stopped early: ${summary.error}`);
+    return lines;
+}
+/**
+ * `/kankaku catalog refresh`'s report lines: client/project counts, or an
+ * unreachable notice when the refresh failed (`snapshot` is `undefined`).
+ * The subcommand still notifies that failure as an error rather than a
+ * report (see `handleCatalogCommand`); the panel's sync screen shows
+ * whatever this returns either way.
+ */
+export function formatCatalogRefreshLines(snapshot) {
+    if (!snapshot)
+        return ["hub unreachable; catalog not refreshed"];
+    return [`refreshed: ${snapshot.clients.length} client(s), ${snapshot.projects.length} project(s)`];
+}

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;