kankaku-pi 1.0.0

package/dist/domain/work-tracker.js

@@ -0,0 +1,405 @@
+import { randomUUID } from "node:crypto";
+import { clampIntervals, unionMs } from "./intervals.js";
+import { emptyUsage, EXTENSION_RUN_PROMPT, finiteOrZero, WORK_RECORD_SCHEMA } from "./work-record.js";
+import { mergeAgreeingLaunchInfo, readLaunchInfo, readResultInfo, resolveToolProfile, safeAmbiguousResultInfo } from "./subagent-profile.js";
+/**
+ * Pure domain state machine that turns pi lifecycle events into finished
+ * {@link WorkRecord} entries. Holds no I/O; timestamps come from the
+ * injected {@link Clock} so behaviour is deterministic under test.
+ */
+export class WorkTracker {
+    clock;
+    interactiveTools;
+    subagentProfiles;
+    segmentRules;
+    state;
+    /** Set by {@link onRunStart}, consumed by {@link onAgentStart}: tells a user-announced run from one an extension started. */
+    runAnnounced = false;
+    /** `true` between an agent loop's start and its `agent_end`. */
+    loopActive = false;
+    /**
+     * The previous record, set aside because a new run began after its last
+     * loop ended but BEFORE its `agent_settled` reached us. pi clears its
+     * "run active" flag and only then awaits the `agent_settled` handlers, in
+     * extension load order; an extension loaded earlier (gentle-pi) can start
+     * the next run from its own handler. Whether that `agent_start` was a new
+     * run or an `agent.continue()` of the same one is only knowable at settle
+     * time — see {@link settleAll}.
+     */
+    closing;
+    constructor(options) {
+        this.clock = options.clock;
+        this.interactiveTools = new Set(options.interactiveTools);
+        this.subagentProfiles = options.subagentProfiles;
+        this.segmentRules = options.segmentRules ?? [];
+    }
+    /**
+     * An agent loop actually started. pi announces a USER prompt with
+     * `before_agent_start` ({@link onRunStart}) and then this; a run an
+     * extension starts itself (`sendCustomMessage(..., { triggerTurn: true })`,
+     * how gentle-pi wakes the orchestrator when a background subagent
+     * finishes) only ever produces this one. Without it that whole run — its
+     * time, its cost, and the subagent spans it opens, which its children need
+     * to join — was never recorded.
+     */
+    onAgentStart() {
+        if (this.runAnnounced) {
+            // The loop of the user prompt onRunStart just opened.
+            this.runAnnounced = false;
+            this.loopActive = true;
+            return;
+        }
+        if (this.loopActive)
+            return;
+        this.openRun(EXTENSION_RUN_PROMPT, "extension");
+        this.runAnnounced = false;
+    }
+    onRunStart(prompt, trigger) {
+        this.openRun(prompt, trigger);
+        this.runAnnounced = true;
+    }
+    openRun(prompt, trigger) {
+        if (this.state && this.loopActive) {
+            this.state.runs++;
+            return;
+        }
+        if (this.state && !this.closing) {
+            // A record is open but its last loop already ended: set it aside and
+            // start a fresh one now. settleAll() decides whether that was right.
+            this.closing = { state: this.state, at: this.clock.now() };
+            this.state = undefined;
+        }
+        this.loopActive = true;
+        if (this.state) {
+            this.state.runs++;
+            return;
+        }
+        this.state = {
+            id: randomUUID(),
+            startedAt: this.clock.now(),
+            prompt,
+            ...(trigger !== undefined ? { trigger } : {}),
+            runs: 1,
+            turns: 0,
+            tools: {},
+            usage: emptyUsage(),
+            costObserved: false,
+            status: "completed",
+            waitingSpans: [],
+            openToolWaits: new Map(),
+            subagents: [],
+            openSubagents: new Map(),
+            segmentSpans: new Map(),
+            openSegments: new Map(),
+        };
+    }
+    onTurnEnd(usage) {
+        if (!this.state)
+            return;
+        this.state.turns++;
+        if (!usage)
+            return;
+        this.state.usage.input += finiteOrZero(usage.input);
+        this.state.usage.output += finiteOrZero(usage.output);
+        this.state.usage.cacheRead += finiteOrZero(usage.cacheRead);
+        this.state.usage.cacheWrite += finiteOrZero(usage.cacheWrite);
+        this.state.usage.cost += finiteOrZero(usage.cost);
+        // A real, finite cost figure (even an explicit 0) counts as "measured";
+        // an absent/non-finite one never un-sets a prior turn's observation.
+        if (typeof usage.cost === "number" && Number.isFinite(usage.cost)) {
+            this.state.costObserved = true;
+        }
+    }
+    onToolStart(toolCallId, toolName, args) {
+        if (!this.state)
+            return;
+        this.state.tools[toolName] = (this.state.tools[toolName] ?? 0) + 1;
+        const rule = this.segmentRules.find((candidate) => candidate.tool === toolName && candidate.pattern.test(segmentText(args)));
+        if (rule) {
+            const span = { start: this.clock.now(), end: undefined };
+            const spans = this.state.segmentSpans.get(rule.tag) ?? [];
+            spans.push(span);
+            this.state.segmentSpans.set(rule.tag, spans);
+            this.state.openSegments.set(toolCallId, span);
+        }
+        if (this.interactiveTools.has(toolName)) {
+            const span = { start: this.clock.now(), end: undefined };
+            this.state.waitingSpans.push(span);
+            this.state.openToolWaits.set(toolCallId, span);
+            return;
+        }
+        // SUBAGENT-REQ-001/005: a tool call opens a subagent span when its name
+        // matches ANY active profile's toolNames — generalised from the single
+        // hardcoded `subagentTool` string. `resolveToolProfile` resolves which
+        // SPECIFIC profile matched (for `readLaunchInfo`/attribution) without
+        // ever guessing when 2+ profiles share the same tool name (e.g.
+        // "subagent", registered by both the pi reference example and
+        // pi-subagents): the span still opens either way (a subagent tool call
+        // genuinely happened), with `profile` left undefined. C1: when
+        // genuinely ambiguous, agent/mode are read with `mergeAgreeingLaunchInfo`
+        // (kept only when every candidate that reports a value agrees) instead
+        // of `readLaunchInfo`'s first-defined-wins merge — this is purely
+        // descriptive (never money/join-affecting), but "agreeing" is still the
+        // more honest answer than silently picking one candidate's guess.
+        const { profile, candidates, ambiguous } = resolveToolProfile(this.subagentProfiles, toolName);
+        if (candidates.length > 0) {
+            const launch = ambiguous ? mergeAgreeingLaunchInfo(candidates, args) : readLaunchInfo(candidates, args);
+            this.state.openSubagents.set(toolCallId, {
+                toolCallId,
+                toolName,
+                agent: launch.agent ?? "unknown",
+                mode: launch.mode ?? "task",
+                profile: profile?.id,
+                start: this.clock.now(),
+            });
+        }
+    }
+    onToolEnd(toolCallId, result) {
+        if (!this.state)
+            return;
+        const openSegment = this.state.openSegments.get(toolCallId);
+        if (openSegment) {
+            this.state.openSegments.delete(toolCallId);
+            openSegment.end = this.clock.now();
+        }
+        const openSubagent = this.state.openSubagents.get(toolCallId);
+        if (openSubagent) {
+            // Consumed exactly once: a second onToolEnd for the same toolCallId
+            // (should never happen from a well-behaved pi runtime) finds nothing
+            // here and falls through — the guard that keeps SUBAGENT-REQ-006's
+            // usage forwarding below from ever double-attributing the same call.
+            this.state.openSubagents.delete(toolCallId);
+            const { ambiguous, candidates } = resolveToolProfile(this.subagentProfiles, openSubagent.toolName);
+            // C1 (CRITICAL fix, SUBAGENT-REQ-005/006): a genuinely ambiguous
+            // match (2+ profiles registered this tool name, never told apart)
+            // must never forward `usage` or `taskId` — see
+            // `subagent-profile.ts#safeAmbiguousResultInfo`'s doc comment for
+            // why. The unambiguous case keeps the existing best-effort merge
+            // (a no-op merge when there is exactly one candidate).
+            const resultInfo = ambiguous ? safeAmbiguousResultInfo(candidates, result) : readResultInfo(candidates, result);
+            // SUBAGENT-REQ-006 (revised by C1): forwarded usage is recorded on
+            // the SPAN itself as `forwardedUsage`, never folded into this
+            // record's own `usage` totals here — `domain/task-view.ts#buildTasks`
+            // (ADR 0006: aggregation across spans/children stays in exactly one
+            // place) is the only place that adds it to a task's total, and only
+            // for a span whose profile has no joined child record already
+            // carrying this same cost through its own confirmed-marker ancestry
+            // join (the writer-admitted "configured profile with both a marker
+            // AND usage forwarding" hole — see `buildConfiguredProfile`'s doc
+            // comment). `costObserved` is still set here, eagerly: a real cost
+            // figure genuinely WAS observed by this call, whether or not this
+            // specific number ends up in the final sum later.
+            const usage = resultInfo.usage;
+            if (usage && typeof usage.cost === "number" && Number.isFinite(usage.cost)) {
+                this.state.costObserved = true;
+            }
+            this.state.subagents.push({
+                toolCallId: openSubagent.toolCallId,
+                agent: openSubagent.agent,
+                mode: openSubagent.mode,
+                ...(resultInfo.taskId !== undefined ? { taskId: resultInfo.taskId } : {}),
+                ...(openSubagent.profile !== undefined ? { profile: openSubagent.profile } : {}),
+                // Clamped to >= 0: a backward clock jump while the subagent was
+                // running must never produce a negative duration.
+                ms: Math.max(0, this.clock.now() - openSubagent.start),
+                ...(usage !== undefined ? { forwardedUsage: usage } : {}),
+            });
+            return;
+        }
+        const openWaitingSpan = this.state.openToolWaits.get(toolCallId);
+        if (openWaitingSpan) {
+            this.state.openToolWaits.delete(toolCallId);
+            openWaitingSpan.end = this.clock.now();
+        }
+    }
+    onUiPromptStart(_kind) {
+        if (!this.state)
+            return;
+        this.state.waitingSpans.push({ start: this.clock.now(), end: undefined });
+    }
+    onUiPromptEnd(_kind) {
+        if (!this.state)
+            return;
+        // Prompts are sequential; close the most recently opened span (LIFO).
+        for (let i = this.state.waitingSpans.length - 1; i >= 0; i--) {
+            const span = this.state.waitingSpans[i];
+            if (span && span.end === undefined) {
+                span.end = this.clock.now();
+                return;
+            }
+        }
+    }
+    onRunEnd(messages) {
+        this.loopActive = false;
+        if (!this.state)
+            return;
+        const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+        if (lastAssistant?.stopReason === "aborted") {
+            this.state.status = "aborted";
+        }
+    }
+    /** Single-record convenience over {@link settleAll}; production code uses `settleAll`. */
+    onSettled() {
+        return this.settleAll()[0];
+    }
+    /**
+     * `agent_settled` arrived. Normally closes the one open record. When a
+     * record was set aside (see {@link closing}):
+     * - a loop is still running → the `agent_start` was a genuinely NEW run
+     *   that overtook this settle: close only the old record, at the instant
+     *   the new run began, and leave the new one open;
+     * - no loop is running → it was an `agent.continue()` of the same run
+     *   (retry, overflow recovery, queued message): fold it back, one record.
+     *   A user-announced prompt is never folded — it keeps its own record.
+     */
+    settleAll() {
+        const now = this.clock.now();
+        const closing = this.closing;
+        this.closing = undefined;
+        if (closing) {
+            if (this.loopActive && this.state) {
+                return [this.buildRecordFrom(closing.state, closing.state.status, closing.at)];
+            }
+            const fresh = this.state;
+            this.state = undefined;
+            this.runAnnounced = false;
+            this.loopActive = false;
+            if (!fresh)
+                return [this.buildRecordFrom(closing.state, closing.state.status, now)];
+            if (fresh.trigger === "extension") {
+                return [this.buildRecordFrom(mergeRunStates(closing.state, fresh), fresh.status !== "completed" ? fresh.status : closing.state.status, now)];
+            }
+            return [this.buildRecordFrom(closing.state, closing.state.status, closing.at), this.buildRecordFrom(fresh, fresh.status, now)];
+        }
+        // Settled with nothing set aside: whatever loop we believed active is over.
+        this.loopActive = false;
+        if (!this.state)
+            return [];
+        const record = this.buildRecordFrom(this.state, this.state.status, now);
+        this.state = undefined;
+        this.runAnnounced = false;
+        return [record];
+    }
+    /** Single-record convenience over {@link shutdownAll}. */
+    onShutdown() {
+        const all = this.shutdownAll();
+        return all[all.length - 1];
+    }
+    /** The session is going away: every open record is written, the running one as `interrupted`. */
+    shutdownAll() {
+        const now = this.clock.now();
+        const records = [];
+        if (this.closing && this.state) {
+            // ONE record, the same shape and id as the crash checkpoint (peek). Two
+            // separate records here double-billed: if the process died before the
+            // checkpoint was cleared, recovery re-appended the merged snapshot next
+            // to the new run's own record — overlapping cost under two ids, which
+            // no dedupe by id can see.
+            records.push(this.buildRecordFrom(mergeRunStates(this.closing.state, this.state), "interrupted", now));
+        }
+        else if (this.closing) {
+            records.push(this.buildRecordFrom(this.closing.state, this.closing.state.status, this.closing.at));
+        }
+        else if (this.state) {
+            records.push(this.buildRecordFrom(this.state, "interrupted", now));
+        }
+        this.closing = undefined;
+        this.state = undefined;
+        this.runAnnounced = false;
+        this.loopActive = false;
+        return records;
+    }
+    /**
+     * Returns what {@link onSettled}/{@link onShutdown} would produce right
+     * now, without mutating any state: open spans are truncated only in the
+     * returned snapshot, so the tracker keeps running unaffected and a later
+     * `peek` or the eventual settle still sees the spans' true open-ended
+     * state. `undefined` when idle. The returned `id` matches the id the
+     * eventual settled record will carry, since both are generated once
+     * in {@link onRunStart}.
+     */
+    peek(status) {
+        if (!this.state)
+            return undefined;
+        // A record set aside (see `closing`) is nowhere on disk yet: fold it into
+        // the snapshot so a crash before the settle cannot lose its time and
+        // cost. The snapshot keeps the set-aside record's id.
+        const state = this.closing ? mergeRunStates(this.closing.state, this.state) : this.state;
+        return this.buildRecordFrom(state, status, this.clock.now());
+    }
+    buildRecordFrom(state, status, settledAt) {
+        // Clamped to >= 0: a backward clock jump (system clock adjustment, NTP
+        // correction) must never produce a negative duration.
+        const wallMs = Math.max(0, settledAt - state.startedAt);
+        const closedSpans = state.waitingSpans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
+        const waitingMs = Math.max(0, unionMs(clampIntervals(closedSpans, state.startedAt, settledAt)));
+        const workMs = Math.max(0, wallMs - waitingMs);
+        const segmentEntries = [];
+        for (const [tag, spans] of state.segmentSpans) {
+            const closedTagSpans = spans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
+            const tagMs = Math.max(0, unionMs(clampIntervals(closedTagSpans, state.startedAt, settledAt)));
+            if (tagMs > 0) {
+                segmentEntries.push([tag, tagMs]);
+            }
+        }
+        // Built via Object.fromEntries (never `segments[tag] = ...`) so a tag
+        // such as `__proto__` becomes an own data property instead of silently
+        // repointing the object's prototype.
+        const segments = Object.fromEntries(segmentEntries);
+        return {
+            schema: WORK_RECORD_SCHEMA,
+            id: state.id,
+            prompt: state.prompt,
+            ...(state.trigger !== undefined ? { trigger: state.trigger } : {}),
+            startedAt: new Date(state.startedAt).toISOString(),
+            settledAt: new Date(settledAt).toISOString(),
+            wallMs,
+            waitingMs,
+            workMs,
+            runs: state.runs,
+            turns: state.turns,
+            tools: state.tools,
+            subagents: state.subagents,
+            segments,
+            usage: state.usage,
+            ...(state.costObserved ? { costObserved: true } : {}),
+            status,
+        };
+    }
+}
+/** Text to match a {@link SegmentRule} pattern against: the `command` string arg when present, else the whole args object as JSON. */
+function segmentText(args) {
+    const command = args?.["command"];
+    return typeof command === "string" ? command : JSON.stringify(args ?? {});
+}
+/** Fold a continuation's counters back into the record it continued. Additive only: nothing is ever dropped. */
+function mergeRunStates(base, continuation) {
+    const tools = { ...base.tools };
+    for (const [name, count] of Object.entries(continuation.tools)) {
+        tools[name] = (tools[name] ?? 0) + count;
+    }
+    const segmentSpans = new Map(base.segmentSpans);
+    for (const [tag, spans] of continuation.segmentSpans) {
+        segmentSpans.set(tag, [...(segmentSpans.get(tag) ?? []), ...spans]);
+    }
+    return {
+        ...base,
+        runs: base.runs + continuation.runs,
+        turns: base.turns + continuation.turns,
+        tools,
+        usage: {
+            input: base.usage.input + continuation.usage.input,
+            output: base.usage.output + continuation.usage.output,
+            cacheRead: base.usage.cacheRead + continuation.usage.cacheRead,
+            cacheWrite: base.usage.cacheWrite + continuation.usage.cacheWrite,
+            cost: base.usage.cost + continuation.usage.cost,
+        },
+        costObserved: base.costObserved || continuation.costObserved,
+        waitingSpans: [...base.waitingSpans, ...continuation.waitingSpans],
+        openToolWaits: new Map([...base.openToolWaits, ...continuation.openToolWaits]),
+        subagents: [...base.subagents, ...continuation.subagents],
+        openSubagents: new Map([...base.openSubagents, ...continuation.openSubagents]),
+        segmentSpans,
+        openSegments: new Map([...base.openSegments, ...continuation.openSegments]),
+    };
+}

