kankaku 0.5.0 → 0.6.0

package/README.md

@@ -804,7 +804,9 @@ On `session_start`, for the orchestrator role with a UI available:
    sorted by name, plus "— skip —"), then for the project (active projects
    of that client, plus "(no project)" and "— skip —"). Declining at either
    step — "— skip —" or dismissing the dialog — cancels the whole pick and
-   is remembered for the session.
+   is remembered for the session. The picker shows the freshly refreshed
+   catalog when the hub answered within the deadline described in "Caching
+   and offline behaviour" below; otherwise it falls back to the cache.
 
 After a pick, kankaku asks whether to remember it for this repository; a
 "yes" merges `clientId`/`projectId` into `<KANKAKU_DIR>/config.json`.
@@ -826,19 +828,36 @@ a project) in place of the legacy client label, both idle and during a run.
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at
-`~/.kankaku/catalog.json` with a 6-hour TTL. On startup: a fresh cache is
-used as-is; a stale cache is used immediately while a refresh happens in
-the background; when there is no cache at all, one refresh is awaited
-(bounded by the hub client's own request timeout, 3s by default) before
-falling back. If the hub is unreachable and there is no cache, kankaku
-notifies once (`kankaku: hub unreachable, using local labels`) and
-continues exactly as it would without a hub configured. `/kankaku catalog
-refresh` forces a refresh on demand. The cache file is always written
-owner-only (`0600`); if kankaku is the first thing to ever create
-`~/.kankaku` itself (no project has put its own `.kankaku` there), the
-directory is created owner-only (`0700`) too — but an already-existing
-`~/.kankaku` is never chmod'd, since it may be a project's own kankaku
-directory (see "The registry" below for the same rule applied to `run/`).
+`~/.kankaku/catalog.json`. On `session_start`, for the orchestrator role
+with a UI available, kankaku always starts a background refresh when a
+cache already exists — regardless of the cache's age — so a client or
+project created in the hub minutes ago shows up without waiting for a TTL
+to expire (the 6-hour TTL and `isStale()` still exist and still gate other
+callers, but session start no longer depends on them). If the target
+resolves silently from the project config file or `repo_paths` against
+the cached snapshot, `ensurePicked` returns immediately without waiting
+for that refresh at all; it keeps running in the background and
+`catalog.read()` reflects it once it lands, exactly as before. Only when
+the picker is actually about to be shown does kankaku wait for the
+in-flight refresh, bounded by a short deadline (1.5s by default,
+`pickerRefreshDeadlineMs`): if the hub answers in time, the picker offers
+the fresh clients/projects; otherwise (or if the refresh fails) it falls
+back to the cached snapshot silently, and the refresh keeps running
+in the background rather than being aborted. `/kankaku target pick` (the
+explicit re-pick command) follows the same wait-then-fall-back rule. When
+there is no cache at all, one refresh is still awaited (bounded by the hub
+client's own request timeout, 3s by default) before falling back — this
+path is unchanged. If the hub is unreachable and there is no cache,
+kankaku notifies once (`kankaku: hub unreachable, using local labels`) and
+continues exactly as it would without a hub configured; a background
+refresh that merely fails once a cache already exists is silent, with no
+notification. `/kankaku catalog refresh` still forces a refresh on demand
+independently of any of this. The cache file is always written owner-only
+(`0600`); if kankaku is the first thing to ever create `~/.kankaku` itself
+(no project has put its own `.kankaku` there), the directory is created
+owner-only (`0700`) too — but an already-existing `~/.kankaku` is never
+chmod'd, since it may be a project's own kankaku directory (see "The
+registry" below for the same rule applied to `run/`).
 
 ### Privacy (catalog)
 
@@ -1179,6 +1198,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
@@ -1198,11 +1245,12 @@ 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.

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

@@ -0,0 +1,36 @@
+import type { Client, 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 }` pair, e.g. `createPocketBaseCatalogFetcher(...)`. */
+    fetchCatalog: (signal?: AbortSignal) => Promise<{
+        clients: Client[];
+        projects: Project[];
+    }>;
+}
+/**
+ * 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,111 @@
+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 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"]));
+}
+/**
+ * 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 } = await this.deps.fetchCatalog(signal);
+            const snapshot = { fetchedAt: this.deps.clock.now(), url: this.deps.url, clients, projects };
+            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;

package/dist/adapters/kankaku-dir.js

@@ -0,0 +1,85 @@
+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, cwd) {
+    return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}
+/** 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, now) {
+    let names;
+    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) {
+    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, fallbackDir, deps = {}) {
+    const probe = deps.probe ?? defaultWritabilityProbe;
+    try {
+        probe(candidateDir);
+        return { dir: candidateDir, usedFallback: false };
+    }
+    catch {
+        return { dir: fallbackDir, usedFallback: true };
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { WorkLog } from "../ports/work-log.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 declare class LazyJsonlWorkLog implements WorkLog {
+    private readonly dirOrRelative;
+    private readonly fallbackCwd;
+    private resolved;
+    constructor(dirOrRelative: string, fallbackCwd?: () => string);
+    private resolveFor;
+    append(record: WorkRecord): void;
+    readAll(): WorkRecord[];
+    version(): string;
+}