package/dist/hub/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public library entrypoint (`kankaku-pi/hub`): the pi-free adapters that talk
+ * to the filesystem and the hub's HTTP layer, for a plain Node consumer
+ * that wants to read a worklog and/or sync it to the hub without pi. Every
+ * adapter that imports a pi package type is deliberately left out — see
+ * AGENTS.md "Architecture (hexagonal)" and odd/tasks/library-exports.md
+ * for which ones and why.
+ */
+export * from "../adapters/cached-catalog.ts";
+export * from "../adapters/export-writer.ts";
+export * from "../adapters/file-modes.ts";
+export * from "../adapters/hub-actions.ts";
+export * from "../adapters/hub-credentials.ts";
+export * from "../adapters/jsonl-work-log.ts";
+export * from "../adapters/kankaku-dir.ts";
+export * from "../adapters/lazy-jsonl-work-log.ts";
+export * from "../adapters/pocketbase-catalog.ts";
+export * from "../adapters/pocketbase-client.ts";
+export * from "../adapters/pocketbase-sink.ts";
+export * from "../adapters/project-config.ts";
+export * from "../adapters/report-data.ts";
+export * from "../adapters/report.ts";
+export * from "../adapters/report-views.ts";
+export * from "../adapters/sync-runner.ts";
+export * from "../adapters/sync-state-store.ts";

package/dist/hub/index.js

@@ -0,0 +1,25 @@
+/**
+ * Public library entrypoint (`kankaku-pi/hub`): the pi-free adapters that talk
+ * to the filesystem and the hub's HTTP layer, for a plain Node consumer
+ * that wants to read a worklog and/or sync it to the hub without pi. Every
+ * adapter that imports a pi package type is deliberately left out — see
+ * AGENTS.md "Architecture (hexagonal)" and odd/tasks/library-exports.md
+ * for which ones and why.
+ */
+export * from "../adapters/cached-catalog.js";
+export * from "../adapters/export-writer.js";
+export * from "../adapters/file-modes.js";
+export * from "../adapters/hub-actions.js";
+export * from "../adapters/hub-credentials.js";
+export * from "../adapters/jsonl-work-log.js";
+export * from "../adapters/kankaku-dir.js";
+export * from "../adapters/lazy-jsonl-work-log.js";
+export * from "../adapters/pocketbase-catalog.js";
+export * from "../adapters/pocketbase-client.js";
+export * from "../adapters/pocketbase-sink.js";
+export * from "../adapters/project-config.js";
+export * from "../adapters/report-data.js";
+export * from "../adapters/report.js";
+export * from "../adapters/report-views.js";
+export * from "../adapters/sync-runner.js";
+export * from "../adapters/sync-state-store.js";

package/dist/ports/catalog.d.ts

@@ -0,0 +1,31 @@
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+/** A cached read of the hub's clients/projects/tasks, plus when and against which hub URL it was fetched. */
+export interface CatalogSnapshot {
+    fetchedAt: number;
+    url: string;
+    clients: Client[];
+    projects: Project[];
+    /** Optional because a cache written by an older build (before hub task linking) never had this field; a missing value reads as "no tasks known yet." */
+    tasks?: HubTask[];
+}
+/**
+ * Read-only access to the hub catalog (clients/projects). `read()` is a
+ * synchronous, cheap access to the last known snapshot so session start
+ * never blocks on it; `refresh()` is the async network path. See
+ * `adapters/cached-catalog.ts` for the disk-backed implementation.
+ */
+export interface Catalog {
+    /** The last known snapshot, or `undefined` when none has ever been fetched or cached. */
+    read(): CatalogSnapshot | undefined;
+    /** `true` when there is no snapshot, or the cached one is older than the configured TTL. */
+    isStale(): boolean;
+    /**
+     * Fetch a fresh snapshot, cache it, and return it. Never throws; resolves
+     * `undefined` on failure. `signal`, when given, is composed with each
+     * underlying request's own per-request timeout (see
+     * `adapters/pocketbase-client.ts`) so a caller can bound the whole fetch
+     * (auth, pagination, retries) with one overall deadline; an abort is
+     * just another failure mode and also resolves `undefined`.
+     */
+    refresh(signal?: AbortSignal): Promise<CatalogSnapshot | undefined>;
+}

package/dist/ports/catalog.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/clock.d.ts

@@ -0,0 +1,3 @@
+export interface Clock {
+    now(): number;
+}

package/dist/ports/clock.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public library entrypoint (`kankaku-pi/ports`): the port interfaces, with
+ * no implementations. See AGENTS.md "Architecture (hexagonal)" and
+ * odd/tasks/library-exports.md.
+ */
+export type * from "./catalog.ts";
+export type * from "./clock.ts";
+export type * from "./inflight-store.ts";
+export type * from "./process-registry.ts";
+export type * from "./work-log.ts";
+export type * from "./work-sink.ts";

package/dist/ports/index.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/inflight-store.d.ts

@@ -0,0 +1,15 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+/**
+ * Crash-recovery checkpoint store: one process periodically saves the
+ * record its {@link WorkTracker} would produce right now, so a hard crash
+ * (kill -9, power loss) still leaves a record behind — recovered as
+ * `interrupted` on the next pi start rather than lost entirely.
+ */
+export interface InflightStore {
+    /** Upsert this process's checkpoint. */
+    save(record: WorkRecord): void;
+    /** Remove this process's checkpoint (normal settle/shutdown). */
+    clear(): void;
+    /** Return and delete every checkpoint whose owning pid is no longer alive. */
+    recoverStale(isAlive: (pid: number) => boolean): WorkRecord[];
+}

package/dist/ports/inflight-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/process-registry.d.ts

@@ -0,0 +1,72 @@
+import type { OrchestratorRef, WorkRole } from "../domain/work-record.ts";
+/**
+ * One machine-wide, live-process registry entry
+ * (`~/.kankaku/run/<pid>.json`, see `adapters/machine-process-registry.ts`),
+ * independent of any project's `KANKAKU_DIR` (ADR 0023). Written by every
+ * kankaku process at extension-factory time, so a later process (a child,
+ * possibly in another worktree) can discover it by walking its own OS
+ * ancestor chain.
+ */
+export interface RegistryEntry {
+    pid: number;
+    parentPid: number;
+    role: WorkRole;
+    /** This process's own cwd at the time it wrote this entry. A hint for matching, never a hard filter (ADR 0021). */
+    project: string;
+    /** Absolute, resolved `KANKAKU_DIR` for this process, so another process can read its `worklog.jsonl` directly without guessing at a shared relative directory name. */
+    dir: string;
+    startedAt: string;
+    /** The tracked ancestor this process itself discovered via the same registry, when any. */
+    orchestratorRef?: OrchestratorRef;
+    /**
+     * This process's own OS-reported start-time identity, as an
+     * approximate-but-self-consistent epoch-ms estimate (see
+     * `adapters/ancestry.ts`). Used to prove — not just guess by pid number
+     * — that a later reader's ancestor pid is still the *same* process
+     * instance this entry was written for, since the OS reuses pids
+     * (`domain/ancestry-match.ts#findAncestorEntry`). `undefined` when this
+     * process could not obtain it (Windows, or any read failure) — such an
+     * entry can never be trusted for identity matching and is swept as
+     * unverifiable (see `domain/registry-health.ts`).
+     */
+    processStartId?: number;
+}
+/** Extra, optional dependencies for {@link ProcessRegistry.record}'s opportunistic sweep. See `domain/registry-health.ts`. */
+export interface RegistrySweepDeps {
+    /** Live start identity for a pid, from the same ancestry snapshot this process already took at startup. `undefined` means "unknown" — such a pid is never swept as stale-by-reuse (fails safe). Defaults to always-unknown. */
+    liveStartId?: (pid: number) => number | undefined;
+    /** Defaults to `Date.now()`. Injectable for deterministic tests. */
+    now?: number;
+}
+/**
+ * Machine-wide registry of live (or recently-live) kankaku processes.
+ * Every operation is expected to degrade gracefully — an unavailable home
+ * directory or any filesystem failure yields an empty read / a no-op write
+ * rather than throwing, since this is an enhancement to subagent detection
+ * and must never block or crash the extension it improves.
+ */
+export interface ProcessRegistry {
+    /**
+     * Upsert this process's own entry, atomically. Also opportunistically
+     * sweeps entries the registry can no longer trust it should keep — dead
+     * pids, entries whose recorded identity no longer matches the live
+     * process holding that pid (pid reuse), entries with no verifiable
+     * identity at all (legacy/malformed), and entries older than a sane
+     * maximum age — so `run/` does not grow unbounded and never serves a
+     * stale identity (SUBAGENT-REQ-010, and the PID-reuse fix). Never
+     * removes the entry this call itself just wrote. Never throws.
+     */
+    record(entry: RegistryEntry, isAlive?: (pid: number) => boolean, sweepDeps?: RegistrySweepDeps): void;
+    /** Every currently-persisted entry, tolerating a corrupt/torn file by skipping it. Never throws; returns `[]` when the registry is unavailable. */
+    readAll(): RegistryEntry[];
+    /**
+     * Best-effort remove of this process's *own* entry file
+     * (`session_shutdown`, process `exit`). Reads the on-disk entry back
+     * first and only unlinks it when both `pid` and `processStartId` still
+     * match exactly what is on disk — so a file already overwritten by a
+     * pid-reuse successor (unlikely, but never assumed away) is never
+     * touched. Optional: an older `ProcessRegistry` implementation (e.g. a
+     * test fake) may omit it; callers must guard the call. Never throws.
+     */
+    removeOwn?(pid: number, processStartId: number | undefined): void;
+}

package/dist/ports/process-registry.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/work-log.d.ts

@@ -0,0 +1,14 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+export interface WorkLog {
+    append(record: WorkRecord): void;
+    readAll(): WorkRecord[];
+    /**
+     * Optional cheap change signal: a value that changes whenever `append()`
+     * would change what `readAll()` returns, computable without reading the
+     * whole log (e.g. from file stat metadata). Callers that cache a view
+     * derived from `readAll()` (see `pi-tracker.ts`'s client-name completion
+     * cache) may use this to invalidate cheaply; a `WorkLog` that omits it
+     * simply leaves such callers relying on their own explicit invalidation.
+     */
+    version?(): string | number;
+}

package/dist/ports/work-log.js

@@ -0,0 +1 @@
+export {};